Collections

A database’s schema is defined by its collections, which are similar to tables in other databases. Collections are containers for holding documents. To create a collection, use the CreateCollection function.

Once the collection has been created, it is possible to create documents within the collection using the FQL API.

A collection cannot be created and used in the same transaction.

It is possible to rename a collection by updating its name field. Renaming a collection changes its Reference, but preserves inbound references to the collection. Documents within the collection remain associated with the collection.

When a collection is deleted, associated documents become inaccessible and are deleted asynchronously.

Reading or writing collection’s metadata document (not the documents within the collection) requires a key with the server role or better, or equivalent Attribute-based access control (ABAC) permissions.

To learn more about common operations and functions related to collections, see Collection recipes.

Structure

Field Type Definition and Requirements

Field	Type	Definition and Requirements
`name`	String	The name of the collection. Cannot be `events`, `sets`, `self`, `documents`, or `_`. Cannot have the `%` character.
`data`	Object	Optional - A JSON object, for storing additional metadata about the collection.
`history_days`	Number	Optional - Document history is retained for at least this many days. When the number of days has elapsed, events older than the specified time window are removed. The current version of a document is retained. The default value is to zero days. See Temporality. See Temporality.
`ttl_days`	Number	Optional - Documents are deleted this many days after their last write. Defaults to `null`, which means that documents are always retained.
`permissions`	Object	Optional.

name

String

The name of the collection.

Cannot be events, sets, self, documents, or _. Cannot have the % character.

data

Object

Optional - A JSON object, for storing additional metadata about the collection.

history_days

Number

Optional - Document history is retained for at least this many days. When the number of days has elapsed, events older than the specified time window are removed. The current version of a document is retained. The default value is to zero days.

See Temporality.

ttl_days

Number

Optional - Documents are deleted this many days after their last write. Defaults to null, which means that documents are always retained.

permissions

Object

Optional.

Each collection has two configuration fields that control the retention of documents. By default, document history is stored for zero days. Set history_days to another value to keep more, or less, history. Setting history_days to null retains history indefinitely. Increasing retention increases storage utilization. See Billing for storage implications.

By setting a collection’s ttl_days, documents within the collection are removed as if they never existed if they have not been updated within the configured number of days.