ArangoDB Logo

ArangoDB v3.11 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent stable version.

HTTP interface for documents

The HTTP API for documents lets you create, read, update, and delete documents in collections, either one or multiple at a time

The basic operations for documents are mapped to the standard HTTP methods:

  • Create: POST
  • Read: GET
  • Update: PATCH (partially modify)
  • Replace: PUT
  • Delete: DELETE
  • Check: HEAD (test for existence and get document metadata)

Addresses of documents

Any document can be retrieved using its unique URI:

http://server:port/_api/document/<document-identifier>

For example, assuming that the document identifier is demo/362549736, then the URL of that document is:

http://localhost:8529/_api/document/demo/362549736

The above URL schema does not specify a database name explicitly, so the default _system database is used. To explicitly specify the database context, use the following URL schema:

http://server:port/_db/<database-name>/_api/document/<document-identifier>

For example, using a database called mydb:

http://localhost:8529/_db/mydb/_api/document/demo/362549736
Many examples in the documentation use the short URL format (and thus the _system database) for brevity.

Multiple documents in a single request

The document API can handle not only single documents but multiple documents in a single request. This is crucial for performance, in particular in the cluster situation, in which a single request can involve multiple network hops within the cluster. Another advantage is that it reduces the overhead of the HTTP protocol and individual network round trips between the client and the server. The general idea to perform multiple document operations in a single request is to use a JSON array of objects in the place of a single document. As a consequence, document keys, identifiers and revisions for preconditions have to be supplied embedded in the individual documents given. Multiple document operations are restricted to a single collection (document collection or edge collection).

Note that the GET, HEAD and DELETE HTTP operations generally do not allow to pass a message body. Thus, they cannot be used to perform multiple document operations in one request. However, there are alternative endpoints to request and delete multiple documents in one request.

Single document operations

Get a document

GET /_db/{database-name}/_api/document/{collection}/{key}

Returns the document identified by the collection name and document key. The returned document contains three special attributes:

  • _id, containing the document identifier with the format <collection-name>/<document-key>.
  • _key, containing the document key that uniquely identifies a document within the collection.
  • _rev, containing the document revision.
Path Parameters

  • The name of the database.

  • Name of the collection from which the document is to be read.

  • The document key.

