ArangoDB v3.13 is under development and not released yet. This documentation is not final and potentially incomplete.

HTTP interface for collections

The HTTP API for collections lets you create and delete collections, get information about collections, and modify certain properties of existing collections

Addresses of collections

All collections in ArangoDB have a unique identifier and a unique name. To access a collection, use the collection name to refer to it:

http://server:port/_api/collection/<collection-name>

For example, assume that the collection identifier is 7254820 and the collection name is demo, then the URL of that collection is:

http://localhost:8529/_api/collection/demo

Get information about collections

List all collections

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

Returns basic information for all collections in the current database, optionally excluding system collections.

Path Parameters

database-name* string
The name of the database.

Query Parameters

excludeSystem boolean
Whether system collections should be excluded from the result.

HTTP Headers

Responses

200 OK
The list of collections.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
- result* array of objects
  A list with every item holding basic collection metadata.
  globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
  id* string
  A unique identifier of the collection (deprecated).
  isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
  name* string
  The name of the collection.
  status* integer
  The status of the collection.
  3: loaded
  5: deleted
  Every other status indicates a corrupted collection.
  type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection

Examples

Return information about all collections:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection

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: 1641
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

{ 
  "error" : false, 
  "code" : 200, 
  "result" : [ 
    { 
      "id" : "4", 
      "name" : "_statistics", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_statistics" 
    }, 
    { 
      "id" : "10", 
      "name" : "_queues", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_queues" 
    }, 
    { 
      "id" : "12", 
      "name" : "_apps", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_apps" 
    }, 
    { 
      "id" : "64926", 
      "name" : "mycollection", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : false, 
      "globallyUniqueId" : "h7F0F0D5E4468/64926" 
    }, 
    { 
      "id" : "11", 
      "name" : "_jobs", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_jobs" 
    }, 
    { 
      "id" : "165", 
      "name" : "demo", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : false, 
      "globallyUniqueId" : "h7F0F0D5E4468/165" 
    }, 
    { 
      "id" : "171", 
      "name" : "animals", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : false, 
      "globallyUniqueId" : "h7F0F0D5E4468/171" 
    }, 
    { 
      "id" : "3", 
      "name" : "_users", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_users" 
    }, 
    { 
      "id" : "9", 
      "name" : "_aqlfunctions", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_aqlfunctions" 
    }, 
    { 
      "id" : "7", 
      "name" : "_graphs", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_graphs" 
    }, 
    { 
      "id" : "13", 
      "name" : "_appbundles", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_appbundles" 
    }, 
    { 
      "id" : "8", 
      "name" : "_analyzers", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_analyzers" 
    }, 
    { 
      "id" : "14", 
      "name" : "_frontend", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_frontend" 
    }, 
    { 
      "id" : "5", 
      "name" : "_statistics15", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_statistics15" 
    }, 
    { 
      "id" : "160", 
      "name" : "ignore", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : false, 
      "globallyUniqueId" : "h7F0F0D5E4468/160" 
    }, 
    { 
      "id" : "6", 
      "name" : "_statisticsRaw", 
      "status" : 3, 
      "type" : 2, 
      "isSystem" : true, 
      "globallyUniqueId" : "_statisticsRaw" 
    } 
  ] 
}

Get the collection information

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

Returns the basic information about a specific collection.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

HTTP Headers

Responses

200 OK
The basic information about a collection.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- name* string
  The name of the collection.
- status* integer
  The status of the collection.
  3: loaded
  5: deleted
  Every other status indicates a corrupted collection.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
404 Not Found
The specified collection is unknown.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  The ArangoDB error number for the error that occurred.

Get the properties of a collection

GET /_db/{database-name}/_api/collection/{collection-name}/properties

Returns all properties of the specified collection.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

HTTP Headers

Responses

200 OK
All the collection properties.
- cacheEnabled* boolean
  Whether the in-memory hash cache for documents is enabled for this collection.
- code* integer
  The HTTP response status code.
- computedValues* array of objects
  A list of objects, each representing a computed value.
  computeOn array of strings
  An array of strings that defines on which write operations the value is computed.
  Possible values: "insert", "update", "replace"
  expression* string
  An AQL RETURN operation with an expression that computes the desired value.
  failOnWarning boolean
  Whether the write operation fails if the expression produces a warning.
  keepNull boolean
  Whether the target attribute is set if the expression evaluates to null.
  name* string
  The name of the target attribute.
  overwrite* boolean
  Whether the computed value takes precedence over a user-provided or existing attribute.
- distributeShardsLike string
  The name of another collection. This collection uses the replicationFactor, numberOfShards and shardingStrategy properties of the other collection and the shards of this collection are distributed in the same way as the shards of the other collection.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isDisjoint boolean
  Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint (Enterprise Edition only). This is an internal property. (cluster only)
- isSmart boolean
  Whether the collection is used in a SmartGraph or EnterpriseGraph (Enterprise Edition only). This is an internal property. (cluster only)
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- keyOptions* object
  An object which contains key generation options.
  allowUserKeys* boolean
  If set to true, then you are allowed to supply own key values in the _key attribute of a document. If set to false, then the key generator is solely responsible for generating keys and an error is raised if you supply own key values in the _key attribute of documents.
  You should not use both user-specified and automatically generated document keys in the same collection in cluster deployments for collections with more than a single shard. Mixing the two can lead to conflicts because Coordinators that auto-generate keys in this case are not aware of all keys which are already used.
  increment integer
  The increment value for the autoincrement key generator. Not used by other key generator types.
  lastValue integer
  The offset value of the autoincrement or padded key generator. This is an internal property for restoring dumps properly.
  offset integer
  The initial offset value for the autoincrement key generator. Not used by other key generator types.
  type* string
  Specifies the type of the key generator. Possible values:
  "traditional"
  "autoincrement"
  "uuid"
  "padded"
- name* string
  The name of this collection.
- numberOfShards integer
  The number of shards of the collection. (cluster only)
- replicationFactor integer
  Contains how many copies of each shard are kept on different DB-Servers. It is an integer number in the range of 1-10 or the string "satellite" for SatelliteCollections (Enterprise Edition only). (cluster only)
- schema* object
  An object that specifies the collection-level schema for documents.
- shardKeys array of strings
  Contains the names of document attributes that are used to determine the target shard for documents. (cluster only)
- shardingStrategy string
  The sharding strategy selected for the collection. (cluster only)
  Possible values:
  "community-compat"
  "enterprise-compat"
  "enterprise-smart-edge-compat"
  "hash"
  "enterprise-hash-smart-edge"
  "enterprise-hex-smart-vertex"
- smartGraphAttribute string
  The attribute that is used for sharding: vertices with the same value of this attribute are placed in the same shard. All vertices are required to have this attribute set and it has to be a string. Edges derive the attribute from their connected vertices (Enterprise Edition only). (cluster only)
- smartJoinAttribute string
  Determines an attribute of the collection that must contain the shard key value of the referred-to SmartJoin collection (Enterprise Edition only). (cluster only)
- syncByRevision* boolean
  Whether the newer revision-based replication protocol is enabled for this collection. This is an internal property.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
- waitForSync* boolean
  If true, creating, changing, or removing documents waits until the data has been synchronized to disk.
- writeConcern integer
  Determines how many copies of each shard are required to be in-sync on the different DB-Servers. If there are less than these many copies in the cluster, a shard refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern cannot be greater than replicationFactor.
  If distributeShardsLike is set, the default writeConcern is that of the prototype collection. For SatelliteCollections, the writeConcern is automatically controlled to equal the number of DB-Servers and has a value of 0. Otherwise, the default value is controlled by the current database’s default writeConcern, which uses the --cluster.write-concern startup option as default, which defaults to 1. (cluster only)
400 Bad Request
If the collection-name placeholder is missing, then a HTTP 400 is returned.
404 Not Found
If the collection is unknown, then a HTTP 404 is returned.

Examples

Using an identifier:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/67973/properties

Show output

Using a name:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/properties

Show output

Get the document count of a collection

GET /_db/{database-name}/_api/collection/{collection-name}/count

Get the number of documents in a collection.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

HTTP Headers

x-arango-trx-id string
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

200 OK
All properties of the collection but additionally the document count.
- cacheEnabled* boolean
  Whether the in-memory hash cache for documents is enabled for this collection.
- code* integer
  The HTTP response status code.
- computedValues* array of objects
  A list of objects, each representing a computed value.
  computeOn array of strings
  An array of strings that defines on which write operations the value is computed.
  Possible values: "insert", "update", "replace"
  expression* string
  An AQL RETURN operation with an expression that computes the desired value.
  failOnWarning boolean
  Whether the write operation fails if the expression produces a warning.
  keepNull boolean
  Whether the target attribute is set if the expression evaluates to null.
  name* string
  The name of the target attribute.
  overwrite* boolean
  Whether the computed value takes precedence over a user-provided or existing attribute.
- count* integer
  The number of documents currently present in the collection.
- distributeShardsLike string
  The name of another collection. This collection uses the replicationFactor, numberOfShards and shardingStrategy properties of the other collection and the shards of this collection are distributed in the same way as the shards of the other collection.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isDisjoint boolean
  Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint (Enterprise Edition only). This is an internal property. (cluster only)
- isSmart boolean
  Whether the collection is used in a SmartGraph or EnterpriseGraph (Enterprise Edition only). This is an internal property. (cluster only)
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- keyOptions* object
  An object which contains key generation options.
  allowUserKeys* boolean
  If set to true, then you are allowed to supply own key values in the _key attribute of a document. If set to false, then the key generator is solely responsible for generating keys and an error is raised if you supply own key values in the _key attribute of documents.
  You should not use both user-specified and automatically generated document keys in the same collection in cluster deployments for collections with more than a single shard. Mixing the two can lead to conflicts because Coordinators that auto-generate keys in this case are not aware of all keys which are already used.
  increment integer
  The increment value for the autoincrement key generator. Not used by other key generator types.
  lastValue integer
  The offset value of the autoincrement or padded key generator. This is an internal property for restoring dumps properly.
  offset integer
  The initial offset value for the autoincrement key generator. Not used by other key generator types.
  type* string
  Specifies the type of the key generator. Possible values:
  "traditional"
  "autoincrement"
  "uuid"
  "padded"
- name* string
  The name of this collection.
- numberOfShards integer
  The number of shards of the collection. (cluster only)
- replicationFactor integer
  Contains how many copies of each shard are kept on different DB-Servers. It is an integer number in the range of 1-10 or the string "satellite" for SatelliteCollections (Enterprise Edition only). (cluster only)
- schema* object
  An object that specifies the collection-level schema for documents.
- shardKeys array of strings
  Contains the names of document attributes that are used to determine the target shard for documents. (cluster only)
- shardingStrategy string
  The sharding strategy selected for the collection. (cluster only)
  Possible values:
  "community-compat"
  "enterprise-compat"
  "enterprise-smart-edge-compat"
  "hash"
  "enterprise-hash-smart-edge"
  "enterprise-hex-smart-vertex"
- smartGraphAttribute string
  The attribute that is used for sharding: vertices with the same value of this attribute are placed in the same shard. All vertices are required to have this attribute set and it has to be a string. Edges derive the attribute from their connected vertices (Enterprise Edition only). (cluster only)
- smartJoinAttribute string
  Determines an attribute of the collection that must contain the shard key value of the referred-to SmartJoin collection (Enterprise Edition only). (cluster only)
- syncByRevision* boolean
  Whether the newer revision-based replication protocol is enabled for this collection. This is an internal property.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
- waitForSync* boolean
  If true, creating, changing, or removing documents waits until the data has been synchronized to disk.
- writeConcern integer
  Determines how many copies of each shard are required to be in-sync on the different DB-Servers. If there are less than these many copies in the cluster, a shard refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern cannot be greater than replicationFactor.
  If distributeShardsLike is set, the default writeConcern is that of the prototype collection. For SatelliteCollections, the writeConcern is automatically controlled to equal the number of DB-Servers and has a value of 0. Otherwise, the default value is controlled by the current database’s default writeConcern, which uses the --cluster.write-concern startup option as default, which defaults to 1. (cluster only)
400 Bad Request
If the collection-name placeholder is missing, then a HTTP 400 is returned.
404 Not Found
If the collection is unknown, then a HTTP 404 is returned.

Examples

Requesting the number of documents:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/count

Show output

Get the collection statistics

GET /_db/{database-name}/_api/collection/{collection-name}/figures

Get the number of documents and additional statistical information about the collection.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

details boolean (default: false)
Setting details to true will return extended storage engine-specific details to the figures. The details are intended for debugging ArangoDB itself and their format is subject to change. By default, details is set to false, so no details are returned and the behavior is identical to previous versions of ArangoDB. Please note that requesting details may cause additional load and thus have an impact on performance.

HTTP Headers

Responses

200 OK
All properties of the collection but additionally the document count and collection figures.
- cacheEnabled* boolean
  Whether the in-memory hash cache for documents is enabled for this collection.
- code* integer
  The HTTP response status code.
