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: FSL 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 read ops, storage, latency, and indexing

Avoid storing unnecessary history. A high history_days setting has several impacts:

  • Increased read ops:

    To support temporal queries, indexes cover field values from both current documents and their historical document snapshots.

    To enable quicker sorting and range searches, current and historical index entries are stored together, sorted by index values. All indexes implicitly include an ascending document id as the index’s last value.

    When you read data from an index, including the collection.all() index, Fauna must read from both current and historical index entries to determine if they apply to the query. Fauna then filters out any data not returned by the query.

    You are charged for any Transactional Read Operations (TROs) used to read current or historical index data, including data not returned by the query.

    You are not charged for any historical data older than the retention period set by the history_days setting.

  • Longer index build times: Because indexes include historical data, a high history_days setting can increase the index build times.

  • Increased query latency on indexes: If an indexed field value changes frequently, the index must retain more historical data. A high history_days setting can increase query latency on the index.

  • Increased storage: More document snapshots and historical index data is retained, consuming additional database storage and increasing storage costs.

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!