Query Parameters
    HTTP Headers

    • If the If-None-Match header is given, then it must contain exactly one ETag. The document is returned, if it has a different revision than the given ETag. Otherwise an HTTP 304 is returned.

    • If the If-Match header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned.

    • Set this header to true to allow the Coordinator to ask any shard replica for the data, not only the shard leader. This may result in “dirty reads”.

      The header is ignored if this operation is part of a Stream Transaction (x-arango-trx-id header). The header set when creating the transaction decides about dirty reads for the entire transaction, not the individual read operations.

    • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

    Responses

    • The document has been found.

    • The If-None-Match header is specified and the document has the same revision.

    • The document or collection cannot be found.

      This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

    • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

    • An If-Match header is specified and the found document has a different revision. The response includes the found document’s current revision in the _rev attribute. Additionally, the _id and _key attributes are returned.

    Examples

    Use a document identifier:

    curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68419'
    Show output
    HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 76
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdQy--_"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_key" : "68419", 
  "_id" : "products/68419", 
  "_rev" : "_jt3ZdQy--_", 
  "hello" : "world" 
}

    Use a document identifier and an ETag:

    curl --header 'If-None-Match: "_jt3ZdRG--_"' --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68428'
    Show output
    HTTP/1.1 304 Not Modified
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdRG--_"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

    Unknown document identifier:

    curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/unknown-identifier'
    Show output
    HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 77
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "document not found", 
  "errorNum" : 1202 
}

    Get a document header

    HEAD /_db/{database-name}/_api/document/{collection}/{key}
    Like GET, but only returns the header fields and not the body. You can use this call to get the current revision of a document or check if the document was deleted.
    Path Parameters

    • The name of the database.

    • Name of the collection from which the document is to be read.

    • The document key.

    Query Parameters
      HTTP Headers

      • If the If-None-Match header is given, then it must contain exactly one ETag. If the current document revision is not equal to the specified ETag, an HTTP 200 response is returned. If the current document revision is identical to the specified ETag, then an HTTP 304 is returned.

      • If the If-Match header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned.

      • Set this header to true to allow the Coordinator to ask any shard replica for the data, not only the shard leader. This may result in “dirty reads”.

        The header is ignored if this operation is part of a Stream Transaction (x-arango-trx-id header). The header set when creating the transaction decides about dirty reads for the entire transaction, not the individual read operations.

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Responses

      • The document has been found.

      • An If-None-Match header is specified and the document has the same version.

      • The document or collection cannot be found.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      • An If-Match header is given and the found document has a different version. The response includes the found document’s current revision in the ETag header.

      Examples

      curl -X HEAD --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68444'
      Show output
      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 76
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdSe---"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

      Create a document

      POST /_db/{database-name}/_api/document/{collection}

      Creates a new document from the document given in the body, unless there is already a document with the _key given. If no _key is given, a new unique _key is generated automatically. The _id is automatically set in both cases, derived from the collection name and _key.

      An _id or _rev attribute specified in the body is ignored.

      If the document was created successfully, then the Location header contains the path to the newly created document. The ETag header field contains the revision of the document. Both are only set in the single document case.

      Unless silent is set to true, the body of the response contains a JSON object with the following attributes:

      • _id, containing the document identifier with the format <collection-name>/<document-key>.
      • _key, containing the document key that uniquely identifies a document within the collection.
      • _rev, containing the document revision.

      If the collection parameter waitForSync is false, then the call returns as soon as the document has been accepted. It does not wait until the documents have been synced to disk.

      Optionally, the query parameter waitForSync can be used to force synchronization of the document creation operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just this specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

      If the query parameter returnNew is true, then, for each generated document, the complete new document is returned under the new attribute in the result.

      Path Parameters

      • The name of the database.

      • Name of the collection in which the document is to be created.

      Query Parameters

      • The name of the collection. This query parameter is only for backward compatibility. In ArangoDB versions < 3.0, the URL path was /_api/document and this query parameter was required. This combination still works, but the recommended way is to specify the collection in the URL path.

      • Wait until document has been synced to disk.

      • Whether to additionally include the complete new document under the new attribute in the result.

      • Whether to additionally include the complete previous document under the old attribute in the result. Only available if the overwriteMode parameter is to "update" or "replace", or if overwrite is set to true.

      • If set to true, an empty object is returned as response if the document operation succeeds. No meta-data is returned for the created document. If the operation raises an error, an error object is returned.

        You can use this option to save network traffic.

      • If set to true, the insert becomes a replace-insert. If a document with the same _key already exists, the new document is not rejected with unique constraint violation error but replaces the old document. Note that operations with overwrite parameter require a _key attribute in the request payload, therefore they can only be performed on collections sharded by _key.

      • Possible values: "ignore", "replace", "update", "conflict"

        This option supersedes overwrite and offers the following modes:

        • "ignore": if a document with the specified _key value exists already, nothing is done and no write operation is carried out. The insert operation returns success in this case. This mode does not support returning the old document version using RETURN OLD. When using RETURN NEW, null is returned in case the document already existed.
        • "replace": if a document with the specified _key value exists already, it is overwritten with the specified document value. This mode is also used when no overwrite mode is specified but the overwrite flag is set to true.
        • "update": if a document with the specified _key value exists already, it is patched (partially updated) with the specified document value. The overwrite mode can be further controlled via the keepNull and mergeObjects parameters.
        • "conflict": if a document with the specified _key value exists already, return a unique constraint violation error so that the insert operation fails. This is also the default behavior in case the overwrite mode is not set, and the overwrite flag is false or not set either.

      • If the intention is to delete existing attributes with the update-insert command, set the keepNull query parameter to false. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of null (but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only.

      • Controls whether objects (not arrays) are merged if present in both, the existing and the update-insert document. If set to false, the value in the patch document overwrites the existing document’s value. If set to true, objects are merged. This option controls the update-insert behavior only.

      • Whether to add new entries to in-memory index caches if document insertions affect the edge index or cache-enabled persistent indexes.

      HTTP Headers

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Request Body application/json object
        A JSON representation of a single document.
      Responses

      • The document has been created successfully and waitForSync was true.

      • The document has been created successfully and waitForSync was false.

      • The request body does not contain a valid JSON representation of a document. The response body contains an error document in this case.

      • If the error code is 1004, the specified write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      • The collection cannot be found. The response body contains an error document in this case.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • There are two possible reasons for this error in the single document case:

        • A document with the same qualifiers in an indexed attribute conflicts with an already existing document and thus violates the unique constraint. The response body contains an error document with the errorNum set to 1210 (ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) in this case.
        • Locking the document key or some unique index entry failed to due to another concurrent operation that operates on the same document. This is also referred to as a write-write conflict. The response body contains an error document with the errorNum set to 1200 (ERROR_ARANGO_CONFLICT) in this case.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      • The system is temporarily not available. This can be a system overload or temporary failure. In this case it makes sense to retry the request later.

        If the error code is 1429, then the write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      Examples

      Create a document in a collection named products. Note that the revision identifier might or might not by equal to the auto-generated key.

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
{ "Hello": "World" }
EOF
      Show output
      HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 60
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdTu--_"
expires: 0
location: /_db/_system/_api/document/products/68453
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68453", 
  "_key" : "68453", 
  "_rev" : "_jt3ZdTu--_" 
}

      Create a document in a collection named products with a collection-level waitForSync value of false.

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
{ "Hello": "World" }
EOF
      Show output
      HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 60
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdUO--_"
expires: 0
location: /_db/_system/_api/document/products/68461
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68461", 
  "_key" : "68461", 
  "_rev" : "_jt3ZdUO--_" 
}

      Create a document in a collection with a collection-level waitForSync value of false, but using the waitForSync query parameter.

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products?waitForSync=true' <<'EOF'
{ "Hello": "World" }
EOF
      Show output
      HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 60
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdV---_"
expires: 0
location: /_db/_system/_api/document/products/68469
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68469", 
  "_key" : "68469", 
  "_rev" : "_jt3ZdV---_" 
}

      Unknown collection name

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
{ "Hello": "World" }
EOF
      Show output
      HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 97
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "collection or view not found: products", 
  "errorNum" : 1203 
}

      Illegal document

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
{ 1: "World" }
EOF
      Show output
      HTTP/1.1 400 Bad Request
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 97
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 400, 
  "error" : true, 
  "errorMessage" : "VPackError error: Expecting '\"' or '}'", 
  "errorNum" : 600 
}

      Use of returnNew:

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products?returnNew=true' <<'EOF'
{"Hello":"World"}
EOF
      Show output
      HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 143
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdXe---"
expires: 0
location: /_db/_system/_api/document/products/68484
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68484", 
  "_key" : "68484", 
  "_rev" : "_jt3ZdXe---", 
  "new" : { 
    "_key" : "68484", 
    "_id" : "products/68484", 
    "_rev" : "_jt3ZdXe---", 
    "Hello" : "World" 
  } 
}

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
{ "Hello": "World", "_key" : "lock" }
EOF

curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products?overwrite=true' <<'EOF'
{ "Hello": "Universe", "_key" : "lock" }
EOF
      Show output
      HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 58
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdY----"
expires: 0
location: /_db/_system/_api/document/products/lock
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/lock", 
  "_key" : "lock", 
  "_rev" : "_jt3ZdY----" 
}


HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 82
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdYO---"
expires: 0
location: /_db/_system/_api/document/products/lock
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/lock", 
  "_key" : "lock", 
  "_rev" : "_jt3ZdYO---", 
  "_oldRev" : "_jt3ZdY----" 
}

      Replace a document

      PUT /_db/{database-name}/_api/document/{collection}/{key}

      Replaces the specified document with the one in the body, provided there is such a document and no precondition is violated.

      The values of the _key, _id, and _rev system attributes as well as attributes used as sharding keys cannot be changed.

      If the If-Match header is specified and the revision of the document in the database is unequal to the given revision, the precondition is violated.

      If If-Match is not given and ignoreRevs is false and there is a _rev attribute in the body and its value does not match the revision of the document in the database, the precondition is violated.

      If a precondition is violated, an HTTP 412 is returned.

      If the document exists and can be updated, then an HTTP 201 or an HTTP 202 is returned (depending on waitForSync, see below), the ETag header field contains the new revision of the document and the Location header contains a complete URL under which the document can be queried.

      Cluster only: The replace documents may contain values for the collection’s pre-defined shard keys. Values for the shard keys are treated as hints to improve performance. Should the shard keys values be incorrect ArangoDB may answer with a not found error.

      Optionally, the query parameter waitForSync can be used to force synchronization of the document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

      Unless silent is set to true, the body of the response contains a JSON object with the following attributes:

      • _id, containing the document identifier with the format <collection-name>/<document-key>.
      • _key, containing the document key that uniquely identifies a document within the collection.
      • _rev, containing the new document revision.

      If the query parameter returnOld is true, then the complete previous revision of the document is returned under the old attribute in the result.

      If the query parameter returnNew is true, then the complete new document is returned under the new attribute in the result.

      If the document does not exist, then a HTTP 404 is returned and the body of the response contains an error document.

      Path Parameters

      • The name of the database.

      • Name of the collection in which the document is to be replaced.

      • The document key.

      Query Parameters

      • Wait until document has been synced to disk.

      • If set to true, the _rev attributes in the given document is ignored. If this is set to false, then the _rev attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified.

      • Whether to additionally include the complete previous document under the old attribute in the result.

      • Whether to additionally include the complete new document under the new attribute in the result.

      • If set to true, an empty object is returned as response if the document operation succeeds. No meta-data is returned for the replaced document. If the operation raises an error, an error object is returned.

        You can use this option to save network traffic.

      • Whether to update existing entries in in-memory index caches if documents replacements affect the edge index or cache-enabled persistent indexes.

      HTTP Headers

      • You can conditionally replace a document based on a target revision id by using the If-Match HTTP header.

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Request Body application/json object
        A JSON representation of a single document.
      Responses

      • The document has been replaced successfully and waitForSync was true.

      • The document has been replaced successfully and waitForSync was false.

      • The request body does not contain a valid JSON representation of a document. The response body contains an error document in this case.

      • If the error code is 1004, the specified write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      • The collection or the document was not found.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • There are two possible reasons for this error:

        • The replace operation causes a unique constraint violation in a secondary index. The response body contains an error document with the errorNum set to 1210 (ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) in this case.
        • Locking the document key or some unique index entry failed due to another concurrent operation that operates on the same document. This is also referred to as a write-write conflict. The response body contains an error document with the errorNum set to 1200 (ERROR_ARANGO_CONFLICT) in this case.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      • The precondition is violated. The response includes the found documents’ current revisions in the _rev attributes. Additionally, the attributes _id and _key are returned.

      • The system is temporarily not available. This can be a system overload or temporary failure. In this case it makes sense to retry the request later.

        If the error code is 1429, then the write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      Examples

      Using a document identifier

      curl -X PUT --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/68500' <<'EOF'
{"Hello": "you"}
EOF
      Show output
      HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 84
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdZO---"
expires: 0
location: /_db/_system/_api/document/products/68500
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68500", 
  "_key" : "68500", 
  "_rev" : "_jt3ZdZO---", 
  "_oldRev" : "_jt3ZdZK--_" 
}

      Unknown document identifier

      curl -X PUT --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/68509' <<'EOF'
{}
EOF
      Show output
      HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 77
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "document not found", 
  "errorNum" : 1202 
}

      Produce a revision conflict

      curl -X PUT --header 'If-Match: "_jt3Zdaa---"' --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/68519' <<'EOF'
{"other":"content"}
EOF
      Show output
      HTTP/1.1 412 Precondition Failed
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 152
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdaW--_"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : true, 
  "code" : 412, 
  "errorNum" : 1200, 
  "errorMessage" : "conflict, _rev values do not match", 
  "_id" : "products/68519", 
  "_key" : "68519", 
  "_rev" : "_jt3ZdaW--_" 
}

      Update a document

      PATCH /_db/{database-name}/_api/document/{collection}/{key}

      Partially updates the document identified by the document ID. The body of the request must contain a JSON document with the attributes to patch (the patch document). All attributes from the patch document are added to the existing document if they do not yet exist, and overwritten in the existing document if they do exist there.

      The values of the _key, _id, and _rev system attributes as well as attributes used as sharding keys cannot be changed.

      Setting an attribute value to null in the patch document causes a value of null to be saved for the attribute by default.

      If the If-Match header is specified and the revision of the document in the database is unequal to the given revision, the precondition is violated.

      If If-Match is not given and ignoreRevs is false and there is a _rev attribute in the body and its value does not match the revision of the document in the database, the precondition is violated.

      If a precondition is violated, an HTTP 412 is returned.

      If the document exists and can be updated, then an HTTP 201 or an HTTP 202 is returned (depending on waitForSync, see below), the ETag header field contains the new revision of the document (in double quotes) and the Location header contains a complete URL under which the document can be queried.

      Cluster only: The patch document may contain values for the collection’s pre-defined shard keys. Values for the shard keys are treated as hints to improve performance. Should the shard keys values be incorrect ArangoDB may answer with a not found error

      Optionally, the query parameter waitForSync can be used to force synchronization of the updated document operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

      Unless silent is set to true, the body of the response contains a JSON object with the following attributes:

      • _id, containing the document identifier with the format <collection-name>/<document-key>.
      • _key, containing the document key that uniquely identifies a document within the collection.
      • _rev, containing the new document revision.

      If the query parameter returnOld is true, then the complete previous revision of the document is returned under the old attribute in the result.

      If the query parameter returnNew is true, then the complete new document is returned under the new attribute in the result.

      If the document does not exist, then a HTTP 404 is returned and the body of the response contains an error document.

      Path Parameters

      • The name of the database.

      • Name of the collection in which the document is to be updated.

      • The document key.

      Query Parameters

      • If the intention is to delete existing attributes with the patch command, set the keepNull query parameter to false. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of null (but not attributes of objects that are nested inside of arrays).

      • Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to false, the value in the patch document overwrites the existing document’s value. If set to true, objects are merged.

      • Wait until document has been synced to disk.

      • If set to true, the _rev attributes in the given document is ignored. If this is set to false, then the _rev attribute given in the body document is taken as a precondition. The document is only updated if the current revision is the one specified.

      • Whether to additionally include the complete previous document under the old attribute in the result.

      • Whether to additionally include the complete new document under the new attribute in the result.

      • If set to true, an empty object is returned as response if the document operation succeeds. No meta-data is returned for the updated document. If the operation raises an error, an error object is returned.

        You can use this option to save network traffic.

      • Whether to update existing entries in in-memory index caches if document updates affect the edge index or cache-enabled persistent indexes.

      HTTP Headers

      • You can conditionally update a document based on a target revision id by using the If-Match HTTP header.

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Request Body application/json object
        A JSON representation of a (partial) document.
      Responses

      • The document has been updated successfully and waitForSync was true.

      • The document has been updated successfully and waitForSync was false.

      • The request body does not contain a valid JSON representation of a document. The response body contains an error document in this case.

      • If the error code is 1004, the specified write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      • The document or collection cannot be found.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • There are two possible reasons for this error:

        • The update causes a unique constraint violation in a secondary index. The response body contains an error document with the errorNum set to 1210 (ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) in this case.
        • Locking the document key or some unique index entry failed due to another concurrent operation that operates on the same document. This is also referred to as a write-write conflict. The response body contains an error document with the errorNum set to 1200 (ERROR_ARANGO_CONFLICT) in this case.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      • The precondition was violated. The response also contains the found documents’ current revisions in the _rev attributes. Additionally, the attributes _id and _key are returned.

      • The system is temporarily not available. This can be a system overload or temporary failure. In this case it makes sense to retry the request later.

        If the error code is 1429, then the write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      Examples

      Patches an existing document with new content.

      curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/68531' <<'EOF'
{
  "hello": "world"
}
EOF

curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/68531' <<'EOF'
{
  "numbers": {
    "one": 1,
    "two": 2,
    "three": 3,
    "empty": null
  }
}
EOF

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68531'

curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/68531?keepNull=false' <<'EOF'
{
  "hello": null,
  "numbers": {
    "four": 4
  }
}
EOF

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68531'
      Show output
      HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 84
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3Zdbe--A"
expires: 0
location: /_db/_system/_api/document/products/68531
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68531", 
  "_key" : "68531", 
  "_rev" : "_jt3Zdbe--A", 
  "_oldRev" : "_jt3Zdbe--_" 
}


HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 84
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3Zdbi---"
expires: 0
location: /_db/_system/_api/document/products/68531
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68531", 
  "_key" : "68531", 
  "_rev" : "_jt3Zdbi---", 
  "_oldRev" : "_jt3Zdbe--A" 
}


HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 141
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3Zdbi---"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_key" : "68531", 
  "_id" : "products/68531", 
  "_rev" : "_jt3Zdbi---", 
  "one" : "world", 
  "hello" : "world", 
  "numbers" : { 
    "one" : 1, 
    "two" : 2, 
    "three" : 3, 
    "empty" : null 
  } 
}


HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 84
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3Zdbm---"
expires: 0
location: /_db/_system/_api/document/products/68531
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68531", 
  "_key" : "68531", 
  "_rev" : "_jt3Zdbm---", 
  "_oldRev" : "_jt3Zdbi---" 
}


HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 134
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3Zdbm---"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_key" : "68531", 
  "_id" : "products/68531", 
  "_rev" : "_jt3Zdbm---", 
  "one" : "world", 
  "numbers" : { 
    "one" : 1, 
    "two" : 2, 
    "three" : 3, 
    "empty" : null, 
    "four" : 4 
  } 
}

      Merging attributes of an object using mergeObjects:

      curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68544'

curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/68544?mergeObjects=true' <<'EOF'
{
  "inhabitants": {
    "indonesia": 252164800,
    "brazil": 203553000
  }
}
EOF

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68544'

curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/68544?mergeObjects=false' <<'EOF'
{
  "inhabitants": {
    "pakistan": 188346000
  }
}
EOF

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68544'
      Show output
      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 130
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdcW--_"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_key" : "68544", 
  "_id" : "products/68544", 
  "_rev" : "_jt3ZdcW--_", 
  "inhabitants" : { 
    "china" : 1366980000, 
    "india" : 1263590000, 
    "usa" : 319220000 
  } 
}


HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 171
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3Zdca---"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_key" : "68544", 
  "_id" : "products/68544", 
  "_rev" : "_jt3Zdca---", 
  "inhabitants" : { 
    "china" : 1366980000, 
    "india" : 1263590000, 
    "usa" : 319220000, 
    "brazil" : 203553000, 
    "indonesia" : 252164800 
  } 
}


HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 84
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3Zdce---"
expires: 0
location: /_db/_system/_api/document/products/68544
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68544", 
  "_key" : "68544", 
  "_rev" : "_jt3Zdce---", 
  "_oldRev" : "_jt3Zdca---" 
}


HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 97
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3Zdce---"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_key" : "68544", 
  "_id" : "products/68544", 
  "_rev" : "_jt3Zdce---", 
  "inhabitants" : { 
    "pakistan" : 188346000 
  } 
}

      Remove a document

      DELETE /_db/{database-name}/_api/document/{collection}/{key}

      Unless silent is set to true, the body of the response contains a JSON object with the following attributes:

      • _id, containing the document identifier with the format <collection-name>/<document-key>.
      • _key, containing the document key that uniquely identifies a document within the collection.
      • _rev, containing the document revision.

      If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

      If the query parameter returnOld is true, then the complete previous revision of the document is returned under the old attribute in the result.

      Path Parameters

      • The name of the database.

      • Name of the collection in which the document is to be deleted.

      • The document key.

      Query Parameters

      • Wait until deletion operation has been synced to disk.

      • Whether to additionally include the complete previous document under the old attribute in the result.

      • If set to true, an empty object is returned as response if the document operation succeeds. No meta-data is returned for the deleted document. If the operation raises an error, an error object is returned.

        You can use this option to save network traffic.

      • Whether to delete existing entries from in-memory index caches and refill them if document removals affect the edge index or cache-enabled persistent indexes.

      HTTP Headers

      • You can conditionally remove a document based on a target revision id by using the If-Match HTTP header.

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Responses

      • The document has been removed successfully and waitForSync was true.

      • The document has been removed successfully and waitForSync was false.

      • If the error code is 1004, the specified write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      • The document or collection cannot be found. The response body contains an error document in this case.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • Locking the document key failed due to another concurrent operation that operates on the same document. This is also referred to as a write-write conflict. The response body contains an error document with the errorNum set to 1200 (ERROR_ARANGO_CONFLICT) in this case.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      • An If-Match header is specified and the found document has a different version. The response includes the found document’s current revision in the _rev attribute. Additionally, the attributes _id and _key are returned.

      • The system is temporarily not available. This can be a system overload or temporary failure. In this case it makes sense to retry the request later.

        If the error code is 1429, then the write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      Examples

      Using document identifier:

      curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68557'
      Show output
      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 60
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3Zddu--_"
expires: 0
location: /_db/_system/_api/document/products/68557
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "_id" : "products/68557", 
  "_key" : "68557", 
  "_rev" : "_jt3Zddu--_" 
}

      Unknown document identifier:

      curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68566'
      Show output
      HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 77
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "document not found", 
  "errorNum" : 1202 
}

      Revision conflict:

      curl -X DELETE --header 'If-Match: "_jt3ZdfW--A"' --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68576'
      Show output
      HTTP/1.1 412 Precondition Failed
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 152
content-security-policy: frame-ancestors 'self'; form-action 'self';
etag: "_jt3ZdfW--_"
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : true, 
  "code" : 412, 
  "errorNum" : 1200, 
  "errorMessage" : "conflict, _rev values do not match", 
  "_id" : "products/68576", 
  "_key" : "68576", 
  "_rev" : "_jt3ZdfW--_" 
}

      Document ETags

      ArangoDB tries to adhere to the existing HTTP standard as far as possible. To this end, results of single document queries have the ETag HTTP header set to the document revision (the value of _rev document attribute) enclosed in double quotes.

      You can check the revision of a document using the HEAD HTTP method.

      If you want to query, replace, update, replace, or delete a document, then you can use the If-Match header to detect conflicts. If the document has changed, the operation is aborted and an HTTP 412 Precondition failed status code is returned.

      If you obtain a document using GET and you want to check whether a newer revision is available, then you can use the If-None-Match HTTP header. If the document is unchanged (same document revision), an HTTP 412 Precondition failed status code is returned.

      Multiple document operations

      ArangoDB supports working with documents in bulk. Bulk operations affect a single collection. Using this API variant allows clients to amortize the overhead of single requests over an entire batch of documents. Bulk operations are not guaranteed to be executed serially, ArangoDB may execute the operations in parallel. This can translate into large performance improvements especially in a cluster deployment.

      ArangoDB continues to process the remaining operations should an error occur during the processing of one operation. Errors are returned inline in the response body as an error document (see below for more details). Additionally, the X-Arango-Error-Codes header is set. It contains a map of the error codes and how often each kind of error occurred. For example, 1200:17,1205:10 means that in 17 cases the error 1200 (“revision conflict”) has happened, and in 10 cases the error 1205 (“illegal document handle”).

      Generally, the bulk operations expect an input array and the result body contains a JSON array of the same length.

      Get multiple documents

      PUT /_db/{database-name}/_api/document/{collection}
      The endpoint for getting multiple documents is the same as for replacing multiple documents but with an additional query parameter: PUT /_api/document/{collection}?onlyget=true. This is because a lot of software does not support payload bodies in GET requests.

      Returns the documents identified by their _key attribute. The body of the request must contain a JSON array of either strings (the _key values to look up) or search documents.

      A search document must contain at least a value for the _key field. A value for _rev may be specified to verify whether the document has the same revision value, unless ignoreRevs is set to false.

      Cluster only: The search document may contain values for the collection’s pre-defined shard keys. Values for the shard keys are treated as hints to improve performance. Should the shard keys values be incorrect ArangoDB may answer with a not found error.

      The returned array of documents contain three special attributes:

      • _id, containing the document identifier with the format <collection-name>/<document-key>.
      • _key, containing the document key that uniquely identifies a document within the collection.
      • _rev, containing the document revision.
      Path Parameters

      • The name of the database.

      • Name of the collection from which the documents are to be read.

      Query Parameters

      • This parameter is required to be true, otherwise a replace operation is executed!

      • If set to false and a _rev attribute is included in the request, then the document is only returned if it has the same revision. Otherwise, a precondition failed error is returned for the document.

      HTTP Headers

      • Set this header to true to allow the Coordinator to ask any shard replica for the data, not only the shard leader. This may result in “dirty reads”.

        The header is ignored if this operation is part of a Stream Transaction (x-arango-trx-id header). The header set when creating the transaction decides about dirty reads for the entire transaction, not the individual read operations.

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Request Body application/json

      • An array of documents to retrieve.

      Responses

      • No error occurred for the overall operation.

      • The request body does not contain a valid JSON representation of an array of documents.

      • The collection cannot be found.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      Examples

      Reading multiple documents identifier:

      curl -X PUT --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products?onlyget=true' <<'EOF'
