ArangoDB v2.8 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent version here: Try latest

Creating and Deleting Collections

Create collection

creates a collection

POST /_api/collection

A JSON object with these properties is required:

  • name: The name of the collection.

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

  • doCompact: whether or not the collection will be compacted (default is true)

  • journalSize: The maximal size of a journal or datafile in bytes. The value must be at least 1048576 (1 MiB). (The default is a configuration parameter)

  • isSystem: 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)

  • isVolatile: If true then the collection data is kept in-memory only and not made persistent. Unloading the collection will cause the collection data to be discarded. Stopping or re-starting the server will also cause full loss of data in the collection. Setting this option will make the resulting collection be slightly faster than regular collections because ArangoDB does not enforce any synchronization to disk and does not calculate any CRC checksums for datafiles (as there are no datafiles). This option should therefore be used for cache-type collections only, and not for data that cannot be re-created otherwise. (The default is false)

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

    • type: specifies the type of the key generator. The currently available generators are traditional and autoincrement.
    • allowUserKeys: 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: increment value for autoincrement key generator. Not used for other key generator types.
    • offset: Initial offset value for autoincrement key generator. Not used for other key generator types.
  • type: (The default is 2): the type of the collection to create. The following values for type are valid:
  • 2: document collection

  • 3: edges collection

    • indexBuckets: The: number of buckets into which indexes using a hash table are split. The default is 16 and this number has to be a power of 2 and less than or equal to 1024.
      For very large collections one should increase this to avoid long pauses when the hash table has to be initially built or resized, since buckets are resized individually and can be initially built in parallel. For example, 64 might be a sensible value for a collection with 100 000 000 documents. Currently, only the edge index respects this value, but other index types might follow in future ArangoDB versions. Changes (see below) are applied when the collection is loaded the next time.

    • numberOfShards: (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: (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.

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

Return codes

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

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

Examples 

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

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
location: /_db/_system/_api/collection/testCollectionBasics
show response body


shell> curl -X POST --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; charset=utf-8
location: /_db/_system/_api/collection/testCollectionUsers
show response body

Drops collection

drops a collection

DELETE /_api/collection/{collection-name}

Path Parameters

  • collection-name (required): The name of the collection to drop.
    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.

    Return codes

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

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

Examples
Using an identifier: 

shell> curl -X DELETE --dump - http://localhost:8529/_api/collection/644106369

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
show response body


Using a name: 

shell> curl -X DELETE --dump - http://localhost:8529/_api/collection/products1

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
show response body

Truncate collection

truncates a collection

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

Path Parameters

  • collection-name (required): The name of the collection.
    Removes all documents from the collection, but leaves the indexes intact.

    Return codes

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

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

Examples 

shell> curl -X PUT --dump - http://localhost:8529/_api/collection/products/truncate

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
show response body
❮  Collections

© ArangoDB - the native multi-model NoSQL database