Doc update (#571)

Author: jwierzbo

collection_documents.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2017 ArangoDB GmbH, Cologne, Germany
+// Copyright 2017-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -17,8 +17,6 @@
 //
 // Copyright holder is ArangoDB GmbH, Cologne, Germany
 //
-// Author Ewout Prangsma
-//
 
 package driver
 
@@ -67,6 +65,7 @@ type CollectionDocuments interface {
 	// To return the OLD document, prepare a context with `WithReturnOld`.
 	// To wait until document has been synced to disk, prepare a context with `WithWaitForSync`.
 	// If no document exists with given key, a NotFoundError is returned.
+	// If `_id` field is present in the document body, it is always ignored.
 	UpdateDocument(ctx context.Context, key string, update interface{}) (DocumentMeta, error)
 
 	// UpdateDocuments updates multiple document with given keys in the collection.
@@ -75,7 +74,8 @@ type CollectionDocuments interface {
 	// To return the OLD documents, prepare a context with `WithReturnOld` with a slice of documents.
 	// To wait until documents has been synced to disk, prepare a context with `WithWaitForSync`.
 	// If no document exists with a given key, a NotFoundError is returned at its errors index.
-	// If keys is nil, each element in the updates slice must contain a `_key` field.
+	// If keys are nil, each element in the update slice must contain a `_key` field.
+	// If `_id` field is present in the document body, it is always ignored.
 	UpdateDocuments(ctx context.Context, keys []string, updates interface{}) (DocumentMetaSlice, ErrorSlice, error)
 
 	// ReplaceDocument replaces a single document with given key in the collection with the document given in the document argument.
@@ -84,6 +84,7 @@ type CollectionDocuments interface {
 	// To return the OLD document, prepare a context with `WithReturnOld`.
 	// To wait until document has been synced to disk, prepare a context with `WithWaitForSync`.
 	// If no document exists with given key, a NotFoundError is returned.
+	// If `_id` field is present in the document body, it is always ignored.
 	ReplaceDocument(ctx context.Context, key string, document interface{}) (DocumentMeta, error)
 
 	// ReplaceDocuments replaces multiple documents with given keys in the collection with the documents given in the documents argument.
@@ -93,6 +94,7 @@ type CollectionDocuments interface {
 	// To wait until documents has been synced to disk, prepare a context with `WithWaitForSync`.
 	// If no document exists with a given key, a NotFoundError is returned at its errors index.
 	// If keys is nil, each element in the documents slice must contain a `_key` field.
+	// If `_id` field is present in the document body, it is always ignored.
 	ReplaceDocuments(ctx context.Context, keys []string, documents interface{}) (DocumentMetaSlice, ErrorSlice, error)
 
 	// RemoveDocument removes a single document with given key from the collection.

examples/example_client_test.go

@@ -56,11 +56,13 @@ func ExampleNewClient() {
 	fmt.Printf("Database has version '%s' and license '%s'\n", versionInfo.Version, versionInfo.License)
 }
 
-// ExampleNewClientWithAuthentication shows how to create the client with custom connection configuration
+// ExampleNewConnection shows how to create the client with custom connection configuration
+// If there is more than one endpoint, the client will pick the first one that works and use it till it fails.
+// Then it will try the next one.
 func ExampleNewConnection() {
 	// Create an HTTP connection to the database
 	conn, err := drviverHttp.NewConnection(drviverHttp.ConnectionConfig{
-		Endpoints: []string{"http://localhost:8529"},
+		Endpoints: []string{"http://localhost:8529", "http://localhost:8539"},
 		Transport: NewConnectionTransport(),
 	})
 	if err != nil {

http/connection.go

@@ -54,6 +54,8 @@ const (
 type ConnectionConfig struct {
 	// Endpoints holds 1 or more URL's used to connect to the database.
 	// In case of a connection to an ArangoDB cluster, you must provide the URL's of all coordinators.
+	// If there is more than one endpoint, the client will pick the first one that works and use it till it fails.
+	// Then it will try the next one
 	Endpoints []string
 	// TLSConfig holds settings used to configure a TLS (HTTPS) connection.
 	// This is only used for endpoints using the HTTPS scheme.

v2/arangodb/collection_documents_replace.go

@@ -33,22 +33,26 @@ type CollectionDocumentReplace interface {
 
 	// ReplaceDocument replaces a single document with given key in the collection.
 	// If no document exists with given key, a NotFoundError is returned.
+	// If `_id` field is present in the document body, it is always ignored.
 	ReplaceDocument(ctx context.Context, key string, document interface{}) (CollectionDocumentReplaceResponse, error)
 
 	// ReplaceDocumentWithOptions replaces a single document with given key in the collection.
 	// If no document exists with given key, a NotFoundError is returned.
+	// If `_id` field is present in the document body, it is always ignored.
 	ReplaceDocumentWithOptions(ctx context.Context, key string, document interface{}, options *CollectionDocumentReplaceOptions) (CollectionDocumentReplaceResponse, error)
 
 	// ReplaceDocuments replaces multiple document with given keys in the collection.
 	// The replaces are loaded from the given replaces slice, the documents metadata are returned.
 	// If no document exists with a given key, a NotFoundError is returned at its errors index.
 	// Each element in the replaces slice must contain a `_key` field.
+	// If `_id` field is present in the document body, it is always ignored.
 	ReplaceDocuments(ctx context.Context, documents interface{}) (CollectionDocumentReplaceResponseReader, error)
 
 	// ReplaceDocumentsWithOptions replaces multiple document with given keys in the collection.
 	// The replaces are loaded from the given replaces slice, the documents metadata are returned.
 	// If no document exists with a given key, a NotFoundError is returned at its errors index.
 	// Each element in the replaces slice must contain a `_key` field.
+	// If `_id` field is present in the document body, it is always ignored.
 	ReplaceDocumentsWithOptions(ctx context.Context, documents interface{}, opts *CollectionDocumentReplaceOptions) (CollectionDocumentReplaceResponseReader, error)
 }
 

v2/arangodb/collection_documents_update.go

@@ -30,27 +30,30 @@ import (
 // CollectionDocumentUpdate Partially updates document(s) with given key in the collection.
 // https://www.arangodb.com/docs/devel/http/document.html#update-a-document
 type CollectionDocumentUpdate interface {
-
-	// UpdateDocument updates a single document with given key in the collection.
+	// UpdateDocument updates a single document with a given key in the collection.
 	// The document metadata is returned.
-	// If no document exists with given key, a NotFoundError is returned.
+	// If no document exists with a given key, a NotFoundError is returned.
+	// If `_id` field is present in the document body, it is always ignored.
 	UpdateDocument(ctx context.Context, key string, document interface{}) (CollectionDocumentUpdateResponse, error)
 
-	// UpdateDocumentWithOptions updates a single document with given key in the collection.
+	// UpdateDocumentWithOptions updates a single document with a given key in the collection.
 	// The document metadata is returned.
-	// If no document exists with given key, a NotFoundError is returned.
+	// If no document exists with a given key, a NotFoundError is returned.
+	// If `_id` field is present in the document body, it is always ignored.
 	UpdateDocumentWithOptions(ctx context.Context, key string, document interface{}, options *CollectionDocumentUpdateOptions) (CollectionDocumentUpdateResponse, error)
 
 	// UpdateDocuments updates multiple documents
 	// The updates are loaded from the given updates slice, the documents metadata are returned.
 	// If no document exists with a given key, a NotFoundError is returned at its errors index.
-	// Each element in the updates slice must contain a `_key` field.
+	// Each element in the update slice must contain a `_key` field.
+	// If `_id` field is present in the document body, it is always ignored.
 	UpdateDocuments(ctx context.Context, documents interface{}) (CollectionDocumentUpdateResponseReader, error)
 
 	// UpdateDocumentsWithOptions updates multiple documents
 	// The updates are loaded from the given updates slice, the documents metadata are returned.
 	// If no document exists with a given key, a NotFoundError is returned at its errors index.
-	// Each element in the updates slice must contain a `_key` field.
+	// Each element in the update slice must contain a `_key` field.
+	// If `_id` field is present in the document body, it is always ignored.
 	UpdateDocumentsWithOptions(ctx context.Context, documents interface{}, opts *CollectionDocumentUpdateOptions) (CollectionDocumentUpdateResponseReader, error)
 }