- computedValues* array of objects
  A list of objects, each representing a computed value.
  computeOn array of strings
  An array of strings that defines on which write operations the value is computed.
  Possible values: "insert", "update", "replace"
  expression* string
  An AQL RETURN operation with an expression that computes the desired value.
  failOnWarning boolean
  Whether the write operation fails if the expression produces a warning.
  keepNull boolean
  Whether the target attribute is set if the expression evaluates to null.
  name* string
  The name of the target attribute.
  overwrite* boolean
  Whether the computed value takes precedence over a user-provided or existing attribute.
- count* integer
  The number of documents currently present in the collection.
- distributeShardsLike string
  The name of another collection. This collection uses the replicationFactor, numberOfShards and shardingStrategy properties of the other collection and the shards of this collection are distributed in the same way as the shards of the other collection.
- error* boolean
  A flag indicating that no error occurred.
- figures* object
  The metrics of the collection.
  indexes* object
  The index metrics.
  count* integer
  The total number of indexes defined for the collection, including the pre-defined indexes (e.g. primary index).
  size* integer
  The total memory allocated for indexes in bytes.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isDisjoint boolean
  Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint (Enterprise Edition only). This is an internal property. (cluster only)
- isSmart boolean
  Whether the collection is used in a SmartGraph or EnterpriseGraph (Enterprise Edition only). This is an internal property. (cluster only)
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- keyOptions* object
  An object which contains key generation options.
  allowUserKeys* boolean
  If set to true, then you are allowed to supply own key values in the _key attribute of a document. If set to false, then the key generator is solely responsible for generating keys and an error is raised if you supply own key values in the _key attribute of documents.
  You should not use both user-specified and automatically generated document keys in the same collection in cluster deployments for collections with more than a single shard. Mixing the two can lead to conflicts because Coordinators that auto-generate keys in this case are not aware of all keys which are already used.
  increment integer
  The increment value for the autoincrement key generator. Not used by other key generator types.
  lastValue integer
  The offset value of the autoincrement or padded key generator. This is an internal property for restoring dumps properly.
  offset integer
  The initial offset value for the autoincrement key generator. Not used by other key generator types.
  type* string
  Specifies the type of the key generator. Possible values:
  "traditional"
  "autoincrement"
  "uuid"
  "padded"
- name* string
  The name of this collection.
- numberOfShards integer
  The number of shards of the collection. (cluster only)
- replicationFactor integer
  Contains how many copies of each shard are kept on different DB-Servers. It is an integer number in the range of 1-10 or the string "satellite" for SatelliteCollections (Enterprise Edition only). (cluster only)
- schema* object
  An object that specifies the collection-level schema for documents.
- shardKeys array of strings
  Contains the names of document attributes that are used to determine the target shard for documents. (cluster only)
- shardingStrategy string
  The sharding strategy selected for the collection. (cluster only)
  Possible values:
  "community-compat"
  "enterprise-compat"
  "enterprise-smart-edge-compat"
  "hash"
  "enterprise-hash-smart-edge"
  "enterprise-hex-smart-vertex"
- smartGraphAttribute string
  The attribute that is used for sharding: vertices with the same value of this attribute are placed in the same shard. All vertices are required to have this attribute set and it has to be a string. Edges derive the attribute from their connected vertices (Enterprise Edition only). (cluster only)
- smartJoinAttribute string
  Determines an attribute of the collection that must contain the shard key value of the referred-to SmartJoin collection (Enterprise Edition only). (cluster only)
- syncByRevision* boolean
  Whether the newer revision-based replication protocol is enabled for this collection. This is an internal property.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
- waitForSync* boolean
  If true, creating, changing, or removing documents waits until the data has been synchronized to disk.
- writeConcern integer
  Determines how many copies of each shard are required to be in-sync on the different DB-Servers. If there are less than these many copies in the cluster, a shard refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern cannot be greater than replicationFactor.
  If distributeShardsLike is set, the default writeConcern is that of the prototype collection. For SatelliteCollections, the writeConcern is automatically controlled to equal the number of DB-Servers and has a value of 0. Otherwise, the default value is controlled by the current database’s default writeConcern, which uses the --cluster.write-concern startup option as default, which defaults to 1. (cluster only)
400 Bad Request
The collection-name parameter is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

Using an identifier and requesting the figures of the collection:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/figures

Show output

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/figures?details=true

Show output

Get the responsible shard for a document

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

Returns the ID of the shard that is responsible for the given document (if the document exists) or that would be responsible if such document existed.

The request must body must contain a JSON document with at least the collection’s shard key attributes set to some values.

The response is a JSON object with a shardId attribute, which will contain the ID of the responsible shard.

This method is only available in cluster deployments on Coordinators.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.

Query Parameters

HTTP Headers

Request Body application/json object

document* object
The request body must be a JSON object with at least the shard key attributes set to some values, but it may also be a full document.

Responses

200 OK
Returns the ID of the responsible shard.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
- shardId* string
  The ID of the responsible shard
400 Bad Request
The collection-name parameter is missing or not all of the collection’s shard key attributes are present in the input document.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
501 Not Implemented
The method has been called on a single server.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

curl -X PUT --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/collection/testCollection/responsibleShard' <<'EOF'
{
  "_key": "testkey",
  "value": 23
}
EOF

Show output

Get the shard IDs of a collection

GET /_db/{database-name}/_api/collection/{collection-name}/shards

Returns a JSON array with the shard IDs of the collection.

If the details parameter is set to true, it returns a JSON object with the shard IDs as object attribute keys, and the responsible servers for each shard mapped to them. In the detailed response, the leader shards come first in the arrays.

This method is only available in cluster deployments on Coordinators.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.

Query Parameters

details boolean (default: false)
If set to true, the return value also contains the responsible servers for the collections’ shards.

HTTP Headers

Responses

200 OK
Returns the collection’s shards.
400 Bad Request
The collection-name parameter is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
501 Not Implemented
The method has been called on a single server.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

Retrieves the list of shards:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/testCollection/shards

Show output

Retrieves the list of shards with the responsible servers:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/testCollection/shards?details=true

Show output

Get the collection revision ID

GET /_db/{database-name}/_api/collection/{collection-name}/revision

The response contains the collection’s latest used revision ID. The revision ID is a server-generated string that clients can use to check whether data in a collection has changed since the last revision check.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

HTTP Headers

Responses

200 OK
All collection properties but additionally the collection revision.
- cacheEnabled* boolean
  Whether the in-memory hash cache for documents is enabled for this collection.
- code* integer
  The HTTP response status code.
- computedValues* array of objects
  A list of objects, each representing a computed value.
  computeOn array of strings
  An array of strings that defines on which write operations the value is computed.
  Possible values: "insert", "update", "replace"
  expression* string
  An AQL RETURN operation with an expression that computes the desired value.
  failOnWarning boolean
  Whether the write operation fails if the expression produces a warning.
  keepNull boolean
  Whether the target attribute is set if the expression evaluates to null.
  name* string
  The name of the target attribute.
  overwrite* boolean
  Whether the computed value takes precedence over a user-provided or existing attribute.
