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 Fauna Query Language or the GraphQL 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 ref, 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.

Field Type Definition and Requirements


Cannot be events, sets, self, documents, or _.


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


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. Defaults to 30 days.


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



Each collection has two configuration fields that control the retention of documents. By default, document history is stored for 30 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.

Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens) "expires" due to the setting in the ttl_days field, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal actually occurs.

For more immediate removal, use the ttl field on documents that should have limited lifespans. See Documents for details.

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email

Thank you for your feedback!