Getting Information about a Collection

Return information about a collection

returns a collection

GET /_api/collection/{collection-name}

Path Parameters

  • collection-name (required): The name of the collection.

The result is an object describing the collection with the following attributes:

  • id: The identifier of the collection.

  • name: The name of the collection.

  • status: The status of the collection as number.

    • 1: new born collection
    • 2: unloaded
    • 3: loaded
    • 4: in the process of being unloaded
    • 5: deleted
    • 6: loading

Every other status indicates a corrupted collection.

  • type: The type of the collection as number.

    • 2: document collection (normal case)
    • 3: edges collection

  • isSystem: If true then the collection is a system collection.

Return Codes

  • 404: If the collection-name is unknown, then a HTTP 404 is returned.

Read properties of a collection

reads the properties of the specified collection

GET /_api/collection/{collection-name}/properties

Path Parameters

  • collection-name (required): The name of the collection.

In addition to the above, the result will always contain the waitForSync, doCompact, journalSize, and isVolatile attributes. This is achieved by forcing a load of the underlying collection.

  • waitForSync: If true then creating, changing or removing documents will wait until the data has been synchronized to disk.

  • doCompact: Whether or not the collection will be compacted.

  • journalSize: The maximal size setting for journals / datafiles in bytes.

  • keyOptions: JSON object which contains key generation options:

    • type: specifies the type of the key generator. The currently available generators are traditional and autoincrement.
    • 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.

  • isVolatile: If true then the collection data will be kept in memory only and ArangoDB will not write or sync the data to disk.

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: contains how many copies of each shard are kept on different DBServers.

Example:

Using an identifier:

shell> curl --dump - http://localhost:8529/_api/collection/9530/properties

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
location: /_db/_system/_api/collection/products/properties

{ 
  "id" : "9530", 
  "name" : "products", 
  "isSystem" : false, 
  "doCompact" : true, 
  "isVolatile" : false, 
  "journalSize" : 33554432, 
  "keyOptions" : { 
    "type" : "traditional", 
    "allowUserKeys" : true, 
    "lastValue" : 0 
  }, 
  "waitForSync" : true, 
  "indexBuckets" : 8, 
  "status" : 3, 
  "type" : 2, 
  "error" : false, 
  "code" : 200 
}

Example:

Using a name:

shell> curl --dump - http://localhost:8529/_api/collection/products/properties

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
location: /_db/_system/_api/collection/products/properties

