Fauna documents are temporal, meaning that create, change, and delete events are assigned a transaction timestamp and inserted in the document history.
Temporality is a Fauna feature that allows you to query your database at a point in time. Working with documents temporally allows event sourcing, reactive programming, and various audit and stream-oriented data architectures.
When a document is created or updated, Fauna stores a new version
of the document with the current transaction timestamp. Fauna
indexes also store the history of fields in the index
values definitions. The result is a record of the evolution of your
database, updated as changes occur.
Temporal queries work as expected when document history exists. Note that document history increases the amount of storage required for your database, and significant amounts of history can affect the performance of your queries.
If temporality is less important than billing and performance, you should use one or more of the following features to remove document history or to remove documents and their history:
history_days field defines the number of days of document history to
maintain 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, a document that stores a rolling overage of some activity over the past month.
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 cause enough history to be
retained to noticeably affect the performance of queries operating on the
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.
ttl field is a document field
that specifies the document time-to-live, which is when the
document and all its history should be removed. When a document is
removed, document existence ceases as if it never existed.
Temporal queries cannot recover the document or its history.
This is particularly useful for intermediate documents involved in gathering report data. These documents must be retained during complex report preparation. After the report is generated, the documents are removed.
This feature should be used with caution because documents with
might be removed. As such, the default
ttl is undefined,
which means the document history is retained indefinitely.
ttl field behavior:
Queries using temporality return an error if the effective query timestamp is older than a collection
Indexes don’t report document events older than the
history_daysvalue in the source collections.
ttl_daysis set on a collection, a new documents
ttlfield is set according to the
ttltimestamp is passed, the document is removed, but its history continues to exist until the collection
ttl_days field is a collection field, which
is the number of days that documents in the
collection should be retained. After the number of days
elapses, documents whose age in days is greater are removed
with their history.
This feature can be useful for documents that must exist for short intervals, 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!