- distributeShardsLike string
  The name of another collection. This collection uses the replicationFactor, numberOfShards and shardingStrategy properties of the other collection and the shards of this collection are distributed in the same way as the shards of the other collection.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isDisjoint boolean
  Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint (Enterprise Edition only). This is an internal property. (cluster only)
- isSmart boolean
  Whether the collection is used in a SmartGraph or EnterpriseGraph (Enterprise Edition only). This is an internal property. (cluster only)
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- keyOptions* object
  An object which contains key generation options.
  allowUserKeys* boolean
  If set to true, then you are allowed to supply own key values in the _key attribute of a document. If set to false, then the key generator is solely responsible for generating keys and an error is raised if you supply own key values in the _key attribute of documents.
  You should not use both user-specified and automatically generated document keys in the same collection in cluster deployments for collections with more than a single shard. Mixing the two can lead to conflicts because Coordinators that auto-generate keys in this case are not aware of all keys which are already used.
  increment integer
  The increment value for the autoincrement key generator. Not used by other key generator types.
  lastValue integer
  The offset value of the autoincrement or padded key generator. This is an internal property for restoring dumps properly.
  offset integer
  The initial offset value for the autoincrement key generator. Not used by other key generator types.
  type* string
  Specifies the type of the key generator. Possible values:
  "traditional"
  "autoincrement"
  "uuid"
  "padded"
- name* string
  The name of this collection.
- numberOfShards integer
  The number of shards of the collection. (cluster only)
- replicationFactor integer
  Contains how many copies of each shard are kept on different DB-Servers. It is an integer number in the range of 1-10 or the string "satellite" for SatelliteCollections (Enterprise Edition only). (cluster only)
- revision* string
  The collection revision ID as a string.
- schema* object
  An object that specifies the collection-level schema for documents.
- shardKeys array of strings
  Contains the names of document attributes that are used to determine the target shard for documents. (cluster only)
- shardingStrategy string
  The sharding strategy selected for the collection. (cluster only)
  Possible values:
  "community-compat"
  "enterprise-compat"
  "enterprise-smart-edge-compat"
  "hash"
  "enterprise-hash-smart-edge"
  "enterprise-hex-smart-vertex"
- smartGraphAttribute string
  The attribute that is used for sharding: vertices with the same value of this attribute are placed in the same shard. All vertices are required to have this attribute set and it has to be a string. Edges derive the attribute from their connected vertices (Enterprise Edition only). (cluster only)
- smartJoinAttribute string
  Determines an attribute of the collection that must contain the shard key value of the referred-to SmartJoin collection (Enterprise Edition only). (cluster only)
- syncByRevision* boolean
  Whether the newer revision-based replication protocol is enabled for this collection. This is an internal property.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
- waitForSync* boolean
  If true, creating, changing, or removing documents waits until the data has been synchronized to disk.
- writeConcern integer
  Determines how many copies of each shard are required to be in-sync on the different DB-Servers. If there are less than these many copies in the cluster, a shard refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern cannot be greater than replicationFactor.
  If distributeShardsLike is set, the default writeConcern is that of the prototype collection. For SatelliteCollections, the writeConcern is automatically controlled to equal the number of DB-Servers and has a value of 0. Otherwise, the default value is controlled by the current database’s default writeConcern, which uses the --cluster.write-concern startup option as default, which defaults to 1. (cluster only)
400 Bad Request
The collection-name parameter is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

Retrieving the revision of a collection

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/revision

Show output

Get the collection checksum

GET /_db/{database-name}/_api/collection/{collection-name}/checksum

Calculates a checksum of the meta-data (keys and optionally revision ids) and optionally the document data in the collection.

The checksum can be used to compare if two collections on different ArangoDB instances contain the same contents. The current revision of the collection is returned too so one can make sure the checksums are calculated for the same state of data.

By default, the checksum is only calculated on the _key system attribute of the documents contained in the collection. For edge collections, the system attributes _from and _to are also included in the calculation.

By setting the optional query parameter withRevisions to true, then revision IDs (_rev system attributes) are included in the checksumming.

By providing the optional query parameter withData with a value of true, the user-defined document attributes are included in the calculation, too.

Including user-defined attributes will make the checksumming slower.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

withRevisions boolean
Whether or not to include document revision ids in the checksum calculation.
withData boolean
Whether or not to include document body data in the checksum calculation.

HTTP Headers

Responses

200 OK
The basic information about the collection but additionally the collection checksum and revision.
- checksum*
  The calculated checksum as a number.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- name* string
  The name of the collection.
- revision*
  The collection revision id as a string.
- status* integer
  The status of the collection.
  3: loaded
  5: deleted
  Every other status indicates a corrupted collection.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
400 Bad Request
If the collection-name placeholder is missing, then a HTTP 400 is returned.
404 Not Found
If the collection is unknown, then a HTTP 404 is returned.

Examples

Retrieving the checksum of a collection:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/checksum

Show output

Retrieving the checksum of a collection including the collection data, but not the revisions:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/checksum?withRevisions=false&withData=true

Show output

Get the available key generators

GET /_db/{database-name}/_api/key-generators

Returns the available key generators for collections.

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.

Query Parameters

HTTP Headers

Responses

200 OK
An object that contains a list of the available generators for document keys.
- keyGenerators* array of strings
  The available document key generators.
  Possible values: "padded", "uuid", "autoincrement", "traditional"

Examples:

Retrieving the key generators for collections:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/key-generators

Show output

Create and delete collections

Create a collection

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

Creates a new collection with a given name. The request must contain an object with the following attributes.

Path Parameters

database-name* string
The name of the database.

Query Parameters

waitForSyncReplication boolean (default: true)
The default is true, which means the server only reports success back to the client when all replicas have created the collection. Set it to false if you want faster server responses and don’t care about full replication.
enforceReplicationFactor boolean (default: true)
The default is true, which means the server checks if there are enough replicas available at creation time and bail out otherwise. Set it to false to disable this extra check.

HTTP Headers

Request Body application/json object

cacheEnabled boolean (default: false)
Whether the in-memory hash cache for documents should be enabled for this collection. Can be controlled globally with the --cache.size startup option. The cache can speed up repeated reads of the same documents via their document keys. If the same documents are not fetched often or are modified frequently, then you may disable the cache to avoid the maintenance costs.
computedValues array of objects
An optional list of objects, each representing a computed value.
- computeOn array of strings (default: ["insert","update","replace"])
  An array of strings to define on which write operations the value shall be computed.
  Possible values: "insert", "update", "replace"