["doc1", {"_key":"doc2"}]
EOF
      Show output
      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 153
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "_key" : "doc1", 
    "_id" : "products/doc1", 
    "_rev" : "_jt3ZdgO---", 
    "hello" : "world" 
  }, 
  { 
    "_key" : "doc2", 
    "_id" : "products/doc2", 
    "_rev" : "_jt3ZdgO--_", 
    "say" : "hi to mom" 
  } 
]

      Create multiple documents

      POST /_db/{database-name}/_api/document/{collection}

      Creates new documents from the documents given in the body, unless there is already a document with the _key given. If no _key is given, a new unique _key is generated automatically. The _id is automatically set in both cases, derived from the collection name and _key.

      The result body contains a JSON array of the same length as the input array, and each entry contains the result of the operation for the corresponding input. In case of an error the entry is a document with attributes error set to true and errorCode set to the error code that has happened.

      Any _id or _rev attribute specified in the body is ignored.

      Unless silent is set to true, the body of the response contains an array of JSON objects with the following attributes:

      • _id, containing the document identifier with the format <collection-name>/<document-key>.
      • _key, containing the document key that uniquely identifies a document within the collection.
      • _rev, containing the document revision.

      If the collection parameter waitForSync is false, then the call returns as soon as the documents have been accepted. It does not wait until the documents have been synced to disk.

      Optionally, the query parameter waitForSync can be used to force synchronization of the document creation operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just this specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

      If the query parameter returnNew is true, then, for each generated document, the complete new document is returned under the new attribute in the result.

      Should an error have occurred with some of the documents, the X-Arango-Error-Codes HTTP header is set. It contains a map of the error codes and how often each kind of error occurred. For example, 1200:17,1205:10 means that in 17 cases the error 1200 (“revision conflict”) has happened, and in 10 cases the error 1205 (“illegal document handle”).

      Path Parameters

      • The name of the database.

      • Name of the collection in which the documents are to be created.

      Query Parameters

      • The name of the collection. This is only for backward compatibility. In ArangoDB versions < 3.0, the URL path was /_api/document and this query parameter was required. This combination still works, but the recommended way is to specify the collection in the URL path.

      • Wait until document has been synced to disk.

      • Whether to additionally include the complete new document under the new attribute in the result.

      • Whether to additionally include the complete previous document under the old attribute in the result. Only available if the overwriteMode parameter is to "update" or "replace", or if overwrite is set to true.

      • If set to true, an empty object is returned as response if all document operations succeed. No meta-data is returned for the created documents. If any of the operations raises an error, an array with the error object(s) is returned.

        You can use this option to save network traffic but you cannot map any errors to the inputs of your request.

      • If set to true, the insert becomes a replace-insert. If a document with the same _key already exists, the new document is not rejected with a unique constraint violation error but replaces the old document. Note that operations with overwrite parameter require a _key attribute in the request payload, therefore they can only be performed on collections sharded by _key.

      • Possible values: "ignore", "replace", "update", "conflict"

        This option supersedes overwrite and offers the following modes:

        • "ignore": if a document with the specified _key value exists already, nothing is done and no write operation is carried out. The insert operation returns success in this case. This mode does not support returning the old document version using RETURN OLD. When using RETURN NEW, null is returned in case the document already existed.
        • "replace": if a document with the specified _key value exists already, it is overwritten with the specified document value. This mode is also used when no overwrite mode is specified but the overwrite flag is set to true.
        • "update": if a document with the specified _key value exists already, it is patched (partially updated) with the specified document value. The overwrite mode can be further controlled via the keepNull and mergeObjects parameters.
        • "conflict": if a document with the specified _key value exists already, return a unique constraint violation error so that the insert operation fails. This is also the default behavior in case the overwrite mode is not set, and the overwrite flag is false or not set either.

      • If the intention is to delete existing attributes with the update-insert command, set the keepNull query parameter to false. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of null (but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only.

      • Controls whether objects (not arrays) are merged if present in both, the existing and the update-insert document. If set to false, the value in the patch document overwrites the existing document’s value. If set to true, objects are merged. This option controls the update-insert behavior only.

      • Whether to add new entries to in-memory index caches if document insertions affect the edge index or cache-enabled persistent indexes.

      HTTP Headers

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Request Body application/json

      • An array of documents to create.

      Responses

      • The individual operations have been processed and waitForSync was true.

      • The individual operations have been processed and waitForSync was false.

      • The request body does not contain a valid JSON representation of an array of documents.

      • If the error code is 1004, the specified write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      • The document or collection cannot be found. The response body contains an error document in this case.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      • The system is temporarily not available. This can be a system overload or temporary failure. In this case it makes sense to retry the request later.

        If the error code is 1429, then the write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      Examples

      Insert multiple documents:

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
[{"Hello":"Earth"}, {"Hello":"Venus"}, {"Hello":"Mars"}]
EOF
      Show output
      HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 184
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "_id" : "products/68597", 
    "_key" : "68597", 
    "_rev" : "_jt3ZdhO---" 
  }, 
  { 
    "_id" : "products/68598", 
    "_key" : "68598", 
    "_rev" : "_jt3ZdhO--_" 
  }, 
  { 
    "_id" : "products/68599", 
    "_key" : "68599", 
    "_rev" : "_jt3ZdhO--A" 
  } 
]

      Use of returnNew:

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products?returnNew=true' <<'EOF'
[{"Hello":"Earth"}, {"Hello":"Venus"}, {"Hello":"Mars"}]
EOF
      Show output
      HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 432
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "_id" : "products/68607", 
    "_key" : "68607", 
    "_rev" : "_jt3Zdh6--_", 
    "new" : { 
      "_key" : "68607", 
      "_id" : "products/68607", 
      "_rev" : "_jt3Zdh6--_", 
      "Hello" : "Earth" 
    } 
  }, 
  { 
    "_id" : "products/68608", 
    "_key" : "68608", 
    "_rev" : "_jt3Zdh6--A", 
    "new" : { 
      "_key" : "68608", 
      "_id" : "products/68608", 
      "_rev" : "_jt3Zdh6--A", 
      "Hello" : "Venus" 
    } 
  }, 
  { 
    "_id" : "products/68609", 
    "_key" : "68609", 
    "_rev" : "_jt3Zdh6--B", 
    "new" : { 
      "_key" : "68609", 
      "_id" : "products/68609", 
      "_rev" : "_jt3Zdh6--B", 
      "Hello" : "Mars" 
    } 
  } 
]

      Partially illegal documents:

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
[{ "_key": 111 }, {"_key":"abc"}]
EOF
      Show output
      HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 127
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-error-codes: {"1221":1}
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "error" : true, 
    "errorNum" : 1221, 
    "errorMessage" : "illegal document key" 
  }, 
  { 
    "_id" : "products/abc", 
    "_key" : "abc", 
    "_rev" : "_jt3Zdim---" 
  } 
]

      Replace multiple documents

      PUT /_db/{database-name}/_api/document/{collection}

      Replaces multiple documents in the specified collection with the ones in the body, the replaced documents are specified by the _key attributes in the body documents.

      The values of the _key, _id, and _rev system attributes as well as attributes used as sharding keys cannot be changed.

      If ignoreRevs is false and there is a _rev attribute in a document in the body and its value does not match the revision of the corresponding document in the database, the precondition is violated.

      Cluster only: The replace documents may contain values for the collection’s pre-defined shard keys. Values for the shard keys are treated as hints to improve performance. Should the shard keys values be incorrect ArangoDB may answer with a not found error.

      Optionally, the query parameter waitForSync can be used to force synchronization of the document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

      The body of the response contains a JSON array of the same length as the input array with the information about the identifier and the revision of the replaced documents. In each element has the following attributes:

      • _id, containing the document identifier with the format <collection-name>/<document-key>.
      • _key, containing the document key that uniquely identifies a document within the collection.
      • _rev, containing the new document revision.

      In case of an error or violated precondition, an error object with the attribute error set to true and the attribute errorCode set to the error code is built.

      If the query parameter returnOld is true, then, for each generated document, the complete previous revision of the document is returned under the old attribute in the result.

      If the query parameter returnNew is true, then, for each generated document, the complete new document is returned under the new attribute in the result.

      Note that if any precondition is violated or an error occurred with some of the documents, the return code is still 201 or 202, but the X-Arango-Error-Codes HTTP header is set. It contains a map of the error codes and how often each kind of error occurred. For example, 1200:17,1205:10 means that in 17 cases the error 1200 (“revision conflict”) has happened, and in 10 cases the error 1205 (“illegal document handle”).

      Path Parameters

      • The name of the database.

      • This URL parameter is the name of the collection in which the documents are replaced.

      Query Parameters

      • Wait until the new documents have been synced to disk.

      • If set to true, the _rev attributes in the given documents are ignored. If this is set to false, then any _rev attribute given in a body document is taken as a precondition. The document is only replaced if the current revision is the one specified.

      • Whether to additionally include the complete previous document under the old attribute in the result.

      • Whether to additionally include the complete new document under the new attribute in the result.

      • If set to true, an empty object is returned as response if all document operations succeed. No meta-data is returned for the replaced documents. If at least one operation raises an error, an array with the error object(s) is returned.

        You can use this option to save network traffic but you cannot map any errors to the inputs of your request.

      • Whether to update existing entries in in-memory index caches if documents replacements affect the edge index or cache-enabled persistent indexes.

      HTTP Headers

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Request Body application/json

      • An array of documents. Each element has to contain a _key attribute. The existing documents with matching document keys are replaced.

      Responses

      • The individual operations have been processed and waitForSync was true.

      • The individual operations have been processed and waitForSync was false.

      • The request body does not contain a valid JSON representation of an array of documents.

      • If the error code is 1004, the specified write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      • The collection cannot be found.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      • The system is temporarily not available. This can be a system overload or temporary failure. In this case it makes sense to retry the request later.

        If the error code is 1429, then the write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      Update multiple documents

      PATCH /_db/{database-name}/_api/document/{collection}

      Partially updates documents, the documents to update are specified by the _key attributes in the body objects. The body of the request must contain a JSON array of document updates with the attributes to patch (the patch documents). All attributes from the patch documents are added to the existing documents if they do not yet exist, and overwritten in the existing documents if they do exist there.

      The values of the _key, _id, and _rev system attributes as well as attributes used as sharding keys cannot be changed.

      Setting an attribute value to null in the patch documents causes a value of null to be saved for the attribute by default.

      If ignoreRevs is false and there is a _rev attribute in a document in the body and its value does not match the revision of the corresponding document in the database, the precondition is violated.

      Cluster only: The patch document may contain values for the collection’s pre-defined shard keys. Values for the shard keys are treated as hints to improve performance. Should the shard keys values be incorrect ArangoDB may answer with a not found error

      Optionally, the query parameter waitForSync can be used to force synchronization of the document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

      The body of the response contains a JSON array of the same length as the input array with the information about the identifier and the revision of the updated documents. Each element has the following attributes:

      • _id, containing the document identifier with the format <collection-name>/<document-key>.
      • _key, containing the document key that uniquely identifies a document within the collection.
      • _rev, containing the new document revision.

      In case of an error or violated precondition, an error object with the attribute error set to true and the attribute errorCode set to the error code is built.

      If the query parameter returnOld is true, then, for each generated document, the complete previous revision of the document is returned under the old attribute in the result.

      If the query parameter returnNew is true, then, for each generated document, the complete new document is returned under the new attribute in the result.

      Note that if any precondition is violated or an error occurred with some of the documents, the return code is still 201 or 202, but the X-Arango-Error-Codes HTTP header is set. It contains a map of the error codes and how often each kind of error occurred. For example, 1200:17,1205:10 means that in 17 cases the error 1200 (“revision conflict”) has happened, and in 10 cases the error 1205 (“illegal document handle”).

      Path Parameters

      • The name of the database.

      • Name of the collection in which the documents are to be updated.

      Query Parameters

      • If the intention is to delete existing attributes with the patch command, set the keepNull query parameter to false. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of null (but not attributes of objects that are nested inside of arrays).

      • Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to false, the value in the patch document overwrites the existing document’s value. If set to true, objects are merged.

      • Wait until the new documents have been synced to disk.

      • If set to true, the _rev attributes in the given documents are ignored. If this is set to false, then any _rev attribute given in a body document is taken as a precondition. The document is only updated if the current revision is the one specified.

      • Whether to additionally include the complete previous document under the old attribute in the result.

      • Whether to additionally include the complete new document under the new attribute in the result.

      • If set to true, an empty object is returned as response if all document operations succeed. No meta-data is returned for the updated documents. If at least one operation raises an error, an array with the error object(s) is returned.

        You can use this option to save network traffic but you cannot map any errors to the inputs of your request.

      • Whether to update existing entries in in-memory index caches if document updates affect the edge index or cache-enabled persistent indexes.

      HTTP Headers

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Request Body application/json

      • An array of partial documents representing the desired updates. Each element has to contain a _key attribute. The existing documents with matching document keys are updated.

      Responses

      • The individual operations have been processed and waitForSync was true.

      • The individual operations have been processed and waitForSync was false.

      • The request body does not contain a valid JSON representation of an array of documents.

      • If the error code is 1004, the specified write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      • The collection cannot be found.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      • The system is temporarily not available. This can be a system overload or temporary failure. In this case it makes sense to retry the request later.

        If the error code is 1429, then the write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      Remove multiple documents

      DELETE /_db/{database-name}/_api/document/{collection}

      The body of the request is an array consisting of selectors for documents. A selector can either be a string with a key or a string with a document identifier or an object with a _key attribute. This API call removes all specified documents from collection. If the ignoreRevs query parameter is false and the selector is an object and has a _rev attribute, it is a precondition that the actual revision of the removed document in the collection is the specified one.

      The body of the response is an array of the same length as the input array. For each input selector, the output contains a JSON object with the information about the outcome of the operation. If no error occurred, then such an object has the following attributes:

      • _id, containing the document identifier with the format <collection-name>/<document-key>.
      • _key, containing the document key that uniquely identifies a document within the collection.
      • _rev, containing the document revision. In case of an error, the object has the error attribute set to true and errorCode set to the error code.

      If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

      If the query parameter returnOld is true, then the complete previous revision of the document is returned under the old attribute in the result.

      Note that if any precondition is violated or an error occurred with some of the documents, the return code is still 200 or 202, but the X-Arango-Error-Codes HTTP header is set. It contains a map of the error codes and how often each kind of error occurred. For example, 1200:17,1205:10 means that in 17 cases the error 1200 (“revision conflict”) has happened, and in 10 cases the error 1205 (“illegal document handle”).

      Path Parameters

      • The name of the database.

      • Collection from which documents are removed.

      Query Parameters

      • Wait until deletion operation has been synced to disk.

      • Whether to additionally include the complete previous document under the old attribute in the result.

      • If set to true, an empty object is returned as response if all document operations succeed. No meta-data is returned for the deleted documents. If at least one of the operations raises an error, an array with the error object(s) is returned.

        You can use this option to save network traffic but you cannot map any errors to the inputs of your request.

      • If set to true, ignore any _rev attribute included in the request. No revision check is performed. If set to false, then revisions are checked.

      • Whether to delete existing entries from in-memory index caches and refill them if document removals affect the edge index or cache-enabled persistent indexes.

      HTTP Headers

      • To make this operation a part of a Stream Transaction, set this header to the transaction ID returned by the POST /_api/transaction/begin call.

      Request Body application/json

      • An array of document selectors. A selector can be a string (document key or identifier) or an object that has to contain a _key attribute with the document key.

      Responses

      • The individual operations have been processed and waitForSync was true.

      • The individual operations have been processed and waitForSync was false.

      • If the error code is 1004, the specified write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      • The collection cannot be found. The response body contains an error document in this case.

        This error also occurs if you try to run this operation as part of a Stream Transaction but the transaction ID specified in the x-arango-trx-id header is unknown to the server.

      • This error occurs if you try to run this operation as part of a Stream Transaction that has just been canceled or timed out.

      • The system is temporarily not available. This can be a system overload or temporary failure. In this case it makes sense to retry the request later.

        If the error code is 1429, then the write concern for the collection cannot be fulfilled. This can happen if less than the number of specified replicas for a shard are currently in-sync with the leader. For example, if the write concern is 2 and the replication factor is 3, then the write concern is not fulfilled if two replicas are not in-sync.

        Note that the HTTP status code is configurable via the --cluster.failed-write-concern-status-code startup option. It defaults to 403 but can be changed to 503 to signal client applications that it is a temporary error.

      Examples

      Using document keys:

      curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
