Collection Methods

Drop

Drops a collection:

collection.drop(options)

Drops a collection and all its indexes and data. In order to drop a system collection, an options object with attribute isSystem set to true must be specified.

Examples

Drop a collection:

arangosh> col = db.example;
arangosh> col.drop();
arangosh> col;

[ArangoCollection 72950, "example" (type document, status loaded)]
[ArangoCollection 72950, "example" (type document, status deleted)]

Drop a system collection:

arangosh> col = db._example;
arangosh> col.drop({ isSystem: true });
arangosh> col;

[ArangoCollection 72957, "_example" (type document, status loaded)]
[ArangoCollection 72957, "_example" (type document, status deleted)]

Truncate

Truncate a collection:

collection.truncate()

Truncates a collection, removing all documents but keeping all its indexes.

Examples

Truncates a collection:

arangosh> col = db.example;
arangosh> col.save({ "Hello" : "World" });
arangosh> col.count();
arangosh> col.truncate();
arangosh> col.count();

[ArangoCollection 73115, "example" (type document, status loaded)]
{ 
  "_id" : "example/73120", 
  "_key" : "73120", 
  "_rev" : "_e268YoC---" 
}
1
0

Compact

Introduced in: v3.4.5

Compacts the data of a collection:

collection.compact()

Compacts the data of a collection in order to reclaim disk space. The operation compacts the document and index data by rewriting the underlying .sst files and only keeps the relevant entries.

Under normal circumstances running a compact operation is not necessary, as the collection data is eventually 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.

Properties

Get or set the properties of a collection:

collection.properties()

Returns an object containing all collection properties.

• waitForSync: If true, creating a document only returns after the data was synced to disk.

• keyOptions (optional) additional options for key generation. This is a JSON object containing the following attributes (note: some of the attributes are optional):
  • type: the type of the key generator used for the collection.
  • 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.
  • 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.

• schema (optional, default: null): Object that specifies the collection level document schema for documents. The attribute keys rule, level and message must follow the rules documented in Document Schema Validation

• computedValues (optional, default: null): An array of objects, each representing a Computed Value.

In a cluster setup, the result also contains the following attributes:

• numberOfShards: the number of shards of the collection.

• shardKeys: contains the names of document attributes that are used to determine the target shard for documents.

• replicationFactor: determines how many copies of each shard are kept on different DB-Servers. Has to be in the range of 1-10 or the string "satellite" for a SatelliteCollection (Enterprise Edition only). (cluster only)

• writeConcern: 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 refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

• shardingStrategy: the sharding strategy selected for the collection. This attribute is only populated in cluster mode and is not populated in single-server mode. (cluster only)

collection.properties(properties)

Changes the collection properties. properties must be an object with one or more of the following attribute(s):

• waitForSync: If true, creating a document only returns after the data was synced to disk.

• replicationFactor: Change the number of shard copies kept on different DB-Servers. Valid values are integer numbers in the range of 1-10 or the string "satellite" for a SatelliteCollection (Enterprise Edition only). (cluster only)

• writeConcern: change 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 refuses to write. Writes to shards with enough up-to-date copies succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

Examples

Read all properties:

arangosh> db.example.properties();

{ 
  "globallyUniqueId" : "h44844A88B2DD/73070", 
  "isSystem" : false, 
  "waitForSync" : false, 
  "keyOptions" : { 
    "allowUserKeys" : true, 
    "type" : "traditional", 
    "lastValue" : 0 
  }, 
  "writeConcern" : 1, 
  "cacheEnabled" : false, 
  "computedValues" : null, 
  "syncByRevision" : true, 
  "schema" : null 
}

Change a property:

arangosh> db.example.properties({ waitForSync : true });

{ 
  "globallyUniqueId" : "h44844A88B2DD/73078", 
  "isSystem" : false, 
  "waitForSync" : true, 
  "keyOptions" : { 
    "allowUserKeys" : true, 
    "type" : "traditional", 
    "lastValue" : 0 
  }, 
  "writeConcern" : 1, 
  "cacheEnabled" : false, 
  "computedValues" : null, 
  "syncByRevision" : true, 
  "schema" : null 
}

