Fauna documents are immutable, meaning that once created they are fixed and unchangeable. When a document is updated, a new version is created with a new timestamp and updated data. Old versions of documents are retained in accordance with the history_days field of the collection they belong to. Individual documents and collections may also have a ttl (time to live) field. When a ttl period expires, all affected documents are deleted along with their document histories as if they never existed, and they cannot be retrieved with temporal queries. To learn more, see the temporality tutorial.

Every Fauna document includes a ts field to hold its timestamp. You can search an index for documents whose timestamp is at or before a specified time with the At function, and you can create an index to make a collection searchable by the ts field.

For demonstration purposes, let’s create a collection named temporal:

Next, add a document:

Next, create an index which includes the ts field in its values:

You can use the Paginate function to read out the contents of the temporal index:

In this case, we’ve used a custom result object to label each field in the index’s values definition.

Now let’s insert an event into the document’s history with a specific timestamp. The following example uses the Epoch function to construct a timestamp 1000 seconds after the Unix epoch date (1970-01-01T00:00:00Z) and the Insert function to add a create event to the document’s history.

If you read out the contents of the index again you can see that the original version of the document still exists, with its original timestamp. The Match function, which reads documents from the temporal index, retrieves the most recent version of the document; when we added a create event to the document we gave it an earlier timestamp, so its the original version we see now:

You can use the At function to retrieve the document with the earlier timestamp. The following example looks for documents created at or before one day after the Unix epoch date plus 1,000 seconds:

The document’s event history is a record of all events in the life of the document. The following example updates our document, adding an update event to the document’s history:

The document now has three events in its history. The following example uses the Events function to display them in order by timestamp: