mirror of https://gitee.com/bigwinds/arangodb
660 lines
17 KiB
Plaintext
660 lines
17 KiB
Plaintext
!CHAPTER Getting Information about a Collection
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`collection-name (string,required)`
|
|
|
|
The name of the collection.
|
|
|
|
!SUBSECTION Description
|
|
|
|
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
|
|
|
|
Every other status indicates a corrupted collection.
|
|
|
|
* type: The type of the collection as number.
|
|
* 2: document collection (normal case)
|
|
* 3: edges collection
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 404`
|
|
|
|
If the collection-name is unknown, then a HTTP 404 is returned.
|
|
|
|
`GET /_api/collection/{collection-name}/properties`*(reads the properties of a collection)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`collection-name (string,required)`
|
|
|
|
The name of the collection.
|
|
|
|
!SUBSECTION Description
|
|
|
|
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 or changing a document will wait until the data has been synchronised to disk.
|
|
* doCompact: Whether or not the collection will be compacted.
|
|
* journalSize: The maximal size setting for journals / datafiles.
|
|
* 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.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 400`
|
|
|
|
If the collection-name is missing, then a HTTP 400 is returned.
|
|
|
|
`HTTP 404`
|
|
|
|
If the collection-name is unknown, then a HTTP 404 is returned.
|
|
|
|
*Examples*
|
|
|
|
Using an identifier:
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/collection/22012897/properties
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
location: /_db/_system/_api/collection/products/properties
|
|
|
|
{
|
|
"id" : "22012897",
|
|
"name" : "products",
|
|
"isSystem" : false,
|
|
"doCompact" : true,
|
|
"isVolatile" : false,
|
|
"journalSize" : 1048576,
|
|
"keyOptions" : {
|
|
"type" : "traditional",
|
|
"allowUserKeys" : true
|
|
},
|
|
"waitForSync" : true,
|
|
"status" : 3,
|
|
"type" : 2,
|
|
"error" : false,
|
|
"code" : 200
|
|
}
|
|
```
|
|
|
|
Using a name:
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/collection/products/properties
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
location: /_db/_system/_api/collection/products/properties
|
|
|
|
{
|
|
"id" : "22078433",
|
|
"name" : "products",
|
|
"isSystem" : false,
|
|
"doCompact" : true,
|
|
"isVolatile" : false,
|
|
"journalSize" : 1048576,
|
|
"keyOptions" : {
|
|
"type" : "traditional",
|
|
"allowUserKeys" : true
|
|
},
|
|
"waitForSync" : true,
|
|
"status" : 3,
|
|
"type" : 2,
|
|
"error" : false,
|
|
"code" : 200
|
|
}
|
|
```
|
|
|
|
`GET /_api/collection/{collection-name}/count`*(returns the number of documents in a collection)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`collection-name (string,required)`
|
|
|
|
The name of the collection.
|
|
|
|
!SUBSECTION Description
|
|
|
|
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.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 400`
|
|
|
|
If the collection-name is missing, then a HTTP 400 is returned.
|
|
|
|
`HTTP 404`
|
|
|
|
If the collection-name is unknown, then a HTTP 404 is returned.
|
|
|
|
*Examples*
|
|
|
|
Using an identifier and requesting the number of documents:
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/collection/22143969/count
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
location: /_db/_system/_api/collection/products/count
|
|
|
|
{
|
|
"id" : "22143969",
|
|
"name" : "products",
|
|
"isSystem" : false,
|
|
"doCompact" : true,
|
|
"isVolatile" : false,
|
|
"journalSize" : 1048576,
|
|
"keyOptions" : {
|
|
"type" : "traditional",
|
|
"allowUserKeys" : true
|
|
},
|
|
"waitForSync" : true,
|
|
"count" : 100,
|
|
"status" : 3,
|
|
"type" : 2,
|
|
"error" : false,
|
|
"code" : 200
|
|
}
|
|
```
|
|
|
|
`GET /_api/collection/{collection-name}/figures`*(returns the stats for a collection)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`collection-name (string,required)`
|
|
|
|
The name of the collection.
|
|
|
|
!SUBSECTION Description
|
|
|
|
In addition to the above, the result also contains the number of documents and additional statistical information about the collection. Note that this will always load the collection into memory.
|
|
|
|
* count: The number of documents currently present in the collection.
|
|
* figures.alive.count: The number of currently active documents.
|
|
* figures.alive.size: The total size in bytes used by all active documents.
|
|
* figures.dead.count: The number of dead documents. This includes document versions that have been deleted or replaced by a newer version.
|
|
* figures.dead.size: The total size in bytes used by all dead documents.
|
|
* figures.dead.deletion: The total number of deletion markers in the collection.
|
|
* figures.datafiles.count: The number of current datafiles.
|
|
* figures.datafiles.fileSize: The total filesize of all datafiles.
|
|
* figures.journals.count: The number of journal files.
|
|
* figures.journals.fileSize: The total filesize of all journal files.
|
|
* figures.compactors.count: The number of compactor files.
|
|
* figures.compactors.fileSize: The total filesize of all compactor files.
|
|
* figures.shapefiles.count: The number of shape files.
|
|
* figures.shapefiles.fileSize: The total filesize of all shape files.
|
|
* figures.shapes.count: The total number of shapes in the collection (this includes shapes that are not in use anymore)
|
|
* figures.attributes.count: The total number of attributes in the collection (this includes attributes that are not in use anymore)
|
|
* figures.attributes.size: The total size used by all attribute names in the collection (this includes attributes that are not in use anymore)
|
|
* figures.indexes.count: The total number of indexes defined for the collection (this includes internal indexes such as the primary index)
|
|
* figures.indexes.size: The total memory allocated by the indexes in bytes
|
|
* journalSize: The maximal size of the journal in bytes.
|
|
|
|
*Note*: 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.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 400`
|
|
|
|
If the collection-name is missing, then a HTTP 400 is returned.
|
|
|
|
`HTTP 404`
|
|
|
|
If the collection-name is unknown, then a HTTP 404 is returned.
|
|
|
|
*Examples*
|
|
|
|
Using an identifier and requesting the figures of the collection:
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/collection/42132449/figures
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
location: /_db/_system/_api/collection/products/figures
|
|
|
|
{
|
|
"id" : "42132449",
|
|
"name" : "products",
|
|
"isSystem" : false,
|
|
"doCompact" : true,
|
|
"isVolatile" : false,
|
|
"journalSize" : 1048576,
|
|
"keyOptions" : {
|
|
"type" : "traditional",
|
|
"allowUserKeys" : true
|
|
},
|
|
"waitForSync" : true,
|
|
"count" : 0,
|
|
"figures" : {
|
|
"alive" : {
|
|
"count" : 0,
|
|
"size" : 0
|
|
},
|
|
"dead" : {
|
|
"count" : 0,
|
|
"size" : 0,
|
|
"deletion" : 0
|
|
},
|
|
"datafiles" : {
|
|
"count" : 0,
|
|
"fileSize" : 0
|
|
},
|
|
"journals" : {
|
|
"count" : 0,
|
|
"fileSize" : 0
|
|
},
|
|
"compactors" : {
|
|
"count" : 0,
|
|
"fileSize" : 0
|
|
},
|
|
"shapefiles" : {
|
|
"count" : 0,
|
|
"fileSize" : 0
|
|
},
|
|
"shapes" : {
|
|
"count" : 0,
|
|
"size" : 0
|
|
},
|
|
"attributes" : {
|
|
"count" : 0,
|
|
"size" : 0
|
|
},
|
|
"indexes" : {
|
|
"count" : 1,
|
|
"size" : 88
|
|
}
|
|
},
|
|
"status" : 3,
|
|
"type" : 2,
|
|
"error" : false,
|
|
"code" : 200
|
|
}
|
|
```
|
|
|
|
`GET /_api/collection/{collection-name}/revision`*(return a collection revision id)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`collection-name (string,required)`
|
|
|
|
The name of the collection.
|
|
|
|
!SUBSECTION Description
|
|
|
|
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.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 400`
|
|
|
|
If the collection-name is missing, then a HTTP 400 is returned.
|
|
|
|
`HTTP 404`
|
|
|
|
If the collection-name is unknown, then a HTTP 404 is returned.
|
|
|
|
*Examples*
|
|
|
|
Retrieving the revision of a collection
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/collection/42329057/revision
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"id" : "42329057",
|
|
"name" : "products",
|
|
"isSystem" : false,
|
|
"status" : 3,
|
|
"type" : 2,
|
|
"revision" : "0",
|
|
"error" : false,
|
|
"code" : 200
|
|
}
|
|
```
|
|
|
|
`GET /_api/collection/{collection-name}/checksum`*(returns a checksum for the collection)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`collection-name (string,required)`
|
|
|
|
The name of the collection.
|
|
|
|
!SUBSECTION Query parameters
|
|
|
|
`withRevisions (boolean,optional)`
|
|
|
|
Whether or not to include document revision ids in the checksum calculation.
|
|
|
|
`withData (boolean,optional)`
|
|
|
|
Whether or not to include document body data in the checksum calculation.
|
|
|
|
!SUBSECTION Description
|
|
|
|
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 URL parameter withRevisions to true, then revision ids (_rev system attributes) are included in the checksumming.
|
|
|
|
By providing the optional URL parameter withData with a value of true, the user-defined document attributes will be included in the calculation too. Note that 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.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 400`
|
|
|
|
If the collection-name is missing, then a HTTP 400 is returned.
|
|
|
|
`HTTP 404`
|
|
|
|
If the collection-name is unknown, then a HTTP 404 is returned.
|
|
|
|
*Examples*
|
|
|
|
Retrieving the checksum of a collection:
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/collection/42460129/checksum
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"id" : "42460129",
|
|
"name" : "products",
|
|
"isSystem" : false,
|
|
"status" : 3,
|
|
"type" : 2,
|
|
"checksum" : 347093004,
|
|
"revision" : "42787809",
|
|
"error" : false,
|
|
"code" : 200
|
|
}
|
|
```
|
|
|
|
Retrieving the checksum of a collection including the collection data, but not the revisions:
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/collection/42984417/checksum?withRevisions=false&withData=true
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"id" : "42984417",
|
|
"name" : "products",
|
|
"isSystem" : false,
|
|
"status" : 3,
|
|
"type" : 2,
|
|
"checksum" : 3774865365,
|
|
"revision" : "43312097",
|
|
"error" : false,
|
|
"code" : 200
|
|
}
|
|
```
|
|
|
|
`GET /_api/collection`*(reads all collections)*
|
|
|
|
!SUBSECTION Query parameters
|
|
|
|
`excludeSystem (boolean,optional)`
|
|
|
|
Whether or not system collections should be excluded from the result.
|
|
|
|
!SUBSECTION Description
|
|
|
|
Returns an object with an attribute collections containing a list of all collection descriptions. The same information is also available in the names as hash map with the collection names as keys.
|
|
By providing the optional URL parameter excludeSystem with a value of true, all system collections will be excluded from the response.
|
|
|
|
*Examples*
|
|
|
|
Return information about all collections:
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/collection
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"collections" : [
|
|
{
|
|
"id" : "1565665",
|
|
"name" : "_cluster_kickstarter_plans",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "3466209",
|
|
"name" : "_aqlfunctions",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "1434593",
|
|
"name" : "_modules",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "19063777",
|
|
"name" : "demo",
|
|
"isSystem" : false,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "3662817",
|
|
"name" : "_configuration",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "19915745",
|
|
"name" : "animals",
|
|
"isSystem" : false,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "3531745",
|
|
"name" : "_trx",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "1500129",
|
|
"name" : "_routing",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "3072993",
|
|
"name" : "_aal",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "1369057",
|
|
"name" : "_graphs",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "3597281",
|
|
"name" : "_replication",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
{
|
|
"id" : "189409",
|
|
"name" : "_users",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
}
|
|
],
|
|
"names" : {
|
|
"_cluster_kickstarter_plans" : {
|
|
"id" : "1565665",
|
|
"name" : "_cluster_kickstarter_plans",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"_aqlfunctions" : {
|
|
"id" : "3466209",
|
|
"name" : "_aqlfunctions",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"_modules" : {
|
|
"id" : "1434593",
|
|
"name" : "_modules",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"demo" : {
|
|
"id" : "19063777",
|
|
"name" : "demo",
|
|
"isSystem" : false,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"_configuration" : {
|
|
"id" : "3662817",
|
|
"name" : "_configuration",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"animals" : {
|
|
"id" : "19915745",
|
|
"name" : "animals",
|
|
"isSystem" : false,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"_trx" : {
|
|
"id" : "3531745",
|
|
"name" : "_trx",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"_routing" : {
|
|
"id" : "1500129",
|
|
"name" : "_routing",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"_aal" : {
|
|
"id" : "3072993",
|
|
"name" : "_aal",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"_graphs" : {
|
|
"id" : "1369057",
|
|
"name" : "_graphs",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"_replication" : {
|
|
"id" : "3597281",
|
|
"name" : "_replication",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
},
|
|
"_users" : {
|
|
"id" : "189409",
|
|
"name" : "_users",
|
|
"isSystem" : true,
|
|
"status" : 3,
|
|
"type" : 2
|
|
}
|
|
},
|
|
"error" : false,
|
|
"code" : 200
|
|
}
|
|
```
|
|
|
|
<!--
|
|
@anchor HttpCollectionRead
|
|
@copydetails JSA_get_api_collection_name
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpCollectionReadProperties
|
|
@copydetails JSA_get_api_collection_properties
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpCollectionReadCount
|
|
@copydetails JSA_get_api_collection_count
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpCollectionReadFigures
|
|
@copydetails JSA_get_api_collection_figures
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpCollectionReadRevision
|
|
@copydetails JSA_get_api_collection_revision
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpCollectionReadChecksum
|
|
@copydetails JSA_get_api_collection_checksum
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpCollectionReadAll
|
|
@copydetails JSF_get_api_collections
|
|
|
|
@CLEARPAGE
|
|
--> |