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
_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
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.
x-arango-allow-dirty-read boolean
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.
Examples
Use a document identifier:
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/68990'
Use a document identifier and an ETag:
curl --header 'If-None-Match: "_iXQtAhW--_"' --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/69002'
Unknown document identifier:
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/unknown-identifier'
Get a document header
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.If-None-Match string
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.
x-arango-allow-dirty-read boolean
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.
Examples
curl -X HEAD --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/69015'
Create a document
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
.
_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.
overwrite boolean
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 withoverwrite
parameter require a_key
attribute in the request payload, therefore they can only be performed on collections sharded by_key
.overwriteMode string
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 usingRETURN OLD
. When usingRETURN 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 theoverwrite
flag is set totrue
."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 thekeepNull
andmergeObjects
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 theoverwrite
flag isfalse
or not set either.
keepNull boolean
If the intention is to delete existing attributes with the update-insert command, set the
keepNull
URL query parameter tofalse
. 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 ofnull
(but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only.mergeObjects boolean
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 totrue
, objects are merged. The default istrue
. This option controls the update-insert behavior only.versionAttribute string
Only applicable if
overwrite
is set totrue
oroverwriteMode
is set toupdate
orreplace
.You can use the
versionAttribute
option for external versioning support. If set, the attribute with the name specified by the option is looked up in the stored document and the attribute value is compared numerically to the value of the versioning attribute in the supplied document that is supposed to update/replace it.If the version number in the new document is higher (rounded down to a whole number) than in the document that already exists in the database, then the update/replace operation is performed normally. This is also the case if the new versioning attribute has a non-numeric value, if it is a negative number, or if the attribute doesn’t exist in the supplied or stored document.
If the version number in the new document is lower or equal to what exists in the database, the operation is not performed and the existing document thus not changed. No error is returned in this case.
The attribute can only be a top-level attribute.
You can check if
_oldRev
(if present) and_rev
are different to determine if the document has been changed.
- A JSON representation of a single document.
403 Forbidden
with the error code
1004
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.409 Conflict
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 to1210
(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 to1200
(ERROR_ARANGO_CONFLICT
) in this 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
503 Service Unavailable
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
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
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
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
Unknown collection name
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
{ "Hello": "World" }
EOF
Illegal document
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
{ 1: "World" }
EOF
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
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
Replace a document
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.
versionAttribute string
You can use the
versionAttribute
option for external versioning support. If set, the attribute with the name specified by the option is looked up in the stored document and the attribute value is compared numerically to the value of the versioning attribute in the supplied document that is supposed to replace it.If the version number in the new document is higher (rounded down to a whole number) than in the document that already exists in the database, then the replace operation is performed normally. This is also the case if the new versioning attribute has a non-numeric value, if it is a negative number, or if the attribute doesn’t exist in the supplied or stored document.
If the version number in the new document is lower or equal to what exists in the database, the operation is not performed and the existing document thus not changed. No error is returned in this case.
The attribute can only be a top-level attribute.
You can check if
_oldRev
and_rev
are different to determine if the document has been changed.
- A JSON representation of a single document.
403 Forbidden
with the error code
1004
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.409 Conflict
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 to1210
(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 to1200
(ERROR_ARANGO_CONFLICT
) in this case.
- The replace operation causes a unique constraint violation in a secondary
index. The response body contains an error document with the
503 Service Unavailable
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
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/69092' <<'EOF'
{"Hello": "you"}
EOF
Unknown document identifier
curl -X PUT --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/69104' <<'EOF'
{}
EOF
Produce a revision conflict
curl -X PUT --header 'If-Match: "_iXQtAr6--A"' --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/69117' <<'EOF'
{"other":"content"}
EOF
Update a document
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.
keepNull boolean
If the intention is to delete existing attributes with the patch command, set the
keepNull
URL query parameter tofalse
. 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 ofnull
(but not attributes of objects that are nested inside of arrays).versionAttribute string
You can use the
versionAttribute
option for external versioning support. If set, the attribute with the name specified by the option is looked up in the stored document and the attribute value is compared numerically to the value of the versioning attribute in the supplied document that is supposed to update it.If the version number in the new document is higher (rounded down to a whole number) than in the document that already exists in the database, then the update operation is performed normally. This is also the case if the new versioning attribute has a non-numeric value, if it is a negative number, or if the attribute doesn’t exist in the supplied or stored document.
If the version number in the new document is lower or equal to what exists in the database, the operation is not performed and the existing document thus not changed. No error is returned in this case.
The attribute can only be a top-level attribute.
You can check if
_oldRev
and_rev
are different to determine if the document has been changed.
- A JSON representation of a (partial) document.
403 Forbidden
with the error code
1004
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.409 Conflict
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 to1210
(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 to1200
(ERROR_ARANGO_CONFLICT
) in this case.
- The update causes a unique constraint violation in a secondary index.
The response body contains an error document with the
503 Service Unavailable
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
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/69132' <<'EOF'
{
"hello": "world"
}
EOF
curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/69132' <<'EOF'
{
"numbers": {
"one": 1,
"two": 2,
"three": 3,
"empty": null
}
}
EOF
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/69132'
curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/69132?keepNull=false' <<'EOF'
{
"hello": null,
"numbers": {
"four": 4
}
}
EOF
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/69132'
Merging attributes of an object using mergeObjects
:
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/69148'
curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/69148?mergeObjects=true' <<'EOF'
{
"inhabitants": {
"indonesia": 252164800,
"brazil": 203553000
}
}
EOF
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/69148'
curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products/69148?mergeObjects=false' <<'EOF'
{
"inhabitants": {
"pakistan": 188346000
}
}
EOF
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/69148'
Remove a document
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.
403 Forbidden
with the error code
1004
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.503 Service Unavailable
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
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/69164'
Unknown document identifier:
curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/69176'
Revision conflict:
curl -X DELETE --header 'If-Match: "_iXQtAzW---"' --header 'accept: application/json' --dump - 'http://localhost:8529/_api/document/products/69189'
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 /_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
in the body objects.
The body of the request must contain a JSON array of either
strings (the _key
values to lookup) 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.
x-arango-allow-dirty-read boolean
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.
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
Create multiple documents
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.
_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”).
silent boolean
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.
overwrite boolean
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 withoverwrite
parameter require a_key
attribute in the request payload, therefore they can only be performed on collections sharded by_key
.overwriteMode string
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 usingRETURN OLD
. When usingRETURN 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 theoverwrite
flag is set totrue
."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 thekeepNull
andmergeObjects
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 theoverwrite
flag isfalse
or not set either.
keepNull boolean
If the intention is to delete existing attributes with the update-insert command, set the
keepNull
URL query parameter tofalse
. 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 ofnull
(but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only.mergeObjects boolean
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 totrue
, objects are merged. The default istrue
. This option controls the update-insert behavior only.versionAttribute string
Only applicable if
overwrite
is set totrue
oroverwriteMode
is set toupdate
orreplace
.You can use the
versionAttribute
option for external versioning support. If set, the attribute with the name specified by the option is looked up in the stored document and the attribute value is compared numerically to the value of the versioning attribute in the supplied document that is supposed to update/replace it.If the version number in the new document is higher (rounded down to a whole number) than in the document that already exists in the database, then the update/replace operation is performed normally. This is also the case if the new versioning attribute has a non-numeric value, if it is a negative number, or if the attribute doesn’t exist in the supplied or stored document.
If the version number in the new document is lower or equal to what exists in the database, the operation is not performed and the existing document thus not changed. No error is returned in this case.
The attribute can only be a top-level attribute.
You can check if
_oldRev
(if present) and_rev
are different to determine if the document has been changed.
403 Forbidden
with the error code
1004
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.503 Service Unavailable
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
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
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
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
Replace multiple documents
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”).
silent boolean
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.
versionAttribute string
You can use the
versionAttribute
option for external versioning support. If set, the attribute with the name specified by the option is looked up in the stored document and the attribute value is compared numerically to the value of the versioning attribute in the supplied document that is supposed to replace it.If the version number in the new document is higher (rounded down to a whole number) than in the document that already exists in the database, then the replace operation is performed normally. This is also the case if the new versioning attribute has a non-numeric value, if it is a negative number, or if the attribute doesn’t exist in the supplied or stored document.
If the version number in the new document is lower or equal to what exists in the database, the operation is not performed and the existing document thus not changed. No error is returned in this case.
The attribute can only be a top-level attribute.
You can check if
_oldRev
and_rev
are different to determine if the document has been changed.
403 Forbidden
with the error code
1004
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.503 Service Unavailable
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.
Update multiple documents
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”).
keepNull boolean
If the intention is to delete existing attributes with the patch command, set the
keepNull
URL query parameter tofalse
. 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 ofnull
(but not attributes of objects that are nested inside of arrays).silent boolean
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.
versionAttribute string
You can use the
versionAttribute
option for external versioning support. If set, the attribute with the name specified by the option is looked up in the stored document and the attribute value is compared numerically to the value of the versioning attribute in the supplied document that is supposed to update it.If the version number in the new document is higher (rounded down to a whole number) than in the document that already exists in the database, then the update operation is performed normally. This is also the case if the new versioning attribute has a non-numeric value, if it is a negative number, or if the attribute doesn’t exist in the supplied or stored document.
If the version number in the new document is lower or equal to what exists in the database, the operation is not performed and the existing document thus not changed. No error is returned in this case.
The attribute can only be a top-level attribute.
You can check if
_oldRev
and_rev
are different to determine if the document has been changed.
403 Forbidden
with the error code
1004
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.503 Service Unavailable
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.
Remove multiple documents
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 theerror
attribute set totrue
anderrorCode
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”).
silent boolean
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.
403 Forbidden
with the error code
1004
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
to signal client applications that it is a temporary error.503 Service Unavailable
is returned if 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 is2
and the replication factor is3
, 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 to403
but can be changed to503
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
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
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
Unknown documents:
curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products' <<'EOF'
[
"1",
"other/2"
]
EOF
Check revisions:
curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/document/products?ignoreRevs=false' <<'EOF'
[
{
"_key": "1",
"_rev": "_iXQtA9G---"
},
{
"_key": "2",
"_rev": "_iXQtA9G--_"
}
]
EOF
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
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
andHEAD /_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
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