[
  "1",
  "2"
]
EOF
      Show output
      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 107
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "_id" : "products/1", 
    "_key" : "1", 
    "_rev" : "_jt3ZdkG--_" 
  }, 
  { 
    "_id" : "products/2", 
    "_key" : "2", 
    "_rev" : "_jt3ZdkG--A" 
  } 
]

      Using document identifiers:

      curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
[
  "products/1",
  "products/2"
]
EOF
      Show output
      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 107
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "_id" : "products/1", 
    "_key" : "1", 
    "_rev" : "_jt3Zdk6--_" 
  }, 
  { 
    "_id" : "products/2", 
    "_key" : "2", 
    "_rev" : "_jt3Zdk6--A" 
  } 
]

      Using objects with document keys:

      curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
[
  {
    "_key": "1"
  },
  {
    "_key": "2"
  }
]
EOF
      Show output
      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 107
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "_id" : "products/1", 
    "_key" : "1", 
    "_rev" : "_jt3ZdmC--_" 
  }, 
  { 
    "_id" : "products/2", 
    "_key" : "2", 
    "_rev" : "_jt3ZdmC--A" 
  } 
]

      Unknown documents:

      curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
[
  "1",
  "other/2"
]
EOF
      Show output
      HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 135
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-error-codes: {"1202":2}
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "error" : true, 
    "errorNum" : 1202, 
    "errorMessage" : "document not found" 
  }, 
  { 
    "error" : true, 
    "errorNum" : 1202, 
    "errorMessage" : "document not found" 
  } 
]

      Check revisions:

      curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products?ignoreRevs=false' <<'EOF'
