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.


Document history is retained for at least this many days. Defaults to 30 days.


Optional - Documents are deleted this many days after their last write. Defaults to 0, which means that automatic deletion is disabled.



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.

Is this article helpful? 

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

Thank you for your feedback!