Event Feeds and Event Streaming reference

To start an event stream and request an Event Feed for the stream, the client driver sends a request containing a stream token to the Change Feed HTTP API endpoint.

When you first poll an event stream using an Event Feed, you usually specify a start_ts (start timestamp). start_ts is an integer representing a time in microseconds since the Unix epoch. The request returns events that occurred after the specified timestamp (exclusive).

page_size limits the number of events returned per page:

The response includes an array of events for the stream:

If the response’s has_next property is true, the response includes a top-level cursor property. The client driver can use this cursor to get the next page of events:

Response:

To get events after a specific time, the client driver uses the start_ts request body parameter:

start_ts must be later than the creation time of the stream token. The period between the request and the start_ts can’t exceed the history_days setting for the source Set’s collection. If history_days is 0 or unset, the period is limited to 15 minutes.

To get events from a previous event’s cursor, the client driver uses the cursor request body parameter. The stream will replay events that occurred after the cursor (exclusive):

The period between the request and the cursor event’s txn_ts (transaction timestamp) can’t exceed the history_days setting for the source Set’s collection. If history_days is 0 or unset, the period is limited to 15 minutes.

To start and subscribe to an event stream’s events in real time, the client driver sends a request containing the stream token to the Stream HTTP API endpoint:

In response, the stream emits a status event, indicating the subscription has started.

The Stream API request's connection remains open. If a tracked change occurs, the stream emits a related add, remove, or update event. These events include the triggering document, encoded using the tagged format, in the data field:

If a change occurs between the creation of the stream token and the start of a stream, the stream replays and emits the related events when the stream starts.

Fauna’s client drivers can detect connection loss and automatically reconnect disconnected Event Streaming subscriptions. Events that occur during network issues are replayed and emitted when the subscription reconnects.

When a subscription reconnects, the stream emits a new status event:

The Stream HTTP API endpoint supports two methods for restarting disconnected stream subscriptions:

The methods are mutually exclusive and can’t be used together.

The Event Streaming sample app show how you can use Event Streaming to build a real-time chat app. You can use it as a starting point for your own app.

If the authentication secret used to start a subscription is revoked or the secret’s privileges change, the subscription using the token closes due to permission loss. This applies even if the secret still has access to the documents the stream is tracking.

Calling set.toStream() directly on collection.all() tracks any change to any document in the collection.

The following query tracks any change to documents in the Product collection:

For example, if you change a Product document’s price to below 100_00, the stream emits an update event.

You can use collection.where() to filter the tracked documents for a collection.

For example, the following query only tracks Product documents with a price of less than 100_00.

If you change a Product document’s price from above 100_00 to below 100_00, the stream emits an add event. Before the change, the document would not have been part of the stream’s Set.

You can use set.changesOn() to only track changes to specific fields.

The following query tracks changes made to any Product document’s description. The stream doesn’t emit events for changes to other fields.

Index streams only emit events for changes to the index’s terms or values fields.

For example, the following Product collection’s byCategory() index has:

The following query only tracks changes to the category, name, or price fields for Product documents with a category of produce.

When called on an index, set.changesOn() only accepts the index’s terms or values fields as arguments.

For example, in the following query, set.changesOn() only accepts .category, .name, or .price as arguments.

You can use streams to track changes to a Set containing a single document. These streams only emit events when the document changes.

Use Set.single() to create a Set from a document.

Use set.changesOn() to only track changes to specific fields of the document.

If the database or source for a stream is deleted, the stream won’t emit any further events. Subscriptions for the stream don’t automatically close.

Use set.where() to filter a stream’s source Set.

For example, the following query only tracks changes to Product documents with:

You can also call set.where() directly on set.toStream() or set.changesOn(). The following query is equivalent to the previous one.

set.where() produces a new Set based on its criteria. The criteria affect the event types emitted for changes:

While filters affect events emitted for a stream, they don’t affect event processing, which impacts performance and cost. See How filters affect costs and performance.

A stream’s add and update event types include a data field. This field contains the document that triggered the event.

Use set.map() or projection to return only specific document fields in these events.

For example, the following query tracks changes to any field in any Product document. The query uses set.map() to only include the name and price document fields in the data field of add and update events.

The following query uses projection and is equivalent to the previous one.

The previous queries can produce the following add event. The event’s data field includes only the name and price document fields.

Events are ordered by ascending txn_ts (transaction timestamp). Events from the same transaction share the same txn_ts, but their order may differ across clients.

The following table outlines supported event types.

Events with a type other than status or error have the following schema:

status event types have the following schema:

error event types have the following schema:

The following table outlines possible error codes for error events.

Streams may discard events based on filters.

For example, a stream with the following query uses a filter to only emit events for Product documents with a category of produce:

To do this, Fauna processes an event for any change to any Product document. It then discards events for documents without a category of produce. These discarded events still consume operations for your account.

To track changes on a large Set, we recommend using an index stream.

For example, the following stream emits events similar to the previous one. However, it only tracks the index’s terms and values fields:

Another source of discarded events is privilege predicates in roles. For example, the following role uses predicates to grant its members read and write access only to Product documents with a category of produce:

A stream token created using an authentication secret with this role only emits events for documents the role can access. Other events are discarded. These discarded events still consume operations for your account.