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

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

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

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

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

Truncate

truncates 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 71315, "example" (type document, status loaded)]
{ 
  "_id" : "example/71320", 
  "_key" : "71320", 
  "_rev" : "_fw2Y2Aa--_" 
}
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 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.

Properties

gets or sets the properties of a collection collection.properties()

Returns an object containing all collection properties.

• waitForSync: If true creating a document will only return 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 will solely be responsible for generating keys and supplying own key values in the _key attribute of documents is considered an error.
  • lastValue: the current offset value of the autoincrement or padded key generator. This an internal property for restoring dumps properly.
  • 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 is 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

• cacheEnabled: Whether the in-memory hash cache for documents is enabled for this collection (default: false).

• isSystem: Whether the collection is a system collection.

• syncByRevision: Whether the newer revision-based replication protocol is enabled for this collection. This is an internal property.

• globallyUniqueId: A unique identifier of the collection. This is an internal property.

In a cluster setup, the result will also contain 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 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)

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

• distributeShardsLike: The name of another collection. This collection uses the replicationFactor, numberOfShards and shardingStrategy properties of the other collection and the shards of this collection are distributed in the same way as the shards of the other collection.

• isSmart: Whether the collection belongs to a SmartGraph (Enterprise Edition only). This is an internal property.

• isDisjoint: Whether the SmartGraph this collection belongs to is disjoint (Enterprise Edition only). This is an internal property.

• smartGraphAttribute: The attribute that is used for sharding: vertices with the same value of this attribute are placed in the same shard. All vertices are required to have this attribute set and it has to be a string. Edges derive the attribute from their connected vertices.

  This feature can only be used in the Enterprise Edition.

• smartJoinAttribute: In an Enterprise Edition cluster, this attribute determines an attribute of the collection that must contain the shard key value of the referred-to SmartJoin collection.

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 will only return 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 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)

• schema: An 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

• cacheEnabled: Whether the in-memory hash cache for documents should be enabled for this collection. 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.

Note: some other collection properties, such as type, keyOptions, numberOfShards or shardingStrategy cannot be changed once the collection is created.

Examples

Read all properties

arangosh> db.example.properties();

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

Change a property

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

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

Figures

returns the figures of a collection collection.figures(details)

Returns an object containing statistics about the collection.

Setting details to true will return 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

arangosh> db.demo.figures()

{ 
  "indexes" : { 
    "count" : 1, 
    "size" : 1959 
  }, 
  "documentsSize" : 15178, 
  "cacheInUse" : false, 
  "cacheSize" : 0, 
  "cacheUsage" : 0 
}

arangosh> db.demo.figures(true)

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

GetResponsibleShard

returns 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 will be returned even if no such document exists.

Shards

returns 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

loads a collection collection.load()

Loads a collection into memory.

Examples

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

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

Revision

returns 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

calculates 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 will make the calculation slower, but is more accurate.

Unload

unloads 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 61252, "example" (type document, status loaded)]
[ArangoCollection 61252, "example" (type document, status unloaded)]

Rename

renames 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 71306, "example" (type document, status loaded)]
[ArangoCollection 71306, "better-example" (type document, status loaded)]