Creating and Deleting Collections

Create collection

creates a collection

POST /_api/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

  • waitForSyncReplication (boolean, optional): Default is true which means the server will only report success back to the client if all replicas have created the collection. Set to false if you want faster server responses and don’t care about full replication.

  • enforceReplicationFactor (boolean, optional): Default is true which means the server will check if there are enough replicas available at creation time and bail out otherwise. Set to false to disable this extra check.

Request Body

  • name (string, required): The name of the collection.

  • waitForSync (boolean, optional): If true then the data is synchronized to disk before returning from a document create, update, replace or removal operation. (default: false)

  • isSystem (boolean, optional): If true, create a system collection. In this case 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. (The default is false)

  • schema (object, optional): 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

  • keyOptions (object, optional): additional options for key generation. If specified, then keyOptions should be a JSON object containing the following attributes:

    • type (string, required): 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 usage with the RocksDB 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.

    • allowUserKeys (boolean, required): if set to true, then it is allowed to supply own key values in the _key attribute of a document. If set to false, then the key generator will solely be responsible for generating keys and supplying own key values in the _key attribute of documents is considered an error.

    • increment (integer, required): increment value for autoincrement key generator. Not used for other key generator types.

    • offset (integer, required): Initial offset value for autoincrement key generator. Not used for other key generator types.

  • type (integer, optional): (The default is 2): the type of the collection to create. The following values for type are valid:
    • 2: document collection
    • 3: edge collection

  • cacheEnabled (boolean, optional): Whether the in-memory hash cache for documents should be enabled for this collection (default: false). 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.

  • numberOfShards (integer, optional): (The default is 1): in a cluster, this value determines the number of shards to create for the collection. In a single server setup, this option is meaningless.

  • shardKeys (string, optional): (The default is [ "_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. Note: Values of shard key attributes cannot be changed once set. This option is meaningless in a single server setup.

  • replicationFactor (integer, optional): (The default is 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. It can also be the string "satellite" for a SatelliteCollection, where the replication factor is matched 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.

  • writeConcern (integer, optional): Write concern for this collection (default: 1). It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern cannot be larger than replicationFactor. (cluster only)

  • distributeShardsLike (string, optional): (The default is ""): in an Enterprise Edition cluster, this attribute binds the specifics of sharding for the newly created collection to follow that of a specified existing collection. Note: 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 will generate warnings (which can be overridden) about missing sharding prototype.

  • shardingStrategy (string, optional): This attribute specifies the name of the sharding strategy to use for the collection. Since ArangoDB 3.4 there are different sharding strategies to select from when creating a new collection. The selected shardingStrategy value will remain 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

    If no sharding strategy is specified, the default will be hash for all collections, and enterprise-hash-smart-edge for all smart edge collections (requires 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.

  • smartJoinAttribute (string, optional): 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.

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

Responses

HTTP 400: If the collection-name is missing, then an HTTP 400 is returned.

HTTP 404: If the collection-name is unknown, then an HTTP 404 is returned.

HTTP 200:

  • waitForSync (boolean): If true then creating, changing or removing documents will wait until the data has been synchronized to disk.

  • schema (object): The collection level schema for documents.

  • keyOptions (object): A object which contains key generation options

    • type (string): specifies the type of the key generator. The currently available generators are traditional, autoincrement, uuid and padded.

    • allowUserKeys (boolean): if set to true, then it is 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 supplying own key values in the _key attribute of documents is considered an error.

    • lastValue (integer):

  • cacheEnabled (boolean): Whether the in-memory hash cache for documents is enabled for this collection.

  • numberOfShards (integer): The number of shards of the collection. (cluster only)

  • shardKeys (array of strings): contains the names of document attributes that are used to determine the target shard for documents. (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 a SatelliteCollection (Enterprise Edition only). (cluster only)

  • writeConcern (integer): determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern cannot be larger than replicationFactor. (cluster only)

  • shardingStrategy (string): the sharding strategy selected for the collection. One of ‘hash’ or ‘enterprise-hash-smart-edge’. (cluster only)

  • isSmart (boolean): Whether the collection is used in a SmartGraph (Enterprise Edition only). (cluster only)

  • smartGraphAttribute (string): Attribute that is used in SmartGraphs (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)

  • isSystem (boolean): true if this is a system collection; usually name will start with an underscore.

  • name (string): literal name of this collection

  • id (string): unique identifier of the collection; deprecated

  • type (integer): The type of the collection:
    • 0: “unknown”
    • 2: regular document collection
    • 3: edge collection

  • globallyUniqueId (string): Unique identifier of the collection

Examples

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 436
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection <<EOF
{ 
  "name" : "testCollectionEdges", 
  "type" : 3 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 435
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection <<EOF
{ 
  "name" : "testCollectionUsers", 
  "keyOptions" : { 
    "type" : "autoincrement", 
    "increment" : 5, 
    "allowUserKeys" : true 
  } 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 462
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Drops a collection

drops a collection

DELETE /_api/collection/{collection-name}

Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Path Parameters

  • collection-name (string, required): The name of the collection to drop.

Query Parameters

  • isSystem (boolean, optional): 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.

Drops the collection identified by collection-name.

If the collection was successfully dropped, an object is returned with the following attributes:

  • error: false

  • id: The identifier of the dropped collection.

Responses

HTTP 400: If the collection-name is missing, then a HTTP 400 is returned.

HTTP 404: If the collection-name is unknown, then a HTTP 404 is returned.

Examples

Using an identifier:

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 39
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Using a name:

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 39
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Dropping a system collection

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 39
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Truncate collection

truncates a collection

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

Accessing collections by their numeric ID is deprecated from version 3.4.0 on. You should reference them via their names instead.

Path Parameters

  • collection-name (string, required): The name of the collection.

Query Parameters

  • waitForSync (boolean, optional): If true then the data is synchronized to disk before returning from the truncate operation (default: false)

  • compact (boolean, optional): If true (default) then 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.

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

Responses

HTTP 400: If the collection-name is missing, then a HTTP 400 is returned.

HTTP 404: If the collection-name is unknown, then a HTTP 404 is returned.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 135
location: /_db/_system/_api/collection/products/truncate
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
❮  Collections

© ArangoDB - the native multi-model NoSQL database