[
  {
    "_key": "1",
    "_rev": "_jt3Zdn6---"
  },
  {
    "_key": "2",
    "_rev": "_jt3Zdn6--_"
  }
]
EOF
      Show output
      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 107
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "_id" : "products/1", 
    "_key" : "1", 
    "_rev" : "_jt3Zdn6---" 
  }, 
  { 
    "_id" : "products/2", 
    "_key" : "2", 
    "_rev" : "_jt3Zdn6--_" 
  } 
]

      Revision conflict:

      curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products?ignoreRevs=false' <<'EOF'
[
  {
    "_key": "1",
    "_rev": "non-matching revision"
  },
  {
    "_key": "2",
    "_rev": "non-matching revision"
  }
]
EOF
      Show output
      HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 167
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-error-codes: {"1200":2}
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "error" : true, 
    "errorNum" : 1200, 
    "errorMessage" : "conflict, _rev values do not match" 
  }, 
  { 
    "error" : true, 
    "errorNum" : 1200, 
    "errorMessage" : "conflict, _rev values do not match" 
  } 
]

      Read from followers

      ArangoDB Enterprise Edition ArangoGraph

      Introduced in: v3.10.0

      In an ArangoDB cluster, all reads and writes are performed via the shard leaders. Shard replicas replicate all operations, but are only on hot standby to take over in case of a failure. This is to ensure consistency of reads and writes and allows giving a certain amount of transactional guarantees.

      If high throughput is more important than consistency and transactional guarantees for you, then you may allow for so-called “dirty reads” or “reading from followers”, for certain read-only operations. In this case, Coordinators are allowed to read not only from leader shards but also from follower shards. This has a positive effect, because the reads can scale out to all DB-Servers which have copies of the data. Therefore, the read throughput is higher. Note however, that you still have to go through your Coordinators. To get the desired result, you have to have enough Coordinators, load balance your client requests across all of them, and then allow reads from followers.

      You may observe the following data inconsistencies (dirty reads) when reading from followers:

      • It is possible to see old, obsolete revisions of documents. More exactly, it is possible that documents are already updated on the leader shard but the updates have not yet been replicated to the follower shard from which you are reading.

      • It is also possible to see changes to documents that have already happened on a replica, but are not yet officially committed on the leader shard.

      When no writes are happening, allowing reading from followers is generally safe.

      The following APIs support reading from followers:

      • Single document reads (GET /_api/document and HEAD /_api/document)
      • Batch document reads (PUT /_api/document?onlyget=true)
      • Read-only AQL queries (POST /_api/cursor)
      • The edge API (GET /_api/edges)
      • Read-only Stream Transactions and their sub-operations (POST /_api/transaction/begin etc.)

      The following APIs do not support reading from followers:

      • The graph API (GET /_api/gharial etc.)
      • JavaScript Transactions (POST /_api/transaction)

      You need to set the following HTTP header in API requests to ask for reads from followers:

      x-arango-allow-dirty-read: true

      This is in line with the older support to read from followers in the Active Failover deployment mode.

      For single requests, you specify this header in the read request. For Stream Transactions, the header has to be set on the request that creates a read-only transaction.

      The POST /_api/cursor endpoint also supports a query option that you can set instead of the HTTP header:

      { "query": "...", "options": { "allowDirtyReads": true } }

      Every response to a request that could produce dirty reads has the following HTTP header:

      x-arango-potential-dirty-read: true

      On this page