Collection Methods

Drop

drops a collectioncollection.drop(options)

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

Dropping a collection in a cluster, which is prototype for sharingin other collections is prohibited. In order to be able to dropsuch a collection, all dependent collections must be dropped first.

Examples

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

Show execution results

Hide execution results

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

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

Show execution results

Hide execution results

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

Truncate

truncates a collectioncollection.truncate()

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

Examples

Truncates a collection:

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

Show execution results

Hide execution results

[ArangoCollection 73966, "example" (type document, status loaded)]
{ 
  "_id" : "example/73971", 
  "_key" : "73971", 
  "_rev" : "_Z2KDPnu---" 
}
1
0

Compact

Introduced in: v3.4.5

Compacts the data of a collectioncollection.compact()

Compacts the data of a collection in order to reclaim disk space. For theMMFiles storage engine, the operation will reset the collection’s lastcompaction timestamp, so it will become a candidate for compaction. For theRocksDB storage engine, the operation will compact the document and indexdata by rewriting the underlying .sst files and only keeping the relevantentries.

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 datafor which the space shall be reclaimed. In this case the compaction operationcan be used.

Properties

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

Returns an object containing all collection properties.

• waitForSync: If true creating a document will only returnafter the data was synced to disk.

• journalSize : The size of the journal in bytes.This option is meaningful for the MMFiles storage engine only.

• isVolatile: If true then the collection data will bekept in memory only and ArangoDB will not write or sync the datato disk.This option is meaningful for the MMFiles storage engine only.

• keyOptions (optional) additional options for key generation. This isa JSON array containing the following attributes (note: some of theattributes are optional):

  • type: the type of the key generator used for the collection.
  • 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.
• indexBuckets: number of buckets into which indexes using a hashtable are split. The default is 16 and this number has to be apower of 2 and less than or equal to 1024.This option is meaningful for the MMFiles storage engine only.

For very large collections one should increase this to avoid long pauseswhen the hash table has to be initially built or resized, since bucketsare resized individually and can be initially built in parallel. Forexample, 64 might be a sensible value for a collection with 100000 000 documents. Currently, only the edge index respects thisvalue, but other index types might follow in future ArangoDB versions.Changes (see below) are applied when the collection is loaded the nexttime.

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 todetermine the target shard for documents.

• replicationFactor: determines how many copies of each shard are kept on different DBServers. Has to be in the range of 1-10. (cluster only)

• writeConcern: determines how many copies of each shard are required to bein sync on the different DBServers. If there are less then these many copiesin the cluster a shard will refuse to write. Writes to shards with enoughup-to-date copies will succeed at the same time however. The value ofwriteConcern 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 populatedin single-server mode. (cluster only)

collection.properties(properties)

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

• waitForSync: If true creating a document will only returnafter the data was synced to disk.

• journalSize: The size of the journal in bytes.This option is meaningful for the MMFiles storage engine only.

• indexBuckets: See above, changes are only applied when thecollection is loaded the next time.This option is meaningful for the MMFiles storage engine only.

• replicationFactor: Change the number of shard copies kept on different DBServers, valid values are integer numbersin the range of 1-10. (cluster only)

• writeConcern: change how many copies of each shard are required to bein sync on the different DBServers. If there are less then these many copiesin the cluster a shard will refuse to write. Writes to shards with enoughup-to-date copies will succeed at the same time however. The value ofwriteConcern can not be larger than replicationFactor. (cluster only)

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

Examples

Read all properties

arangosh> db.example.properties();
{ 
  "isSystem" : false, 
  "waitForSync" : false, 
  "keyOptions" : { 
    "allowUserKeys" : true, 
    "type" : "traditional", 
    "lastValue" : 0 
  }, 
  "writeConcern" : 1, 
  "cacheEnabled" : false 
}

Hide execution results

arangosh> db.example.properties();

Show execution results

Change a property

arangosh> db.example.properties({ waitForSync : true });
{ 
  "isSystem" : false, 
  "waitForSync" : true, 
  "keyOptions" : { 
    "allowUserKeys" : true, 
    "type" : "traditional", 
    "lastValue" : 0 
  }, 
  "writeConcern" : 1, 
  "cacheEnabled" : false 
}

Hide execution results

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

Show execution results

Figures

returns the figures of a collectioncollection.figures()

Returns an object containing statistics about the collection.

Retrieving the figures will always load the collection into memory.

