Database Methods

Collection

returns a single collection or nulldb._collection(collection-name)

Returns the collection with the given name or null if no such collectionexists.

db._collection(collection-identifier)

Returns the collection with the given identifier or null if no suchcollection exists. Accessing collections by identifier is discouraged forend users. End users should access collections using the collection name.

Examples

Get a collection by name:

  1. arangosh> db._collection("demo");

Show execution results

  1. [ArangoCollection 90, "demo" (type document, status loaded)]

Hide execution results

Get a collection by id:

  1. arangosh> db._collection(123456);
  2. [ArangoCollection 123456, "demo" (type document, status loaded)]

Unknown collection:

  1. arangosh> db._collection("unknown");

Show execution results

  1. null

Hide execution results

Create

creates a new document or edge collectiondb._create(collection-name)

Creates a new document collection named collection-name.If the collection name already exists or if the name format is invalid, anerror is thrown. For more information on valid collection names please referto the naming conventions.

db._create(collection-name, properties)

properties must be an object with the following attributes:

  • waitForSync (optional, default false): If true creatinga document will only return after the data was synced to disk.

  • journalSize (optional, default is aconfiguration parameter: The maximalsize of a journal or datafile. Note that this also limits the maximalsize of a single object. Must be at least 1MB.

  • isSystem (optional, default is false): If true, create asystem collection. In this case collection-name should start withan underscore. End users should normally create non-system collectionsonly. API implementors may be required to create system collections invery special occasions, but normally a regular collection will do.

  • isVolatile (optional, default is false): If true then thecollection data is kept in-memory only and not made persistent. Unloadingthe collection will cause the collection data to be discarded. Stoppingor re-starting the server will also cause full loss of data in thecollection. The collection itself will remain however (only the data isvolatile). Setting this option will make the resulting collection beslightly faster than regular collections because ArangoDB does notenforce any synchronization to disk and does not calculate any CRCchecksums for datafiles (as there are no datafiles).This option is meaningful for the MMFiles storage engine only.

  • keyOptions (optional): additional options for key generation. Ifspecified, then keyOptions should be a JSON object containing thefollowing attributes (note: some of them are optional):

    • type: specifies the type of the key generator. The currentlyavailable generators are traditional, autoincrement, uuid andpadded.The traditional key generator generates numerical keys in ascending order.The autoincrement key generator generates numerical keys in ascending order, the inital offset and the spacing can be configured (note: autoincrement is currently only supported for non-sharded collections). The padded key generator generates keys of a fixed length (16 bytes) inascending lexicographical sort order. This is ideal for usage with the _RocksDB_engine, which will slightly benefit keys that are inserted in lexicographicallyascending order. The key generator can be used in a single-server or cluster.The uuid key generator generates universally unique 128 bit keys, which are stored in hexadecimal human-readable format. This key generator can be usedin a single-server or cluster to generate “seemingly random” keys. The keys produced by this key generator are not lexicographically sorted.
    • allowUserKeys: if set to true, then it is allowed to supplyown key values in the key attribute of a document. If set to_false, then the key generator will solely be responsible forgenerating keys and supplying own key values in the key_ attributeof 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.

  • numberOfShards (optional, default is 1): in a cluster, this valuedetermines the number of shards to create for the collection. In a singleserver setup, this option is meaningless.

  • shardKeys (optional, default is [ "_key" ]): in a cluster, thisattribute determines which document attributes are used to determine thetarget shard for documents. Documents are sent to shards based on thevalues they have in their shard key attributes. The values of all shardkey attributes in a document are hashed, and the hash value is used todetermine the target shard. Note that values of shard key attributes cannotbe changed once set.This option is meaningless in a single server setup.

When choosing the shard keys, one must be aware of the followingrules and limitations: In a sharded collection with more thanone shard it is not possible to set up a unique constraint onan attribute that is not the one and only shard key given inshardKeys. This is because enforcing a unique constraintwould otherwise make a global index necessary or need extensivecommunication for every single write operation. Furthermore, ifkey_ is not the one and only shard key, then it is not possibleto set the key_ attribute when inserting a document, providedthe collection has more than one shard. Again, this is becausethe database has to enforce the unique constraint on the __key_attribute and this can only be done efficiently if this is theonly shard key by delegating to the individual shards.

  • replicationFactor (optional, default is 1): in a cluster, thisattribute determines how many copies of each shard are kept on different DBServers. The value 1 means that only one copy (nosynchronous replication) is kept. A value of k means thatk-1 replicas are kept. Any two copies reside on different DBServers.Replication between them is synchronous, that is, every write operationto 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 theservers holding copies take over, usually without an error beingreported.

When using the Enterprise Edition of ArangoDB the replicationFactormay be set to “satellite” making the collection locally joinableon every database server. This reduces the number of network hopsdramatically when using joins in AQL at the costs of reduced writeperformance on these collections.

  • minReplicationFactor (optional, default is 1): in a cluster, thisattribute determines how many copies of each shard are requiredto be in sync on the different DBServers. If we have less then thesemany copies in the cluster a shard will refuse to write. TheminReplicationFactor can not be larger than replicationFactor.Please note: during server failures this might lead to writesnot being possible until the failover is sorted out and might causewrite slow downs in trade of data durability.

  • distributeShardsLike: distribute the shards of this collectioncloning the shard distribution of another. If this value is set,it will copy the attributes replicationFactor, numberOfShards and shardingStrategy from the other collection.

  • shardingStrategy (optional): specifies the name of the shardingstrategy to use for the collection. Since ArangoDB 3.4 there aredifferent sharding strategies to select from when creating a new collection. The selected shardingStrategy value will remainfixed for the collection and cannot be changed afterwards. This isimportant to make the collection keep its sharding settings andalways find documents already distributed to shards using the sameinitial sharding algorithm.

The available sharding strategies are:

  • community-compat: default sharding used by ArangoDBCommunity Edition before version 3.4
  • enterprise-compat: default sharding used by ArangoDBEnterprise Edition before version 3.4
  • enterprise-smart-edge-compat: default sharding used by smart edgecollections in ArangoDB Enterprise Edition before version 3.4
  • hash: default sharding used for new collections starting from version 3.4(excluding smart edge collections)
  • enterprise-hash-smart-edge: default sharding used for newsmart edge collections starting from version 3.4If no sharding strategy is specified, the default will be hash forall collections, and enterprise-hash-smart-edge for all smart edgecollections (requires the Enterprise Edition of ArangoDB). Manually overriding the sharding strategy does not yet provide a benefit, but it may later in case other sharding strategies are added.

In single-server mode, the shardingStrategy attribute is meaningless and will be ignored.

  • 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 smart join collection. Additionally, the sharding key for a document in this collection must contain the value of this attribute, followed by a colon, followed by the actual primary key of the document.

This feature can only be used in the Enterprise Edition and requires thedistributeShardsLike attribute of the collection to be set to the nameof another collection. It also requires the shardKeys attribute of thecollection to be set to a single shard key attribute, with an additional ‘:’at the end.A further restriction is that whenever documents are stored or updated in the collection, the value stored in the smartJoinAttribute must be a string.

db._create(collection-name, properties, type)

Specifies the optional type of the collection, it can either be document or edge. On default it is document. Instead of giving a type you can also use db._createEdgeCollection or db._createDocumentCollection.

db._create(collection-name, properties[, type], options)

As an optional third (if the type string is being omitted) or fourthparameter you can specify an optional options map that controls how thecluster will create the collection. These options are only relevant atcreation time and will not be persisted:

  • waitForSyncReplication (default: true)When enabled the server will only report success back to the clientif all replicas have created the collection. Set to false if you want fasterserver responses and don’t care about full replication.

  • enforceReplicationFactor (default: true)When enabled which means the server will check if there are enough replicasavailable at creation time and bail out otherwise. Set to false to disablethis extra check.

Examples

With defaults:

  1. arangosh> c = db._create("users");
  2. arangosh> c.properties();

Show execution results

  1. [ArangoCollection 73647, "users" (type document, status loaded)]
  2. { 
  3.   "isSystem" : false, 
  4.   "waitForSync" : false, 
  5.   "keyOptions" : { 
  6.     "allowUserKeys" : true, 
  7.     "type" : "traditional", 
  8.     "lastValue" : 0 
  9.   }, 
  10.   "cacheEnabled" : false 
  11. }

Hide execution results

With properties:

  1. arangosh> c = db._create("users", { waitForSync : true,
  2. ........> journalSize : 1024 * 1204});
  3. arangosh> c.properties();

Show execution results

  1. [ArangoCollection 73627, "users" (type document, status loaded)]
  2. { 
  3.   "isSystem" : false, 
  4.   "waitForSync" : true, 
  5.   "keyOptions" : { 
  6.     "allowUserKeys" : true, 
  7.     "type" : "traditional", 
  8.     "lastValue" : 0 
  9.   }, 
  10.   "cacheEnabled" : false 
  11. }

Hide execution results

With a key generator:

  1. arangosh> db._create("users",
  2. ........> { keyOptions: { type: "autoincrement", offset: 10, increment: 5 } });
  3. arangosh> db.users.save({ name: "user 1" });
  4. arangosh> db.users.save({ name: "user 2" });
  5. arangosh> db.users.save({ name: "user 3" });

Show execution results

  1. [ArangoCollection 73617, "users" (type document, status loaded)]
  2. { 
  3.   "_id" : "users/10", 
  4.   "_key" : "10", 
  5.   "_rev" : "_ZJNS5IG---" 
  6. }
  7. { 
  8.   "_id" : "users/15", 
  9.   "_key" : "15", 
  10.   "_rev" : "_ZJNS5IG--A" 
  11. }
  12. { 
  13.   "_id" : "users/20", 
  14.   "_key" : "20", 
  15.   "_rev" : "_ZJNS5IG--C" 
  16. }

Hide execution results

With a special key option:

  1. arangosh> db._create("users", { keyOptions: { allowUserKeys: false } });
  2. arangosh> db.users.save({ name: "user 1" });
  3. arangosh> db.users.save({ name: "user 2", _key: "myuser" });
  4. arangosh> db.users.save({ name: "user 3" });

Show execution results

  1. [ArangoCollection 73635, "users" (type document, status loaded)]
  2. { 
  3.   "_id" : "users/73640", 
  4.   "_key" : "73640", 
  5.   "_rev" : "_ZJNS5Im---" 
  6. }
  7. [ArangoError 1222: unexpected document key]
  8. { 
  9.   "_id" : "users/73643", 
  10.   "_key" : "73643", 
  11.   "_rev" : "_ZJNS5Iq---" 
  12. }

Hide execution results

creates a new edge collectiondb._createEdgeCollection(collection-name)

Creates a new edge collection named collection-name. If thecollection name already exists an error is thrown. The default valuefor waitForSync is false.

db._createEdgeCollection(collection-name, properties)

properties must be an object with the following attributes:

  • waitForSync (optional, default false): If true creatinga document will only return after the data was synced to disk.
  • journalSize (optional, default is “configuration parameter”): The maximal size ofa journal or datafile. Note that this also limits the maximalsize of a single object and must be at least 1MB.creates a new document collectiondb._createDocumentCollection(collection-name)

Creates a new document collection named collection-name. If thedocument name already exists and error is thrown.

All Collections

returns all collectionsdb._collections()

Returns all collections of the given database.

Examples

  1. arangosh> db._collections();

Show execution results

  1. [ 
  2.   [ArangoCollection 41, "_analyzers" (type document, status loaded)], 
  3.   [ArangoCollection 38, "_appbundles" (type document, status loaded)], 
  4.   [ArangoCollection 31, "_apps" (type document, status loaded)], 
  5.   [ArangoCollection 14, "_aqlfunctions" (type document, status loaded)], 
  6.   [ArangoCollection 4, "_graphs" (type document, status loaded)], 
  7.   [ArangoCollection 20, "_jobs" (type document, status loaded)], 
  8.   [ArangoCollection 17, "_queues" (type document, status loaded)], 
  9.   [ArangoCollection 68, "_statistics" (type document, status loaded)], 
  10.   [ArangoCollection 75, "_statistics15" (type document, status loaded)], 
  11.   [ArangoCollection 61, "_statisticsRaw" (type document, status loaded)], 
  12.   [ArangoCollection 7, "_users" (type document, status loaded)], 
  13.   [ArangoCollection 96, "animals" (type document, status loaded)], 
  14.   [ArangoCollection 90, "demo" (type document, status loaded)], 
  15.   [ArangoCollection 73886, "example" (type document, status loaded)] 
  16. ]

Hide execution results

Collection Name

selects a collection from the vocbasedb.collection-name

Returns the collection with the given collection-name. If no suchcollection exists, create a collection named collection-name with thedefault properties.

Examples

  1. arangosh> db.example;

Show execution results

  1. [ArangoCollection 73602, "example" (type document, status loaded)]

Hide execution results

Drop

drops a collectiondb._drop(collection)

Drops a collection and all its indexes and data.

db._drop(collection-identifier)

Drops a collection identified by collection-identifier with all itsindexes and data. No error is thrown if there is no such collection.

db._drop(collection-name)

Drops a collection named collection-name and all its indexes. No erroris thrown if there is no such collection.

db._drop(collection-name, options)

In order to drop a system collection, one must specify an options objectwith attribute isSystem set to true. Otherwise it is not possible todrop system collections.

Note: cluster collection, which are prototypes for collectionswith distributeShardsLike parameter, cannot be dropped.

Examples

Drops a collection:

  1. arangosh> col = db.example;
  2. arangosh> db._drop(col);
  3. arangosh> col;

Show execution results

  1. [ArangoCollection 73662, "example" (type document, status loaded)]
  2. [ArangoCollection 73662, "example" (type document, status loaded)]

Hide execution results

Drops a collection identified by name:

  1. arangosh> col = db.example;
  2. arangosh> db._drop("example");
  3. arangosh> col;

Show execution results

  1. [ArangoCollection 73669, "example" (type document, status loaded)]
  2. [ArangoCollection 73669, "example" (type document, status deleted)]

Hide execution results

Drops a system collection

  1. arangosh> col = db._example;
  2. arangosh> db._drop("_example", { isSystem: true });
  3. arangosh> col;

Show execution results

  1. [ArangoCollection 73676, "_example" (type document, status loaded)]
  2. [ArangoCollection 73676, "_example" (type document, status deleted)]

Hide execution results

Truncate

truncates a collectiondb._truncate(collection)

Truncates a collection, removing all documents but keeping all itsindexes.

db._truncate(collection-identifier)

Truncates a collection identified by collection-identified. No error isthrown if there is no such collection.

db._truncate(collection-name)

Truncates a collection named collection-name. No error is thrown ifthere is no such collection.

Examples

Truncates a collection:

  1. arangosh> col = db.example;
  2. arangosh> col.save({ "Hello" : "World" });
  3. arangosh> col.count();
  4. arangosh> db._truncate(col);
  5. arangosh> col.count();

Show execution results

  1. [ArangoCollection 73697, "example" (type document, status loaded)]
  2. { 
  3.   "_id" : "example/73702", 
  4.   "_key" : "73702", 
  5.   "_rev" : "_ZJNS6Sa--A" 
  6. }
  7. 1
  8. 0

Hide execution results

Truncates a collection identified by name:

  1. arangosh> col = db.example;
  2. arangosh> col.save({ "Hello" : "World" });
  3. arangosh> col.count();
  4. arangosh> db._truncate("example");
  5. arangosh> col.count();

Show execution results

  1. [ArangoCollection 73709, "example" (type document, status loaded)]
  2. { 
  3.   "_id" : "example/73714", 
  4.   "_key" : "73714", 
  5.   "_rev" : "_ZJNS6vu---" 
  6. }
  7. 1
  8. 0

Hide execution results