Document history

Fauna stores snapshots of each document’s history. Fauna creates these snapshots each time the document receives a write. Fauna indexes also store the history of index terms or values field values.

The historical snapshots act as versions of a document. You can use the snapshots to get a point-in-time view of documents and audit changes.

Run a temporal query

Reference: at expression

You can use an at expression to get a snapshot of one or more documents. This is called a temporal query.

For example, the following query retrieves a snapshot of a document from yesterday:

let yesterday = Time.now().subtract(1, "day")
at (yesterday) { Product.byName("avocados").first() }

If available, Fauna returns the document at the time of the at expression.

History retention

Reference: Collection schema

A collection schema's history_days field defines the number of days of history to retain as document snapshots:

collection Customer {
  // Number of days of document history to retain.
  history_days 3
}

After history_days passes, snapshots before the related time are deleted and become inaccessible. Temporal queries that attempt to access snapshots older than history_days return an error.

Default history days

history_days defaults to 0, which only retains the current version of each document. No history is retained.

Decreasing history days

If you decrease history_days, any snapshots created before the new history_days setting are deleted and become inaccessible.

Increasing history days

Increasing history_days does not recreate or recover previously inaccessible snapshots.

For example, increasing history_days from 0 to 7 does not recreate historical snapshots for the last 7 days. Instead, Fauna begins storing snapshots beginning at the time of the schema update.

Impacts on storage and latency

Avoid using history_days to store unnecessary history. Setting history_days to a high number causes a collection to retain more snapshots for each document. The snapshots consume database storage.

If collection documents are frequently updated, more snapshots are also stored.

When an indexed field is frequently updated, the index also retains the history of indexed fields. Over time, this can increase the query latency on the index.

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!