{ 
  "id" : "9534", 
  "name" : "products", 
  "isSystem" : false, 
  "doCompact" : true, 
  "isVolatile" : false, 
  "journalSize" : 33554432, 
  "keyOptions" : { 
    "type" : "traditional", 
    "allowUserKeys" : true, 
    "lastValue" : 0 
  }, 
  "waitForSync" : true, 
  "indexBuckets" : 8, 
  "status" : 3, 
  "type" : 2, 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 400: If the collection-name is missing, then a HTTP 400 is returned.
  • 404: If the collection-name is unknown, then a HTTP 404 is returned.

Examples

Using an identifier:

shell> curl --dump - http://localhost:8529/_api/collection/9530/properties

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
location: /_db/_system/_api/collection/products/properties
show response body

Using a name:

shell> curl --dump - http://localhost:8529/_api/collection/products/properties

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
location: /_db/_system/_api/collection/products/properties
show response body

Return number of documents in a collection

Counts the documents in a collection

GET /_api/collection/{collection-name}/count

Path Parameters

  • collection-name (required): The name of the collection.

In addition to the above, the result also contains the number of documents. Note that this will always load the collection into memory.

  • count: The number of documents inside the collection.

Example:

Requesting the number of documents:

shell> curl --dump - http://localhost:8529/_api/collection/products/count

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
location: /_db/_system/_api/collection/products/count

{ 
  "id" : "9192", 
  "name" : "products", 
  "isSystem" : false, 
  "doCompact" : true, 
  "isVolatile" : false, 
  "journalSize" : 33554432, 
  "keyOptions" : { 
    "type" : "traditional", 
    "allowUserKeys" : true, 
    "lastValue" : 9502 
  }, 
  "waitForSync" : true, 
  "indexBuckets" : 8, 
  "count" : 100, 
  "status" : 3, 
  "type" : 2, 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 400: If the collection-name is missing, then a HTTP 400 is returned.
  • 404: If the collection-name is unknown, then a HTTP 404 is returned.

Examples

Requesting the number of documents:

shell> curl --dump - http://localhost:8529/_api/collection/products/count

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
location: /_db/_system/_api/collection/products/count
show response body

Return statistics for a collection

Fetch the statistics of a collection

GET /_api/collection/{collection-name}/figures

Path Parameters

  • collection-name (required): The name of the collection.

In addition to the above, the result also contains the number of documents and additional statistical information about the collection. Note : This will always load the collection into memory.

Note: collection data that are stored in the write-ahead log only are not reported in the results. When the write-ahead log is collected, documents might be added to journals and datafiles of the collection, which may modify the figures of the collection.

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

That means that the figures reported do not reflect the actual disk usage of the collection with 100% accuracy. The actual disk usage of a 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.

A json document with these Properties is returned:

HTTP 200

Returns information about the collection:

  • count: The number of documents currently present in the collection.
  • journalSize: The maximal size of a journal or datafile in bytes.
  • figures:
    • datafiles:
      • count: The number of datafiles.
      • fileSize: The total filesize of datafiles (in bytes).
    • uncollectedLogfileEntries: The number of markers in the write-ahead log for this collection that have not been transferred to journals or datafiles.
    • documentReferences: The number of references to documents in datafiles that JavaScript code currently holds. This information can be used for debugging compaction and unload issues.
    • compactionStatus:
      • message: The action that was performed when the compaction was last run for the collection. This information can be used for debugging compaction issues.
      • time: The point in time the compaction for the collection was last executed. This information can be used for debugging compaction issues.
    • compactors:
      • count: The number of compactor files.
      • fileSize: The total filesize of all compactor files (in bytes).
    • dead:
      • count: The number of dead documents. This includes document versions that have been deleted or replaced by a newer version. Documents deleted or replaced that are contained the write-ahead log only are not reported in this figure.
      • deletion: The total number of deletion markers. Deletion markers only contained in the write-ahead log are not reporting in this figure.
      • size: The total size in bytes used by all dead documents.
    • indexes:
      • count: The total number of indexes defined for the collection, including the pre-defined indexes (e.g. primary index).
      • size: The total memory allocated for indexes in bytes.
    • readcache:
      • count: The number of revisions of this collection stored in the document revisions cache.
      • size: The memory used for storing the revisions of this collection in the document revisions cache (in bytes). This figure does not include the document data but only mappings from document revision ids to cache entry locations.
    • waitingFor: An optional string value that contains information about which object type is at the head of the collection's cleanup queue. This information can be used for debugging compaction and unload issues.
    • alive:
      • count: The number of currently active documents in all datafiles and journals of the collection. Documents that are contained in the write-ahead log only are not reported in this figure.
      • size: The total size in bytes used by all active documents of the collection. Documents that are contained in the write-ahead log only are not reported in this figure.
    • lastTick: The tick of the last marker that was stored in a journal of the collection. This might be 0 if the collection does not yet have a journal.
    • journals:
      • count: The number of journal files.
      • fileSize: The total filesize of all journal files (in bytes).
    • revisions:
      • count: The number of revisions of this collection managed by the storage engine.
      • size: The memory used for storing the revisions of this collection in the storage engine (in bytes). This figure does not include the document data but only mappings from document revision ids to storage engine datafile positions.

Example:

Using an identifier and requesting the figures of the collection:

shell> curl --dump - http://localhost:8529/_api/collection/products/figures

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
location: /_db/_system/_api/collection/products/figures

{ 
  "id" : "9507", 
  "name" : "products", 
  "isSystem" : false, 
  "doCompact" : true, 
  "isVolatile" : false, 
  "journalSize" : 33554432, 
  "keyOptions" : { 
    "type" : "traditional", 
    "allowUserKeys" : true, 
    "lastValue" : 9510 
  }, 
  "waitForSync" : false, 
  "indexBuckets" : 8, 
  "count" : 1, 
  "figures" : { 
    "indexes" : { 
      "count" : 1, 
      "size" : 32128 
    }, 
    "compactionStatus" : { 
      "message" : "skipped compaction because collection has no datafiles", 
      "time" : "2017-07-19T21:50:50Z" 
    }, 
    "documentReferences" : 0, 
    "waitingFor" : "-", 
    "alive" : { 
      "count" : 1, 
      "size" : 72 
    }, 
    "dead" : { 
      "count" : 0, 
      "size" : 0, 
      "deletion" : 0 
    }, 
    "datafiles" : { 
      "count" : 0, 
      "fileSize" : 0 
    }, 
    "journals" : { 
      "count" : 1, 
      "fileSize" : 33554432 
    }, 
    "compactors" : { 
      "count" : 0, 
      "fileSize" : 0 
    }, 
    "revisions" : { 
      "count" : 1, 
      "size" : 48192 
    }, 
    "lastTick" : 9512, 
    "uncollectedLogfileEntries" : 0 
  }, 
  "status" : 3, 
  "type" : 2, 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 200: Returns information about the collection:

Response Body

  • count: The number of documents currently present in the collection.
  • journalSize: The maximal size of a journal or datafile in bytes.
  • figures:
    • datafiles:
    • count: The number of datafiles.
    • fileSize: The total filesize of datafiles (in bytes).
    • uncollectedLogfileEntries: The number of markers in the write-ahead log for this collection that have not been transferred to journals or datafiles.
    • lastTick: The tick of the last marker that was stored in a journal of the collection. This might be 0 if the collection does not yet have a journal.
    • compactionStatus:
    • message: The action that was performed when the compaction was last run for the collection. This information can be used for debugging compaction issues.
    • time: The point in time the compaction for the collection was last executed. This information can be used for debugging compaction issues.
    • dead:
    • count: The number of dead documents. This includes document versions that have been deleted or replaced by a newer version. Documents deleted or replaced that are contained the write-ahead log only are not reported in this figure.
    • deletion: The total number of deletion markers. Deletion markers only contained in the write-ahead log are not reporting in this figure.
    • size: The total size in bytes used by all dead documents.
    • compactors:
    • count: The number of compactor files.
    • fileSize: The total filesize of all compactor files (in bytes).
    • readcache:
    • count: The number of revisions of this collection stored in the document revisions cache.
    • size: The memory used for storing the revisions of this collection in the document revisions cache (in bytes). This figure does not include the document data but only mappings from document revision ids to cache entry locations.
    • waitingFor: An optional string value that contains information about which object type is at the head of the collection's cleanup queue. This information can be used for debugging compaction and unload issues.
    • alive:
    • count: The number of currently active documents in all datafiles and journals of the collection. Documents that are contained in the write-ahead log only are not reported in this figure.
    • size: The total size in bytes used by all active documents of the collection. Documents that are contained in the write-ahead log only are not reported in this figure.
    • documentReferences: The number of references to documents in datafiles that JavaScript code currently holds. This information can be used for debugging compaction and unload issues.
    • indexes:
    • count: The total number of indexes defined for the collection, including the pre-defined indexes (e.g. primary index).
    • size: The total memory allocated for indexes in bytes.
    • journals:
    • count: The number of journal files.
    • fileSize: The total filesize of all journal files (in bytes).
    • revisions:
    • count: The number of revisions of this collection managed by the storage engine.
    • size: The memory used for storing the revisions of this collection in the storage engine (in bytes). This figure does not include the document data but only mappings from document revision ids to storage engine datafile positions.
shell> curl --dump - http://localhost:8529/_api/collection/products/figures

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
location: /_db/_system/_api/collection/products/figures
show response body

Return collection revision id

Retrieve the collections revision id

GET /_api/collection/{collection-name}/revision

Path Parameters

  • collection-name (required): The name of the collection.

In addition to the above, the result will also contain the collection's revision id. The revision id is a server-generated string that clients can use to check whether data in a collection has changed since the last revision check.

  • revision: The collection revision id as a string.

Example:

Retrieving the revision of a collection

shell> curl --dump - http://localhost:8529/_api/collection/products/revision

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "id" : "9538", 
  "name" : "products", 
  "isSystem" : false, 
  "status" : 3, 
  "type" : 2, 
  "revision" : "0", 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 400: If the collection-name is missing, then a HTTP 400 is returned.
  • 404: If the collection-name is unknown, then a HTTP 404 is returned.

Examples

Retrieving the revision of a collection

shell> curl --dump - http://localhost:8529/_api/collection/products/revision

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Return checksum for the collection

returns a checksum for the specified collection

GET /_api/collection/{collection-name}/checksum

Path Parameters

  • collection-name (required): The name of the collection.

Query Parameters

  • withRevisions (optional): Whether or not to include document revision ids in the checksum calculation.
  • withData (optional): Whether or not to include document body data in the checksum calculation.

Will calculate a checksum of the meta-data (keys and optionally revision ids) and optionally the document data in the collection.

The checksum can be used to compare if two collections on different ArangoDB instances contain the same contents. The current revision of the collection is returned too so one can make sure the checksums are calculated for the same state of data.

By default, the checksum will only be calculated on the _key system attribute of the documents contained in the collection. For edge collections, the system attributes _from and _to will also be included in the calculation.

By setting the optional query parameter withRevisions to true, then revision ids (_rev system attributes) are included in the checksumming.

By providing the optional query parameter withData with a value of true, the user-defined document attributes will be included in the calculation too. Note: Including user-defined attributes will make the checksumming slower.

The response is a JSON object with the following attributes:

  • checksum: The calculated checksum as a number.

  • revision: The collection revision id as a string.

Note: this method is not available in a cluster.

Example:

Retrieving the checksum of a collection:

shell> curl --dump - http://localhost:8529/_api/collection/products/checksum

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "id" : "9176", 
  "name" : "products", 
  "isSystem" : false, 
  "status" : 3, 
  "type" : 2, 
  "checksum" : "14386390800665990706", 
  "revision" : "_VTxS9gq---", 
  "error" : false, 
  "code" : 200 
}

Example:

Retrieving the checksum of a collection including the collection data, but not the revisions:

shell> curl --dump - http://localhost:8529/_api/collection/products/checksum?withRevisions=false&withData=true

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "id" : "9184", 
  "name" : "products", 
  "isSystem" : false, 
  "status" : 3, 
  "type" : 2, 
  "checksum" : "3247874159664609465", 
  "revision" : "_VTxS9jG---", 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 400: If the collection-name is missing, then a HTTP 400 is returned.
  • 404: If the collection-name is unknown, then a HTTP 404 is returned.

Examples

Retrieving the checksum of a collection:

shell> curl --dump - http://localhost:8529/_api/collection/products/checksum

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Retrieving the checksum of a collection including the collection data, but not the revisions:

shell> curl --dump - http://localhost:8529/_api/collection/products/checksum?withRevisions=false&withData=true

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

reads all collections

returns all collections

GET /_api/collection

Query Parameters

  • excludeSystem (optional): Whether or not system collections should be excluded from the result.

Returns an object with an attribute collections containing an array of all collection descriptions. The same information is also available in the names as an object with the collection names as keys.

By providing the optional query parameter excludeSystem with a value of true, all system collections will be excluded from the response.

Example:

Return information about all collections:

shell> curl --dump - http://localhost:8529/_api/collection

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "id" : "68", 
      "name" : "_appbundles", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "50", 
      "name" : "_apps", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "26", 
      "name" : "_aqlfunctions", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "43", 
      "name" : "_frontend", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "3", 
      "name" : "_graphs", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "47", 
      "name" : "_jobs", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "11", 
      "name" : "_modules", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "45", 
      "name" : "_queues", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "13", 
      "name" : "_routing", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "33", 
      "name" : "_statistics", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "38", 
      "name" : "_statistics15", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "28", 
      "name" : "_statisticsRaw", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "6", 
      "name" : "_users", 
      "isSystem" : true, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "89", 
      "name" : "animals", 
      "isSystem" : false, 
      "status" : 3, 
      "type" : 2 
    }, 
    { 
      "id" : "84", 
      "name" : "demo", 
      "isSystem" : false, 
      "status" : 3, 
      "type" : 2 
    } 
  ], 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 200: The list of collections

Examples

Return information about all collections:

shell> curl --dump - http://localhost:8529/_api/collection

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

© ArangoDB - the native multi-model NoSQL database