Modifying a Collection

Load collection

loads a collection

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

Path Parameters

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

Loads a collection into memory. Returns the collection on success.

The request body object might optionally contain the following attribute:

• count: If set, this controls whether the return value should include the number of documents in the collection. Setting count to false may speed up loading a collection. The default value for count is true.

On success an object with the following attributes is returned:

• id: The identifier of the collection.

• name: The name of the collection.

• count: The number of documents inside the collection. This is only returned if the count input parameters is set to true or has not been specified.

• status: The status of the collection as number.

• type: The collection type. Valid types are:
  • 2: document collection
  • 3: edges collection
• isSystem: If true then the collection is a system 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

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 145
location: /_api/collection/products/load
server: ArangoDB
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "type" : 2, 
  "count" : 0, 
  "globallyUniqueId" : "h92B84384354F/67123", 
  "id" : "67123", 
  "isSystem" : false, 
  "status" : 3, 
  "name" : "products" 
}

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 145
location: /_api/collection/products/load
server: ArangoDB
x-content-type-options: nosniff

Unload collection

unloads a collection

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

Path Parameters

• collection-name (string, required):

Removes a collection from memory. This call does not delete any documents. You can use the collection afterwards; in which case it will be loaded into memory, again. On success an object with the following attributes is returned:

• id: The identifier of the collection.

• name: The name of the collection.

• status: The status of the collection as number.

• type: The collection type. Valid types are:
  • 2: document collection
  • 3: edges collection
• isSystem: If true then the collection is a system 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

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 135
location: /_api/collection/products/unload
server: ArangoDB
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "type" : 2, 
  "isSystem" : false, 
  "id" : "67166", 
  "globallyUniqueId" : "h92B84384354F/67166", 
  "name" : "products", 
  "status" : 2 
}

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 135
location: /_api/collection/products/unload
server: ArangoDB
x-content-type-options: nosniff

Load Indexes into Memory

Load Indexes into Memory

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

Path Parameters

• collection-name (string, required):

This route tries to cache all index entries of this collection into the main memory. Therefore it iterates over all indexes of the collection and stores the indexed values, not the entire document data, in memory. All lookups that could be found in the cache are much faster than lookups not stored in the cache so you get a nice performance boost. It is also guaranteed that the cache is consistent with the stored data.

For the time being this function is only useful on RocksDB storage engine, as in MMFiles engine all indexes are in memory anyways.

On RocksDB this function honors all memory limits, if the indexes you want to load are smaller than your memory limit this function guarantees that most index values are cached. If the index is larger than your memory limit this function will fill up values up to this limit and for the time being there is no way to control which indexes of the collection should have priority over others.

On sucess this function returns an object with attribute result set to true

Responses

HTTP 200: If the indexes have all been loaded

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/loadIndexesIntoMemory

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 40
location: /_api/collection/products/loadIndexesIntoMemory
server: ArangoDB
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : true 
}

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 40
location: /_api/collection/products/loadIndexesIntoMemory
server: ArangoDB
x-content-type-options: nosniff

Change properties of a collection

changes a collection

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

Path Parameters

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

Request Body

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

• 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.

• 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

• 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 can not be larger than replicationFactor. (cluster only)

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).

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' --data-binary @- --dump - http://localhost:8529/_api/collection/products/properties <<EOF
{ 
  "waitForSync" : true 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 416
location: /_api/collection/products/properties
server: ArangoDB
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "writeConcern" : 1, 
  "waitForSync" : true, 
  "usesRevisionsAsDocumentIds" : true, 
  "type" : 2, 
  "syncByRevision" : true, 
  "id" : "67140", 
  "cacheEnabled" : false, 
  "isSmartChild" : false, 
  "objectId" : "67139", 
  "globallyUniqueId" : "h92B84384354F/67140", 
  "schema" : null, 
  "keyOptions" : { 
    "allowUserKeys" : true, 
    "type" : "traditional", 
    "lastValue" : 0 
  }, 
  "isSystem" : false, 
  "isDisjoint" : false, 
  "name" : "products", 
  "statusString" : "loaded", 
  "status" : 3 
}

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 416
location: /_api/collection/products/properties
server: ArangoDB
x-content-type-options: nosniff

Rename collection

renames a collection

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

Path Parameters

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

Renames a collection. Expects an object with the attribute(s)

• name: The new name.

It returns an object with the attributes

• id: The identifier of the collection.

• name: The new name of the collection.

• status: The status of the collection as number.

• type: The collection type. Valid types are:
  • 2: document collection
  • 3: edges collection
• isSystem: If true then the collection is a system collection.

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

Note: this method is not available in a cluster.

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' --data-binary @- --dump - http://localhost:8529/_api/collection/products1/rename <<EOF
{ 
  "name" : "newname" 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 134
location: /_api/collection/products1/rename
server: ArangoDB
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "type" : 2, 
  "isSystem" : false, 
  "id" : "67149", 
  "globallyUniqueId" : "h92B84384354F/67149", 
  "name" : "newname", 
  "status" : 3 
}

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 134
location: /_api/collection/products1/rename
server: ArangoDB
x-content-type-options: nosniff

Recalculate count of a collection

recalculates the document count of a collection

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

Path Parameters

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

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

It returns an object with the attributes

• result: will be true if recalculating the document count succeeded.

Note: this method is specific for the RocksDB storage engine

Responses

HTTP 200: If the document count was recalculated successfully, HTTP 200 is returned.

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

Compact the data of a collection

compact collection

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

Path Parameters

• collection-name (string, required): Name of the collection to 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.

Responses

HTTP 200: Compaction started successfully

HTTP 401: if the request was not authenticated as a user with sufficient rights

Examples

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 141
location: /_api/collection/testCollection/compact
server: ArangoDB
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "type" : 2, 
  "isSystem" : false, 
  "id" : "66730", 
  "globallyUniqueId" : "h92B84384354F/66730", 
  "name" : "testCollection", 
  "status" : 3 
}

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 141
location: /_api/collection/testCollection/compact
server: ArangoDB
x-content-type-options: nosniff