Figures

Return the figures of a collection:

collection.figures(details)

Returns an object containing statistics about the collection.

Setting details to true returns extended storage engine-specific details to the figures (introduced in v3.8.0). The details are intended for debugging ArangoDB itself and their format is subject to change. By default, details is set to false, so no details are returned and the behavior is identical to previous versions of ArangoDB.

• indexes.count: The total number of indexes defined for the collection, including the pre-defined indexes (e.g. primary index).
• indexes.size: The total memory allocated for indexes in bytes.
• documentsSize
• cacheInUse
• cacheSize
• cacheUsage

Examples

Get the basic collection figures:

arangosh> db.demo.figures()

{ 
  "indexes" : { 
    "count" : 1, 
    "size" : 2077 
  }, 
  "documentsSize" : 1581, 
  "cacheInUse" : false, 
  "cacheSize" : 0, 
  "cacheUsage" : 0 
}

Get the detailed collection figures:

arangosh> db.demo.figures(true)

{ 
  "indexes" : { 
    "count" : 1, 
    "size" : 2077 
  }, 
  "documentsSize" : 1581, 
  "cacheInUse" : false, 
  "cacheSize" : 0, 
  "cacheUsage" : 0, 
  "engine" : { 
    "documents" : 1, 
    "indexes" : [ 
      { 
        "type" : "primary", 
        "id" : 0, 
        "count" : 1 
      } 
    ] 
  } 
}

GetResponsibleShard

Return the responsible shard for the given document:

collection.getResponsibleShard(document)

Returns a string with the responsible shard’s ID. Note that the returned shard ID is the ID of responsible shard for the document’s shard key values, and it returns even if no such document exists.

Shards

Return the available shards for the collection:

collection.shards(details)

If details is not set, or set to false, returns an array with the names of the available shards of the collection.

If details is set to true, returns an object with the shard names as object attribute keys, and the responsible servers as an array mapped to each shard attribute key.

The leader shards are always first in the arrays of responsible servers.

Load

Load a collection:

collection.load()

Loads a collection into memory.

Examples

arangosh> col = db.example;
arangosh> col.load();
arangosh> col;

[ArangoCollection 73043, "example" (type document, status loaded)]
[ArangoCollection 73043, "example" (type document, status loaded)]

Revision

Return the revision ID of a collection:

collection.revision()

Returns the revision ID of the collection

The revision ID is updated when the document data is modified, either by inserting, deleting, updating or replacing documents in it.

The revision ID of a collection can be used by clients to check whether data in a collection has changed or if it is still unmodified since a previous fetch of the revision ID.

The revision ID returned is a string value. Clients should treat this value as an opaque string, and only use it for equality/non-equality comparisons.

Checksum

Calculate a checksum for the data in a collection:

collection.checksum(withRevisions, withData)

The checksum operation calculates an aggregate hash value for all document keys contained in collection collection.

If the optional argument withRevisions is set to true, then the revision ids of the documents are also included in the hash calculation.

If the optional argument withData is set to true, then all user-defined document attributes are also checksummed. Including the document data in checksumming makes the calculation slower, but is more accurate.

Unload

Unload a collection:

collection.unload()

Starts unloading a collection from memory. Note that unloading is deferred until all queries have finished.

Examples

arangosh> col = db.example;
arangosh> col.unload();
arangosh> col;

[ArangoCollection 61254, "example" (type document, status loaded)]
[ArangoCollection 61254, "example" (type document, status loaded)]

Rename

Rename a collection:

collection.rename(new-name)

Renames a collection using the new-name. The new-name must not already be used for a different collection. new-name must also be a valid collection name. For more information on valid collection names please refer to the naming conventions.

If renaming fails for any reason, an error is thrown. If renaming the collection succeeds, then the collection is also renamed in all graph definitions inside the _graphs collection in the current database.

Examples

arangosh> c = db.example;
arangosh> c.rename("better-example");
arangosh> c;

[ArangoCollection 73106, "example" (type document, status loaded)]
[ArangoCollection 73106, "better-example" (type document, status loaded)]