- expression* string
  An AQL RETURN operation with an expression that computes the desired value. See Computed Value Expressions for details.
- failOnWarning boolean (default: false)
  Whether to let the write operation fail if the expression produces a warning.
- keepNull boolean (default: true)
  Whether the target attribute shall be set if the expression evaluates to null. You can set the option to false to not set (or unset) the target attribute if the expression returns null.
- name* string
  The name of the target attribute. Can only be a top-level attribute, but you may return a nested object. Cannot be _key, _id, _rev, _from, _to, or a shard key attribute.
- overwrite* boolean
  Whether the computed value shall take precedence over a user-provided or existing attribute.
distributeShardsLike string (default: "")
The name of another collection. If this property is set in a cluster, the collection copies the replicationFactor, numberOfShards and shardingStrategy properties from the specified collection (referred to as the prototype collection) and distributes the shards of this collection in the same way as the shards of the other collection. In an Enterprise Edition cluster, this data co-location is utilized to optimize queries.
You need to use the same number of shardKeys as the prototype collection, but you can use different attributes.
Using this parameter has consequences for the prototype collection. It can no longer be dropped, before the sharding-imitating collections are dropped. Equally, backups and restores of imitating collections alone generate warnings (which can be overridden) about a missing sharding prototype.
isDisjoint boolean
Whether the collection is for a Disjoint SmartGraph (Enterprise Edition only). This is an internal property.
isSmart boolean
Whether the collection is for a SmartGraph or EnterpriseGraph (Enterprise Edition only). This is an internal property.
isSystem boolean (default: false)
If true, create a system collection. In this case, the collection-name should start with an underscore. End-users should normally create non-system collections only. API implementors may be required to create system collections in very special occasions, but normally a regular collection will do.
keyOptions object
additional options for key generation. If specified, then keyOptions should be a JSON object containing the following attributes:
- allowUserKeys boolean
  If set to true, then you are allowed to supply own key values in the _key attribute of documents. If set to false, then the key generator is solely responsible for generating keys and an error is raised if you supply own key values in the _key attribute of documents.
  You should not use both user-specified and automatically generated document keys in the same collection in cluster deployments for collections with more than a single shard. Mixing the two can lead to conflicts because Coordinators that auto-generate keys in this case are not aware of all keys which are already used.
- increment integer
  The increment value for the autoincrement key generator. Not allowed for other key generator types.
- offset integer
  The initial offset value for the autoincrement key generator. Not allowed for other key generator types.
- type string
  specifies the type of the key generator. The currently available generators are traditional, autoincrement, uuid and padded.
  The traditional key generator generates numerical keys in ascending order. The sequence of keys is not guaranteed to be gap-free.
  The autoincrement key generator generates numerical keys in ascending order, the initial offset and the spacing can be configured (note: autoincrement is currently only supported for non-sharded collections). The sequence of generated keys is not guaranteed to be gap-free, because a new key will be generated on every document insert attempt, not just for successful inserts.
  The padded key generator generates keys of a fixed length (16 bytes) in ascending lexicographical sort order. This is ideal for the RocksDB storage engine, which will slightly benefit keys that are inserted in lexicographically ascending order. The key generator can be used in a single-server or cluster. The sequence of generated keys is not guaranteed to be gap-free.
  The uuid key generator generates universally unique 128 bit keys, which are stored in hexadecimal human-readable format. This key generator can be used in a single-server or cluster to generate “seemingly random” keys. The keys produced by this key generator are not lexicographically sorted.
  Please note that keys are only guaranteed to be truly ascending in single server deployments and for collections that only have a single shard (that includes collections in a OneShard database). The reason is that for collections with more than a single shard, document keys are generated on Coordinator(s). For collections with a single shard, the document keys are generated on the leader DB-Server, which has full control over the key sequence.
name* string
The name of the collection.
numberOfShards integer (default: 1)
In a cluster, this value determines the number of shards to create for the collection.
replicationFactor integer (default: 1)
In a cluster, this attribute determines how many copies of each shard are kept on different DB-Servers. The value 1 means that only one copy (no synchronous replication) is kept. A value of k means that k-1 replicas are kept. For SatelliteCollections, it needs to be the string "satellite", which matches the replication factor to the number of DB-Servers (Enterprise Edition only).
Any two copies reside on different DB-Servers. Replication between them is synchronous, that is, every write operation to the “leader” copy will be replicated to all “follower” replicas, before the write operation is reported successful.
If a server fails, this is detected automatically and one of the servers holding copies take over, usually without an error being reported.
schema object
Optional object that specifies the collection level schema for documents. The attribute keys rule, level and message must follow the rules documented in Document Schema Validation
shardKeys string (default: ["_key"])
In a cluster, this attribute determines which document attributes are used to determine the target shard for documents. Documents are sent to shards based on the values of their shard key attributes. The values of all shard key attributes in a document are hashed, and the hash value is used to determine the target shard.
Values of shard key attributes cannot be changed once set.
shardingStrategy string
This attribute specifies the name of the sharding strategy to use for the collection. There are different sharding strategies to select from when creating a new collection. The selected shardingStrategy value remains fixed for the collection and cannot be changed afterwards. This is important to make the collection keep its sharding settings and always find documents already distributed to shards using the same initial sharding algorithm.
The available sharding strategies are:
- community-compat: default sharding used by ArangoDB Community Edition before version 3.4
- enterprise-compat: default sharding used by ArangoDB Enterprise Edition before version 3.4
- enterprise-smart-edge-compat: default sharding used by smart edge collections in ArangoDB Enterprise Edition before version 3.4
- hash: default sharding used for new collections starting from version 3.4 (excluding smart edge collections)
- enterprise-hash-smart-edge: default sharding used for new smart edge collections starting from version 3.4
- enterprise-hex-smart-vertex: sharding used for vertex collections of EnterpriseGraphs
If no sharding strategy is specified, the default is hash for all normal collections, enterprise-hash-smart-edge for all smart edge collections, and enterprise-hex-smart-vertex for EnterpriseGraph vertex collections (the latter two require the Enterprise Edition of ArangoDB). Manually overriding the sharding strategy does not yet provide a benefit, but it may later in case other sharding strategies are added.
smartGraphAttribute string
The attribute that is used for sharding: vertices with the same value of this attribute are placed in the same shard. All vertices are required to have this attribute set and it has to be a string. Edges derive the attribute from their connected vertices.
This feature can only be used in the Enterprise Edition.
smartJoinAttribute string
In an Enterprise Edition cluster, this attribute determines an attribute of the collection that must contain the shard key value of the referred-to SmartJoin collection. Additionally, the shard key for a document in this collection must contain the value of this attribute, followed by a colon, followed by the actual primary key of the document.
This feature can only be used in the Enterprise Edition and requires the distributeShardsLike attribute of the collection to be set to the name of another collection. It also requires the shardKeys attribute of the collection to be set to a single shard key attribute, with an additional ‘:’ at the end. A further restriction is that whenever documents are stored or updated in the collection, the value stored in the smartJoinAttribute must be a string.
type integer (default: 2)
The type of the collection to create. The following values for type are valid:
- 2: document collection
- 3: edge collection
waitForSync boolean (default: false)
If set to true, then the data is synchronized to disk before returning from a document create, update, replace or removal operation.
writeConcern integer
Determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less than these many copies in the cluster, a shard refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern cannot be greater than replicationFactor.
If distributeShardsLike is set, the default writeConcern is that of the prototype collection. For SatelliteCollections, the writeConcern is automatically controlled to equal the number of DB-Servers and has a value of 0. Otherwise, the default value is controlled by the current database’s default writeConcern, which uses the --cluster.write-concern startup option as default, which defaults to 1. (cluster only)

