Temporality is a Fauna feature that allows you to query your database at a specific point in time.
When 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 declared in the index
values definitions. The result is a record of the evolution of your
database that is 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. But, 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, Fauna recommends using one or more of the following features to remove document history, or to remove documents and their history:
field specifies the number of days of document history that
should be maintained, for all documents in the collection. After the
number of days elapses, document history is removed, but the
document is retained.
This feature is useful for documents that change frequently and only the most recent versions are required. For example, documents that store a rolling overage of some activity over the past month.
The default`history_days` value of zero is appropriate for a collection that stores counters because those are updated at a high rate. Counters that update multiple times per second can quickly cause enough history to be retained to noticeably affect the performance of queries operating on the counter.
history_days has the following behavior. If
smaller, such as changing the value from 10 days to zero days, history is
truncated as of the time of the collection document update, minus the new
history_days value. History before the new
history_days setting is
history_days becomes larger, such as changing the value from zero to 30
days, history begins accumulating as of the time of the collection document
history_days expires, history before the time of the update
to the collection becomes inaccessible.
ttlis a document field that specifies the time-to-live for the document, which is when the document and all of its history should be removed. When a document is removed, its existence ceases (as if it never existed) and temporal queries cannot recover the document or its history.
This is particularly useful for temporary documents involved in gathering report data. These documents need to be retained while a complex report is being prepared, but after the report is generated the documents can be removed.
This feature should be used carefully because documents with
ttlset can be removed without intervention. 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 be removed behaves as if removal has taken place. But, until removal occurs you can continue to access the history of the document, provided you have its reference, using the
ttlfield has the following behavior:
Indexes don’t report document events older than the
history_daysvalue in the source collections.
ttl_daysis set on a collection, new documents have the
ttlfield set according to the
ttltimestamp is passed, the document is removed but its history continues to exist until the collection
ttl_daysis a collection field that specifies the number of days that documents in the collection should be retained. After the number of days has elapsed, documents old enough are removed along with their history.
This feature could be useful for documents that need to exist for short periods and you want 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!