Modifying a Collection

Load collection

loads a collection

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

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

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 --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/load

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/load
x-content-type-options: nosniff

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

Hide response body

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/load
x-content-type-options: nosniff

Show response body

Unload collection

unloads a collection

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

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

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 --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/unload

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/unload
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "type" : 2, 
  "globallyUniqueId" : "h84DFE661F1A8/103751", 
  "id" : "103751", 
  "isSystem" : false, 
  "status" : 4, 
  "name" : "products" 
}

Hide response body

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/unload
x-content-type-options: nosniff

Show response body

Load Indexes into Memory

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

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 (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

Return codes

200: If the indexes have all been loaded
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 --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/loadIndexesIntoMemory

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/loadIndexesIntoMemory
x-content-type-options: nosniff

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

Hide response body

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/loadIndexesIntoMemory
x-content-type-options: nosniff

Show response body

Change properties of a collection

changes a collection

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

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

Changes the properties of a collection. Expects an object with the attribute(s)

waitForSync: If true then creating or changing a document will wait until the data has been synchronized to disk.
journalSize: The maximal size of a journal or datafile in bytes. The value must be at least 1048576 (1 MB). Note that when changing the journalSize value, it will only have an effect for additional journals or datafiles that are created. Already existing journals or datafiles will not be affected.

On success an object with the following attributes is returned:

id: The identifier of the collection.
name: The name of the collection.
waitForSync: The new value.
journalSize: The new value.
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.
isVolatile: If true then the collection data will be kept in memory only and ArangoDB will not write or sync the data to disk.
doCompact: Whether or not the collection will be compacted.
keyOptions: JSON object which contains key generation options:
- type: specifies the type of the key generator. The currently available generators are traditional, autoincrement, uuid and padded.
- 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 is solely responsible for generating keys and supplying own key values in the _key attribute of documents is considered an error.

Note: except for waitForSync, journalSize and name, collection properties cannot be changed once a collection is created. To rename a collection, the rename endpoint must be used.

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/properties
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "waitForSync" : true, 
  "type" : 2, 
  "indexBuckets" : 8, 
  "id" : "103714", 
  "doCompact" : true, 
  "globallyUniqueId" : "h84DFE661F1A8/103714", 
  "isVolatile" : false, 
  "journalSize" : 33554432, 
  "isSystem" : false, 
  "keyOptions" : { 
    "allowUserKeys" : true, 
    "type" : "traditional", 
    "lastValue" : 0 
  }, 
  "name" : "products", 
  "statusString" : "loaded", 
  "status" : 3 
}

Hide response body

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 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/properties
x-content-type-options: nosniff

Show response body

Rename collection

renames a collection

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

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

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products1/rename
x-content-type-options: nosniff

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

Hide response body

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 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products1/rename
x-content-type-options: nosniff

Show response body

Rotate journal of a collection

rotates the journal of a collection

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

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

Rotates the journal of a collection. The current journal of the collection will be closed and made a read-only datafile. The purpose of the rotate method is to make the data in the file available for compaction (compaction is only performed for read-only datafiles, and not for journals).

Saving new data in the collection subsequently will create a new journal file automatically if there is no current journal.

It returns an object with the attributes

result: will be true if rotation succeeded

Note: this method is specific for the MMFiles storage engine, and there it is not available in a cluster.

Return codes

400: If the collection currently has no journal, HTTP 400 is returned.
404: If the collection-name is unknown, then a HTTP 404 is returned.

Examples

Rotating the journal:

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/rotate
x-content-type-options: nosniff

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

Hide response body

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
location: /_api/collection/products/rotate
x-content-type-options: nosniff

Show response body

Rotating if no journal exists:

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

HTTP/1.1 Bad Request
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : true, 
  "errorMessage" : "no journal", 
  "code" : 400, 
  "errorNum" : 1105 
}

Hide response body

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

HTTP/1.1 Bad Request
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Recalculate count of a collection

recalculates the document count of a collection

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

Path Parameters

collection-name (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

Return codes

200: If the document count was recalculated successfully, HTTP 200 is returned.
404: If the collection-name is unknown, then a HTTP 404 is returned.

❮ Getting Information Documents ❯