ArangoDB Collections API
Manage collections for organizing documents
OpenAPI Specification
openapi: 3.2.0
info:
contact:
name: ArangoDB Inc.
url: https://arango.ai
license:
name: Business Source License 1.1
url: https://github.com/arangodb/arangodb/blob/devel/LICENSE
summary: The HTTP API of the ArangoDB graph database system
title: ArangoDB Core Collections API
version: 3.12.10 (API v0)
description: Manage collections for organizing documents
tags:
- description: Manage collections for organizing documents
name: Collections
paths:
/_db/{database-name}/_api/collection:
get:
description: 'Returns basic information for all collections in the current database,
optionally excluding system collections.
'
operationId: listCollections
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'Whether system collections should be excluded from the result.
'
in: query
name: excludeSystem
required: false
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 200
type: integer
error:
description: 'A flag indicating that no error occurred.
'
example: false
type: boolean
result:
description: 'A list with every item holding basic collection metadata.
'
items:
properties:
globallyUniqueId:
description: 'A unique identifier of the collection. This is an internal property.
'
type: string
id:
description: 'A unique identifier of the collection (deprecated).
'
type: string
isSystem:
description: 'Whether the collection is a system collection. Collection names that starts with
an underscore are usually system collections.
'
example: false
type: boolean
name:
description: 'The name of the collection.
'
example: coll
type: string
status:
description: 'The status of the collection.
- `3`: loaded
- `5`: deleted
Every other status indicates a corrupted collection.
'
example: 3
type: integer
type:
description: 'The type of the collection:
- `0`: "unknown"
- `2`: regular document collection
- `3`: edge collection
'
example: 2
type: integer
required:
- id
- name
- status
- type
- isSystem
- globallyUniqueId
type: object
type: array
required:
- error
- code
- result
type: object
description: 'The list of collections.
'
summary: List all collections
tags:
- Collections
post:
description: 'Creates a new collection with a given name. The request must contain an
object with the following attributes.
'
operationId: createCollection
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The default is `true`, which means the server only reports success back to the
client when all replicas have created the collection. Set it to `false` if you want
faster server responses and don''t care about full replication.
'
in: query
name: waitForSyncReplication
required: false
schema:
default: true
type: boolean
- description: 'The default is `true`, which means the server checks if there are enough replicas
available at creation time and bail out otherwise. Set it to `false` to disable
this extra check.
'
in: query
name: enforceReplicationFactor
required: false
schema:
default: true
type: boolean
requestBody:
content:
application/json:
schema:
properties:
cacheEnabled:
default: false
description: '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.
'
type: boolean
computedValues:
description: 'An optional list of objects, each representing a computed value.
'
items:
properties:
computeOn:
default:
- insert
- update
- replace
description: 'An array of strings to define on which write operations the value shall be
computed.
'
items:
enum:
- insert
- update
- replace
type: string
type: array
uniqueItems: true
expression:
description: 'An AQL `RETURN` operation with an expression that computes the desired value.
See [Computed Value Expressions](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/computed-values/#computed-value-expressions) for details.
'
type: string
failOnWarning:
default: false
description: 'Whether to let the write operation fail if the expression produces a warning.
'
type: boolean
keepNull:
default: true
description: 'Whether the target attribute shall be set if the expression evaluates to `null`.
You can set the option to `false` to not set (or unset) the target attribute if
the expression returns `null`.
'
type: boolean
name:
description: 'The name of the target attribute. Can only be a top-level attribute, but you
may return a nested object. Cannot be `_key`, `_id`, `_rev`, `_from`, `_to`,
or a shard key attribute.
'
type: string
overwrite:
description: 'Whether the computed value shall take precedence over a user-provided or
existing attribute.
'
type: boolean
required:
- name
- expression
- overwrite
type: object
type: array
distributeShardsLike:
default: ''
description: 'The name of another collection. If this property is set in a cluster, the
collection follows the `replicationFactor`, `numberOfShards` and `shardingStrategy`
properties of the specified collection (referred to as the
_prototype collection_ or sometimes _initial collection_)
and distributes the shards of this collection in the same way as the shards of
the other collection. This data co-location is utilized to optimize queries.
You need to use the same number of `shardKeys` as the prototype collection, but
you can use different attributes.
> **INFO:**
Using this parameter has consequences for the prototype
collection. It can no longer be dropped, before the sharding-imitating
collections are dropped. Equally, backups and restores of imitating
collections alone generate warnings (which can be overridden)
about a missing sharding prototype.
'
type: string
isDisjoint:
description: 'Whether the collection is for a Disjoint SmartGraph.
This is an internal property.
'
type: boolean
isSmart:
description: 'Whether the collection is for a SmartGraph or EnterpriseGraph.
This is an internal property.
'
type: boolean
isSystem:
default: false
description: 'If `true`, create a system collection. In this case, the `collection-name`
should start with an underscore. End-users should normally create non-system
collections only. API implementors may be required to create system
collections in very special occasions, but normally a regular collection will do.
'
type: boolean
keyOptions:
description: 'additional options for key generation. If specified, then `keyOptions`
should be a JSON object containing the following attributes:
'
properties:
allowUserKeys:
default: true
description: 'If set to `true`, then you are allowed to supply own key values in the
`_key` attribute of documents. If set to `false`, then the key generator
is solely responsible for generating keys and an error is raised if you
supply own key values in the `_key` attribute of documents.
> **WARNING:**
You should not use both user-specified and automatically generated document keys
in the same collection in cluster deployments for collections with more than a
single shard. Mixing the two can lead to conflicts because Coordinators that
auto-generate keys in this case are not aware of all keys which are already used.
'
type: boolean
increment:
default: 1
description: 'The increment value for the `autoincrement` key generator.
Not allowed for other key generator types.
'
type: integer
offset:
default: 0
description: 'The initial offset value for the `autoincrement` key generator.
Not allowed for other key generator types.
'
type: integer
type:
default: traditional
description: "specifies the type of the key generator. The currently available generators are\n`traditional`, `autoincrement`, `uuid` and `padded`.\n\n- The `traditional` key generator generates numerical keys in ascending order.\n The sequence of keys is not guaranteed to be gap-free.\n\n- The `autoincrement` key generator generates numerical keys in ascending order,\n the initial offset and the spacing can be configured (**note**: `autoincrement`\n is only supported for non-sharded collections).\n The sequence of generated keys is not guaranteed to be gap-free, because a new key\n will be generated on every document insert attempt, not just for successful\n inserts.\n\n- The `padded` key generator generates keys of a fixed length (16 bytes) in\n ascending lexicographical sort order. This is ideal for the RocksDB storage engine,\n which will slightly benefit keys that are inserted in lexicographically\n ascending order. The key generator can be used in a single-server or cluster.\n The sequence of generated keys is not guaranteed to be gap-free.\n\n- The `uuid` key generator generates universally unique 128 bit keys, which\n are stored in hexadecimal human-readable format. This key generator can be used\n in a single-server or cluster to generate \"seemingly random\" keys. The keys\n produced by this key generator are not lexicographically sorted.\n\nPlease note that keys are only guaranteed to be truly ascending in single\nserver deployments and for collections that only have a single shard (that includes\ncollections in a OneShard database).\nThe reason is that for collections with more than a single shard, document keys\nare generated on Coordinator(s). For collections with a single shard, the document\nkeys are generated on the leader DB-Server, which has full control over the key\nsequence.\n"
type: string
type: object
name:
description: 'The name of the collection.
'
type: string
numberOfShards:
default: 1
description: 'In a cluster, this value determines the
number of shards to create for the collection.
Default:
If `distributeShardsLike` is set, the `numberOfShards`
is that of the indicated prototype collection.
'
type: integer
replicationFactor:
description: 'In a cluster, this attribute determines how many copies
of each shard are kept on different DB-Servers. The value 1 means that only one
copy (no synchronous replication) is kept. A value of k means that k-1 replicas
are kept. For SatelliteCollections, it needs to be the string `"satellite"`,
which matches the replication factor to the number of DB-Servers.
Any two copies reside on different DB-Servers. Replication between them is
synchronous, that is, every write operation to 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 the servers holding
copies take over, usually without an error being reported.
Default:
If `distributeShardsLike` is set, the default `replicationFactor`
is that of the indicated prototype collection. Otherwise,
the default `replicationFactor` is defined by the database.
'
type: integer
schema:
description: 'The configuration of the collection-level schema validation for documents.
'
properties:
level:
default: strict
description: "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n"
enum:
- none
- new
- moderate
- strict
type: string
message:
description: 'The error message to raise if the schema validation fails
for a document.
'
type: string
rule:
description: 'A [JSON Schema](https://json-schema.org/specification-links#draft-4)
object (draft-4, without remote schemas).
See [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)
for details.
'
type: object
required:
- rule
type: object
shardKeys:
default:
- _key
description: 'In a cluster, this attribute determines
which document attributes are used to determine the target shard for documents.
Documents are sent to shards based on the values of their shard key attributes.
The values of all shard key attributes in a document are hashed,
and the hash value is used to determine the target shard.
> **INFO:**
Values of shard key attributes cannot be changed once set.
'
type: string
shardingStrategy:
description: "This attribute specifies the name of the sharding strategy to use for\nthe collection. There are different sharding strategies\nto select from when creating a new collection. The selected `shardingStrategy`\nvalue remains fixed for the collection and cannot be changed afterwards.\nThis is important to make the collection keep its sharding settings and\nalways find documents already distributed to shards using the same\ninitial sharding algorithm.\n\nThe available sharding strategies are:\n- `community-compat`: default sharding used by ArangoDB\n Community Edition before version 3.4\n- `enterprise-compat`: default sharding used by ArangoDB\n Enterprise Edition before version 3.4\n- `enterprise-smart-edge-compat`: default sharding used by smart edge\n collections in ArangoDB Enterprise Edition before version 3.4\n- `hash`: default sharding used for new collections starting from version 3.4\n (excluding smart edge collections)\n- `enterprise-hash-smart-edge`: default sharding used for new\n smart edge collections starting from version 3.4\n- `enterprise-hex-smart-vertex`: sharding used for node collections of\n EnterpriseGraphs\n\nDefault:\nIf `distributeShardsLike` is set, the `shardingStrategy`\nis that of the indicated prototype collection. Otherwise,\nif no sharding strategy is specified, the default is `hash` for\nall normal collections, `enterprise-hash-smart-edge` for all smart edge\ncollections, and `enterprise-hex-smart-vertex` for EnterpriseGraph\nnode collections.\nManually overriding the sharding strategy does not yet provide a\nbenefit, but it may later in case other sharding strategies are added.\n"
type: string
smartGraphAttribute:
description: 'The attribute that is used for sharding: nodes with the same value of
this attribute are placed in the same shard. All nodes are required to
have this attribute set and it has to be a string. Edges derive the
attribute from their connected nodes.
'
type: string
smartJoinAttribute:
description: 'In a cluster, this attribute determines an attribute
of the collection that must contain the shard key value of the referred-to
SmartJoin collection. Additionally, the shard 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 requires the
`distributeShardsLike` attribute of the collection to be set to the name
of another collection. It also requires the `shardKeys` attribute of the
collection 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.
'
type: string
type:
default: 2
description: 'The type of the collection to create.
The following values for `type` are valid:
- `2`: document collection
- `3`: edge collection
'
type: integer
waitForSync:
default: false
description: 'If set to `true`, then the data is synchronized to disk before returning from a
document create, update, replace or removal operation.
'
type: boolean
writeConcern:
description: 'Determines how many copies of each shard are required to be
in sync on the different DB-Servers. If there are less than these many copies
in the cluster, a shard refuses to write. Writes to shards with enough
up-to-date copies succeed at the same time, however. The value of
`writeConcern` cannot be greater than `replicationFactor`.
Default: If `distributeShardsLike` is set when the collection is created,
the initial `writeConcern` defaults to that of the indicated
prototype collection. Afterwards, `writeConcern` is independent
from the prototype collection and can differ from it.
For SatelliteCollections, the `writeConcern` is automatically controlled to
equal the number of DB-Servers and has a value of `0`.
Otherwise, the default value is controlled by the current database''s
default `writeConcern`, which uses the `--cluster.write-concern`
startup option as default, which defaults to `1`. _(cluster only)_
'
type: integer
required:
- name
type: object
responses:
'200':
content:
application/json:
schema:
properties:
cacheEnabled:
description: 'Whether the in-memory hash cache for documents is enabled for this
collection.
'
type: boolean
code:
description: 'The HTTP response status code.
'
example: 200
type: integer
computedValues:
description: 'A list of objects, each representing a computed value.
'
items:
properties:
computeOn:
description: 'An array of strings that defines on which write operations the value is
computed.
'
example:
- insert
- update
- replace
items:
enum:
- insert
- update
- replace
type: string
type: array
uniqueItems: true
expression:
description: 'An AQL `RETURN` operation with an expression that computes the desired value.
'
type: string
failOnWarning:
description: 'Whether the write operation fails if the expression produces a warning.
'
type: boolean
keepNull:
description: 'Whether the target attribute is set if the expression evaluates to `null`.
'
type: boolean
name:
description: 'The name of the target attribute.
'
type: string
overwrite:
description: 'Whether the computed value takes precedence over a user-provided or
existing attribute.
'
type: boolean
required:
- name
- expression
- overwrite
type: object
type: array
distributeShardsLike:
description: '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.
'
type: string
error:
description: 'A flag indicating that no error occurred.
'
example: false
type: boolean
globallyUniqueId:
description: 'A unique identifier of the collection. This is an internal property.
'
type: string
id:
description: 'A unique identifier of the collection (deprecated).
'
type: string
isDisjoint:
description: 'Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint.
This is an internal property. _(cluster only)_
'
type: boolean
isSmart:
description: 'Whether the collection is used in a SmartGraph or EnterpriseGraph.
This is an internal property. _(cluster only)_
'
type: boolean
isSystem:
description: 'Whether the collection is a system collection. Collection names that starts with
an underscore are usually system collections.
'
type: boolean
keyOptions:
description: 'An object which contains key generation options.
'
properties:
allowUserKeys:
description: 'If set to `true`, then you are 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 an error is raised if you supply own key values in the
`_key` attribute of documents.
> **WARNING:**
You should not use both user-specified and automatically generated document keys
in the same collection in cluster deployments for collections with more than a
single shard. Mixing the two can lead to conflicts because Coordinators that
auto-generate keys in this case are not aware of all keys which are already used.
'
type: boolean
increment:
description: 'The increment value for the `autoincrement` key generator.
Not used by other key generator types.
'
type: integer
lastValue:
description: 'The offset value for the `autoincrement` or `padded` key generator.
This is an internal property for restoring dumps properly.
'
type: integer
offset:
description: 'The initial offset value for the `autoincrement` key generator.
Not used by other key generator types.
'
type: integer
type:
description: 'Specifies the type of the key generator.
'
enum:
- traditional
- autoincrement
- uuid
- padded
type: string
required:
- type
- allowUserKeys
type: object
name:
description: 'The name of this collection.
'
type: string
numberOfShards:
description: 'The number of shards of the collection. _(cluster only)_
'
type: integer
replicationFactor:
description: 'Contains how many copies of each shard are kept on different DB-Servers.
It is an integer number in the range of 1-10 or the string `"satellite"`
for SatelliteCollections. _(cluster only)_
If `distributeShardsLike` is set, the actual replication factor
is that of the indicated prototype collection. Query the
prototype collection to get the current `replicationFactor`
for this collection. The reported `replicationFactor` of
this collection is the value as of the time at which the
collection was created, but it may have been changed
# --- truncated at 32 KB (232 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arangodb/refs/heads/main/openapi/arangodb-collections-api-openapi.yml