Modifying a Collection
Load collection
loads a collection
PUT /_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.
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.
Since ArangoDB version 3.9.0 this API does nothing. Previously it used to load a collection into memory.
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.
A call to this API returns an object with the following attributes for compatibility reasons:
-
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: edge 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
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: 145
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/load
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Unload collection
unloads a collection
PUT /_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.
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):
Since ArangoDB version 3.9.0 this API does nothing. Previously it used to unload a collection from memory, while preserving all documents. When calling the API an object with the following attributes is returned for compatibility reasons:
-
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
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: 135
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/unload
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Load Indexes into Memory
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 (string, required):
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 larger 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.
On success, this endpoint returns an object with attribute result
set to true
.
Responses
HTTP 200: If the index loading has been scheduled for all suitable indexes.
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
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: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/loadIndexesIntoMemory
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
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 (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
andmessage
must follow the rules documented in Document Schema Validation -
computedValues (array, optional): An optional list of objects, each representing a computed value.
-
name (string, required): 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. -
expression (string, required): An AQL
RETURN
operation with an expression that computes the desired value. See Computed Value Expressions for details. -
overwrite (boolean, required): Whether the computed value shall take precedence over a user-provided or existing attribute.
-
computeOn (array of strings, optional): An array of strings to define on which write operations the value shall be computed. The possible values are
"insert"
,"update"
, and"replace"
. The default is["insert", "update", "replace"]
. -
keepNull (boolean, optional): Whether the target attribute shall be set if the expression evaluates to
null
. You can set the option tofalse
to not set (or unset) the target attribute if the expression returnsnull
. The default istrue
. -
failOnWarning (boolean, optional): Whether to let the write operation fail if the expression produces a warning. The default is
false
.
-
-
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
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: 445
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/properties
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
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 (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
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: 134
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products1/rename
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
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.
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
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: 141
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/testCollection/compact
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff