Temporality is a Fauna feature that allows you to query your database at a specific point in time.
Whenever a document is created or updated, Fauna stores a new version
of the document along with the current transaction timestamp. Fauna
indexes also store the history of fields in the index’s
values definitions. The result is a record of the evolution of your
database that is automatically updated as changes occur.
At function allows you to execute a query expression at a
specific timestamp, and the results include documents or values that
existed in your database at that timestamp.
Temporal queries work as expected when document history exists. However, document history increases the amount of storage required for your database, and significant amounts of history can affect the performance of your queries. See Billing for more details.
If temporality is less important than billing and performance, we recommend using one or more of the following features to automatically remove document history, or to remove documents and their history:
|Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens), or history "expires" due to the settings described below, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal actually occurs.|
history_daysis a collection field that specifies the number of days of document history that should be maintained, for all documents within the collection. Once the specified number of days has elapsed, document history is removed, but the document itself is retained.
This feature is useful for any documents that change frequently and only the most recent versions are required. For example, any document that stores a rolling overage of some activity over the past month.
history_daysshould be set to zero for a collection storing counters, as those are often updated extremely frequently. Counters that update multiple times per second can quickly cause enough history to be retained to notably affect the performance of queries operating on the counter.
ttlis a document field that specifies the document’s time-to-live, which is when the document and all of its history should be removed. When a document is removed, the document’s existence ceases (as if it never existed); temporal queries cannot recover the document nor its history.
This is particularly useful for "intermediate" documents involved in gathering report data. These documents need to be retained while a complex report is being prepared, but after the report has been generated the documents can be removed automatically.
This feature should be used carefully because documents with
ttlset can be removed automatically. As such, the default
ttlis undefined, which means that document history is retained indefinitely.
As of API version 3, the
ttlfield is honored on read — a document that should have been removed behaves as if it has been removed. However, until removal actually occurs due to background task processing, you can continue to access the history of the document, provided you have its reference, via the
ttl_daysis a collection field that specifies the number of days that documents in the collection should be retained. Once the specified number of days has elapsed, any documents (and all of their history) whose age in days is greater are removed.
This feature could be useful for any documents that need to exist for short periods and you wish to avoid executing "maintenance" queries to remove the documents.
Is this article helpful?
Tell Fauna how the article can be improved:
Thank you for your feedback!