• alive.count: The number of currently active documents in all datafiles andjournals of the collection. Documents that are contained in thewrite-ahead log only are not reported in this figure.
• alive.size: The total size in bytes used by all active documents of thecollection. Documents that are contained in the write-ahead log only arenot reported in this figure.
• dead.count: The number of dead documents. This includes documentversions that have been deleted or replaced by a newer version. Documentsdeleted or replaced that are contained in the write-ahead log only are notreported in this figure.
• dead.size: The total size in bytes used by all dead documents.
• dead.deletion: The total number of deletion markers. Deletion markersonly contained in the write-ahead log are not reporting in this figure.
• datafiles.count: The number of datafiles.
• datafiles.fileSize: The total filesize of datafiles (in bytes).
• journals.count: The number of journal files.
• journals.fileSize: The total filesize of the journal files(in bytes).
• compactors.count: The number of compactor files.
• compactors.fileSize: The total filesize of the compactor files(in bytes).
• shapefiles.count: The number of shape files. This value isdeprecated and kept for compatibility reasons only. The value will alwaysbe 0 since ArangoDB 2.0 and higher.
• shapefiles.fileSize: The total filesize of the shape files. Thisvalue is deprecated and kept for compatibility reasons only. The value willalways be 0 in ArangoDB 2.0 and higher.
• shapes.count: The total number of shapes used in the collection.This includes shapes that are not in use anymore. Shapes that are containedin the write-ahead log only are not reported in this figure.
• shapes.size: The total size of all shapes (in bytes). This includesshapes that are not in use anymore. Shapes that are contained in thewrite-ahead log only are not reported in this figure.
• attributes.count: The total number of attributes used in thecollection. Note: the value includes data of attributes that are not in useanymore. Attributes that are contained in the write-ahead log only arenot reported in this figure.
• attributes.size: The total size of the attribute data (in bytes).Note: the value includes data of attributes that are not in use anymore.Attributes that are contained in the write-ahead log only are not reported in this figure.
• indexes.count: The total number of indexes defined for thecollection, including the pre-defined indexes (e.g. primary index).
• indexes.size: The total memory allocated for indexes in bytes.
• lastTick: The tick of the last marker that was stored in a journalof the collection. This might be 0 if the collection does not yet havea journal.
• uncollectedLogfileEntries: The number of markers in the write-aheadlog for this collection that have not been transferred to journals ordatafiles.
• documentReferences: The number of references to documents in datafilesthat JavaScript code currently holds. This information can be used fordebugging compaction and unload issues.
• waitingFor: An optional string value that contains information aboutwhich object type is at the head of the collection’s cleanup queue. This information can be used for debugging compaction and unload issues.
• compactionStatus.time: The point in time the compaction for the collectionwas last executed. This information can be used for debugging compactionissues.
• compactionStatus.message: The action that was performed when the compactionwas last run for the collection. This information can be used for debuggingcompaction issues.

Note: collection data that are stored in the write-ahead log only arenot reported in the results. When the write-ahead log is collected, documentsmight be added to journals and datafiles of the collection, which may modify the figures of the collection. Also note that waitingFor and compactionStatus may be empty when called on a Coordinator in a cluster.

Additionally, the filesizes of collection and index parameter JSON files arenot reported. These files should normally have a size of a few byteseach. Please also note that the fileSize values are reported in bytesand reflect the logical file sizes. Some filesystems may use optimizations(e.g. sparse files) so that the actual physical file size is somewhatdifferent. Directories and sub-directories may also require space in thefile system, but this space is not reported in the fileSize results.

That means that the figures reported do not reflect the actual diskusage of the collection with 100% accuracy. The actual disk usage ofa collection is normally slightly higher than the sum of the reported fileSize values. Still the sum of the fileSize values can still be used as a lower bound approximation of the disk usage.

Examples

arangosh> db.demo.figures()

Show execution results

Hide execution results

{ 
  "indexes" : { 
    "count" : 1, 
    "size" : 1507 
  }, 
  "documentsSize" : 15173, 
  "cacheInUse" : false, 
  "cacheSize" : 0, 
  "cacheUsage" : 0 
}

GetResponsibleShard

returns the responsible shard for the given document.collection.getResponsibleShard(document)

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

The getResponsibleShard() method can only be used on Coordinatorsin clusters.

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 asobject attribute keys, and the responsible servers as an array mapped to eachshard attribute key.

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

The shards() method can only be used on Coordinators in clusters.

Load

loads a collectioncollection.load()

Loads a collection into memory.

Cluster collections are loaded at all times.

Examples

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

Show execution results

Hide execution results

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

Revision

returns the revision id of a collectioncollection.revision()

Returns the revision id of the collection

The revision id is updated when the document data is modified, either byinserting, deleting, updating or replacing documents in it.

The revision id of a collection can be used by clients to check whetherdata in a collection has changed or if it is still unmodified since aprevious fetch of the revision id.

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

Path

returns the physical path of the collectioncollection.path()

The path operation returns a string with the physical storage path forthe collection data.

The path() method will return nothing meaningful in a cluster.In a single-server ArangoDB, this method will only return meaningful datafor the MMFiles storage engine.

Checksum

calculates a checksum for the data in a collectioncollection.checksum(withRevisions, withData)

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

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

If the optional argument withData is set to true, then all user-defineddocument attributes are also checksummed. Including the document data inchecksumming will make the calculation slower, but is more accurate.

The checksum calculation algorithm changed in ArangoDB 3.0, so checksums from3.0 and earlier versions for the same data will differ.

The checksum() method can not be used in clusters.

Unload

unloads a collectioncollection.unload()

Starts unloading a collection from memory. Note that unloading is deferreduntil all query have finished.

Cluster collections cannot be unloaded.

Examples

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

Show execution results

Hide execution results

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

Rename

renames a collectioncollection.rename(new-name)

Renames a collection using the new-name. The new-name must notalready be used for a different collection. new-name must also be avalid collection name. For more information on valid collection names pleaserefer 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 inall graph definitions inside the _graphs collection in the currentdatabase.

The rename() method can not be used in clusters.

Examples

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

Show execution results

Hide execution results

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

Rotate

rotates the current journal of a collectioncollection.rotate()

Rotates the current journal of a collection. This operation makes thecurrent journal of the collection a read-only datafile so it may become acandidate for garbage collection. If there is currently no journal availablefor the collection, the operation will fail with an error.

The rotate() method is specific to the MMFiles storage engine and cannot be used in clusters.

You need appropriate user permissions to execute this.

• To do the rename collections in first place you need to haveadministrative rights on the database.
• To have access to the resulting renamed collection you either needto have access to all collections of that database (*) or a mainsystem administrator has to give you access to the newly named one.