Responses

200 OK
The collection has been created.
- cacheEnabled* boolean
  Whether the in-memory hash cache for documents is enabled for this collection.
- computedValues array of objects
  A list of objects, each representing a computed value.
  computeOn array of strings
  An array of strings that defines on which write operations the value is computed.
  Possible values: "insert", "update", "replace"
  expression* string
  An AQL RETURN operation with an expression that computes the desired value.
  failOnWarning boolean
  Whether the write operation fails if the expression produces a warning.
  keepNull boolean
  Whether the target attribute is set if the expression evaluates to null.
  name* string
  The name of the target attribute.
  overwrite* boolean
  Whether the computed value takes precedence over a user-provided or existing attribute.
- distributeShardsLike string
  The name of another collection. This collection uses the replicationFactor, numberOfShards and shardingStrategy properties of the other collection and the shards of this collection are distributed in the same way as the shards of the other collection.
- globallyUniqueId string
  A unique identifier of the collection. This is an internal property.
- id string
  A unique identifier of the collection (deprecated).
- isDisjoint boolean
  Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint (Enterprise Edition only). This is an internal property. (cluster only)
- isSmart boolean
  Whether the collection is used in a SmartGraph or EnterpriseGraph (Enterprise Edition only). This is an internal property. (cluster only)
- isSystem boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- keyOptions* object
  An object which contains key generation options.
  allowUserKeys* boolean
  If set to true, then you are allowed to supply own key values in the _key attribute of a document. If set to false, then the key generator is solely responsible for generating keys and an error is raised if you supply own key values in the _key attribute of documents.
  You should not use both user-specified and automatically generated document keys in the same collection in cluster deployments for collections with more than a single shard. Mixing the two can lead to conflicts because Coordinators that auto-generate keys in this case are not aware of all keys which are already used.
  increment integer
  The increment value for the autoincrement key generator. Not used by other key generator types.
  lastValue integer
  The offset value for the autoincrement or padded key generator. This is an internal property for restoring dumps properly.
  offset integer
  The initial offset value for the autoincrement key generator. Not used by other key generator types.
  type* string
  Specifies the type of the key generator. Possible values:
  "traditional"
  "autoincrement"
  "uuid"
  "padded"
- name string
  The name of this collection.
- numberOfShards integer
  The number of shards of the collection. (cluster only)
- replicationFactor integer
  Contains how many copies of each shard are kept on different DB-Servers. It is an integer number in the range of 1-10 or the string "satellite" for SatelliteCollections (Enterprise Edition only). (cluster only)
- schema object
  An object that specifies the collection-level schema for documents.
- shardKeys array of strings
  Contains the names of document attributes that are used to determine the target shard for documents. (cluster only)
- shardingStrategy string
  The sharding strategy selected for the collection. (cluster only)
  Possible values:
  "community-compat"
  "enterprise-compat"
  "enterprise-smart-edge-compat"
  "hash"
  "enterprise-hash-smart-edge"
  "enterprise-hex-smart-vertex"
- smartGraphAttribute string
  The attribute that is used for sharding: vertices with the same value of this attribute are placed in the same shard. All vertices are required to have this attribute set and it has to be a string. Edges derive the attribute from their connected vertices (Enterprise Edition only). (cluster only)
- smartJoinAttribute string
  Determines an attribute of the collection that must contain the shard key value of the referred-to SmartJoin collection (Enterprise Edition only). (cluster only)
- syncByRevision* boolean
  Whether the newer revision-based replication protocol is enabled for this collection. This is an internal property.
- type integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
- waitForSync* boolean
  If true, creating, changing, or removing documents waits until the data has been synchronized to disk.
- writeConcern integer
  Determines how many copies of each shard are required to be in-sync on the different DB-Servers. If there are less than these many copies in the cluster, a shard refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern cannot be greater than replicationFactor.
  If distributeShardsLike is set, the default writeConcern is that of the prototype collection. For SatelliteCollections, the writeConcern is automatically controlled to equal the number of DB-Servers and has a value of 0. Otherwise, the default value is controlled by the current database’s default writeConcern, which uses the --cluster.write-concern startup option as default, which defaults to 1. (cluster only)
400 Bad Request
The name or another required attribute is missing or an attribute has an invalid value.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection
{
  "name": "testCollectionBasics"
}

curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection
{
  "name": "testCollectionEdges",
  "type": 3
}

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: 458
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

{ 
  "error" : false, 
  "code" : 200, 
  "writeConcern" : 1, 
  "waitForSync" : false, 
  "usesRevisionsAsDocumentIds" : true, 
  "syncByRevision" : true, 
  "statusString" : "loaded", 
  "id" : "68742", 
  "isSmartChild" : false, 
  "schema" : null, 
  "name" : "testCollectionBasics", 
  "type" : 2, 
  "status" : 3, 
  "cacheEnabled" : false, 
  "isSystem" : false, 
  "internalValidatorType" : 0, 
  "globallyUniqueId" : "h7F0F0D5E4468/68742", 
  "keyOptions" : { 
    "allowUserKeys" : true, 
    "type" : "traditional", 
    "lastValue" : 0 
  }, 
  "computedValues" : null, 
  "objectId" : "68743" 
}


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: 457
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

{ 
  "error" : false, 
  "code" : 200, 
  "writeConcern" : 1, 
  "waitForSync" : false, 
  "usesRevisionsAsDocumentIds" : true, 
  "syncByRevision" : true, 
  "statusString" : "loaded", 
  "id" : "68747", 
  "isSmartChild" : false, 
  "schema" : null, 
  "name" : "testCollectionEdges", 
  "type" : 3, 
  "status" : 3, 
  "cacheEnabled" : false, 
  "isSystem" : false, 
  "internalValidatorType" : 0, 
  "globallyUniqueId" : "h7F0F0D5E4468/68747", 
  "keyOptions" : { 
    "allowUserKeys" : true, 
    "type" : "traditional", 
    "lastValue" : 0 
  }, 
  "computedValues" : null, 
  "objectId" : "68748" 
}

curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection
{
  "name": "testCollectionUsers",
  "keyOptions": {
    "type": "autoincrement",
    "increment": 5,
    "allowUserKeys": true
  }
}

Show output

Drop a collection

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

Delete the collection identified by collection-name and all its documents.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection to drop.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

isSystem boolean
Whether or not the collection to drop is a system collection. This parameter must be set to true in order to drop a system collection.

HTTP Headers

Responses

200 OK
Dropping the collection has been successful.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
- id* string
  The identifier of the dropped collection.
400 Bad Request
The collection-name parameter is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

Using an identifier:

curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/68887

Show output

Using a name:

curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products1

Show output

Dropping a system collection

curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/_example?isSystem=true

Show output

Truncate a collection

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

Removes all documents from the collection, but leaves the indexes intact.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

waitForSync boolean (default: false)
If set to true, the data is synchronized to disk before returning from the truncate operation.
compact boolean (default: true)
If set to true, the storage engine is told to start a compaction in order to free up disk space. This can be resource intensive. If the only intention is to start over with an empty collection, specify false.

HTTP Headers

x-arango-trx-id string
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

200 OK
Truncating the collection was successful. Returns the basic information about the collection.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
- id* string
  A unique identifier of the collection (deprecated).
400 Bad Request
The collection-name parameter is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/truncate

Show output

Modify collections

Load a collection

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

The load function is deprecated from version 3.8.0 onwards and is a no-op from version 3.9.0 onwards. It should no longer be used, as it may be removed in a future version of ArangoDB.

Since ArangoDB version 3.9.0 this API does nothing. Previously, it used to load a collection into memory.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

HTTP Headers

Responses

200 OK
Returns the basic collection properties for compatibility reasons.
- code* integer
  The HTTP response status code.
- count integer
  The number of documents currently present in the collection.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- name* string
  The name of the collection.
- status* integer
  The status of the collection.
  3: loaded
  5: deleted
  Every other status indicates a corrupted collection.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
400 Bad Request
The collection-name parameter or the name attribute is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/load

Show output

Unload a collection

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

The unload function is deprecated from version 3.8.0 onwards and is a no-op from version 3.9.0 onwards. It should no longer be used, as it may be removed in a future version of ArangoDB.

Since ArangoDB version 3.9.0 this API does nothing. Previously it used to unload a collection from memory, while preserving all documents.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

HTTP Headers

Responses

200 OK
Returns the basic collection properties for compatibility reasons.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- name* string
  The name of the collection.
- status* integer
  The status of the collection.
  3: loaded
  5: deleted
  Every other status indicates a corrupted collection.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
400 Bad Request
The collection-name parameter or the name attribute is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/unload

Show output

Load collection indexes into memory

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

You can call this endpoint to try to cache this collection’s index entries in the main memory. Index lookups served from the memory cache can be much faster than lookups not stored in the cache, resulting in a performance boost.

The endpoint iterates over suitable indexes of the collection and stores the indexed values (not the entire document data) in memory. This is implemented for edge indexes only.

The endpoint returns as soon as the index warmup has been scheduled. The index warmup may still be ongoing in the background, even after the return value has already been sent. As all suitable indexes are scanned, it may cause significant I/O activity and background load.

This feature honors memory limits. If the indexes you want to load are smaller than your memory limit, this feature guarantees that most index values are cached. If the index is greater than your memory limit, this feature fills up values up to this limit. You cannot control which indexes of the collection should have priority over others.

It is guaranteed that the in-memory cache data is consistent with the stored index data at all times.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

HTTP Headers

Responses

200 OK
The index loading has been scheduled for all suitable indexes.
- error* boolean
  A flag indicating that no error occurred.
400 Bad Request
The collection-name parameter is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/loadIndexesIntoMemory

Show output

Change the properties of a collection

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

Changes the properties of a collection. Only the provided attributes are updated. Collection properties cannot be changed once a collection is created except for the listed properties, as well as the collection name via the rename endpoint (but not in clusters).

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

HTTP Headers

Request Body application/json object

cacheEnabled boolean (default: false)
Whether the in-memory hash cache for documents should be enabled for this collection. Can be controlled globally with the --cache.size startup option. The cache can speed up repeated reads of the same documents via their document keys. If the same documents are not fetched often or are modified frequently, then you may disable the cache to avoid the maintenance costs.
computedValues array of objects
An optional list of objects, each representing a computed value.
- computeOn array of strings
  An array of strings to define on which write operations the value shall be computed.
  Possible values: "insert", "update", "replace"
- expression* string
  An AQL RETURN operation with an expression that computes the desired value. See Computed Value Expressions for details.
- failOnWarning boolean (default: false)
  Whether to let the write operation fail if the expression produces a warning.
- keepNull boolean (default: true)
  Whether the target attribute shall be set if the expression evaluates to null. You can set the option to false to not set (or unset) the target attribute if the expression returns null.
- name* string
  The name of the target attribute. Can only be a top-level attribute, but you may return a nested object. Cannot be _key, _id, _rev, _from, _to, or a shard key attribute.
- overwrite* boolean
  Whether the computed value shall take precedence over a user-provided or existing attribute.
replicationFactor integer (default: 1)
In a cluster, this attribute determines how many copies of each shard are kept on different DB-Servers. The value 1 means that only one copy (no synchronous replication) is kept. A value of k means that k-1 replicas are kept. For SatelliteCollections, it needs to be the string "satellite", which matches the replication factor to the number of DB-Servers (Enterprise Edition only).
Any two copies reside on different DB-Servers. Replication between them is synchronous, that is, every write operation to the “leader” copy will be replicated to all “follower” replicas, before the write operation is reported successful.
If a server fails, this is detected automatically and one of the servers holding copies take over, usually without an error being reported.
schema object
Optional object that specifies the collection level schema for documents. The attribute keys rule, level and message must follow the rules documented in Document Schema Validation
waitForSync boolean (default: false)
If set to true, the data is synchronized to disk before returning from a document create, update, replace or removal operation.
writeConcern integer
Determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less than these many copies in the cluster, a shard refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern cannot be greater than replicationFactor.
If distributeShardsLike is set, the default writeConcern is that of the prototype collection. For SatelliteCollections, the writeConcern is automatically controlled to equal the number of DB-Servers and has a value of 0. Otherwise, the default value is controlled by the current database’s default writeConcern, which uses the --cluster.write-concern startup option as default, which defaults to 1. (cluster only)

Responses

200 OK
The collection has been updated successfully.
- cacheEnabled* boolean
  Whether the in-memory hash cache for documents is enabled for this collection.
- code* integer
  The HTTP response status code.
- computedValues* array of objects
  A list of objects, each representing a computed value.
  computeOn array of strings
  An array of strings that defines on which write operations the value is computed.
  Possible values: "insert", "update", "replace"
  expression* string
  An AQL RETURN operation with an expression that computes the desired value.
  failOnWarning boolean
  Whether the write operation fails if the expression produces a warning.
  keepNull boolean
  Whether the target attribute is set if the expression evaluates to null.
  name* string
  The name of the target attribute.
  overwrite* boolean
  Whether the computed value takes precedence over a user-provided or existing attribute.
- distributeShardsLike string
  The name of another collection. This collection uses the replicationFactor, numberOfShards and shardingStrategy properties of the other collection and the shards of this collection are distributed in the same way as the shards of the other collection.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isDisjoint boolean
  Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint (Enterprise Edition only). This is an internal property. (cluster only)
- isSmart boolean
  Whether the collection is used in a SmartGraph or EnterpriseGraph (Enterprise Edition only). This is an internal property. (cluster only)
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- keyOptions* object
  An object which contains key generation options.
  allowUserKeys* boolean
  If set to true, then you are allowed to supply own key values in the _key attribute of a document. If set to false, then the key generator is solely responsible for generating keys and an error is raised if you supply own key values in the _key attribute of documents.
  You should not use both user-specified and automatically generated document keys in the same collection in cluster deployments for collections with more than a single shard. Mixing the two can lead to conflicts because Coordinators that auto-generate keys in this case are not aware of all keys which are already used.
  increment integer
  The increment value for the autoincrement key generator. Not used by other key generator types.
  lastValue integer
  The offset value of the autoincrement or padded key generator. This is an internal property for restoring dumps properly.
  offset integer
  The initial offset value for the autoincrement key generator. Not used by other key generator types.
  type* string
  Specifies the type of the key generator. Possible values:
  "traditional"
  "autoincrement"
  "uuid"
  "padded"
- name* string
  The name of this collection.
- numberOfShards integer
  The number of shards of the collection. (cluster only)
- replicationFactor integer
  Contains how many copies of each shard are kept on different DB-Servers. It is an integer number in the range of 1-10 or the string "satellite" for SatelliteCollections (Enterprise Edition only). (cluster only)
- schema* object
  An object that specifies the collection-level schema for documents.
- shardKeys array of strings
  Contains the names of document attributes that are used to determine the target shard for documents. (cluster only)
- shardingStrategy string
  The sharding strategy selected for the collection. (cluster only)
  Possible values:
  "community-compat"
  "enterprise-compat"
  "enterprise-smart-edge-compat"
  "hash"
  "enterprise-hash-smart-edge"
  "enterprise-hex-smart-vertex"
- smartGraphAttribute string
  The attribute that is used for sharding: vertices with the same value of this attribute are placed in the same shard. All vertices are required to have this attribute set and it has to be a string. Edges derive the attribute from their connected vertices (Enterprise Edition only). (cluster only)
- smartJoinAttribute string
  Determines an attribute of the collection that must contain the shard key value of the referred-to SmartJoin collection (Enterprise Edition only). (cluster only)
- syncByRevision* boolean
  Whether the newer revision-based replication protocol is enabled for this collection. This is an internal property.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
- waitForSync* boolean
  If true, creating, changing, or removing documents waits until the data has been synchronized to disk.
- writeConcern integer
  Determines how many copies of each shard are required to be in-sync on the different DB-Servers. If there are less than these many copies in the cluster, a shard refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern cannot be greater than replicationFactor.
  If distributeShardsLike is set, the default writeConcern is that of the prototype collection. For SatelliteCollections, the writeConcern is automatically controlled to equal the number of DB-Servers and has a value of 0. Otherwise, the default value is controlled by the current database’s default writeConcern, which uses the --cluster.write-concern startup option as default, which defaults to 1. (cluster only)
400 Bad Request
The collection-name parameter is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection/products/properties
{
  "waitForSync": true
}

Show output

Rename a collection

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

Renames a collection.

Renaming collections is not supported in cluster deployments.

If renaming the collection succeeds, then the collection is also renamed in all graph definitions inside the _graphs collection in the current database.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection to rename.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Query Parameters

HTTP Headers

Request Body application/json object

name* string
The new collection name.

Responses

200 OK
The collection has been renamed successfully.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- name* string
  The name of the collection.
- status* integer
  The status of the collection.
  3: loaded
  5: deleted
  Every other status indicates a corrupted collection.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
400 Bad Request
The collection-name parameter or the name attribute is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection/products1/rename
{
  "name": "newname"
}

Show output

Recalculate the document count of a collection

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

Recalculates the document count of a collection, if it ever becomes inconsistent.

Path Parameters

database-name* string
The name of the database.
collection-name* string
The name of the collection.

Query Parameters

HTTP Headers

Responses

200 OK
The document count has been recalculated successfully.
- code* integer
  The HTTP response status code.
- count integer
  The recalculated document count. This attribute is not present when using a cluster.
- error* boolean
  A flag indicating that no error occurred.
- result* boolean
400 Bad Request
The collection-name parameter is missing.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.
404 Not Found
A collection called collection-name could not be found.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Compact a collection

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

Compacts the data of a collection in order to reclaim disk space. The operation will compact the document and index data by rewriting the underlying .sst files and only keeping the relevant entries.

Under normal circumstances, running a compact operation is not necessary, as the collection data will eventually get compacted anyway. However, in some situations, e.g. after running lots of update/replace or remove operations, the disk data for a collection may contain a lot of outdated data for which the space shall be reclaimed. In this case the compaction operation can be used.

Path Parameters

database-name* string
The name of the database.
collection-name* string
Name of the collection to compact

Query Parameters

HTTP Headers

Responses

200 OK
The compaction has been started successfully.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
- globallyUniqueId* string
  A unique identifier of the collection. This is an internal property.
- id* string
  A unique identifier of the collection (deprecated).
- isSystem* boolean
  Whether the collection is a system collection. Collection names that starts with an underscore are usually system collections.
- name* string
  The name of the collection.
- status* integer
  The status of the collection.
  3: loaded
  5: deleted
  Every other status indicates a corrupted collection.
- type* integer
  The type of the collection:
  0: “unknown”
  2: regular document collection
  3: edge collection
401 Unauthorized
If the request was not authenticated as a user with sufficient rights.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  ArangoDB error number for the error that occurred.

Examples

curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/testCollection/compact

Show output