Best practices for Event Feeds and Event Streams

This guide covers best practices for creating and consuming event sources using Event Feeds or Event Streams.

Follow query best practices

When composing FQL queries for event sources, follow best practices for queries.

Manage the event source’s Set and shape

An event source’s cost and performance are closely related to its Set and shape.

For more details, see Costs and performance in the Event Feeds and Event Streams reference docs.

Use projection to limit event fields

Projection lets you select the fields to include in an event source’s events.

For the best performance and costs, use an index and only project fields covered as an index term or value. This lets the event source read data from the index rather than the underlying documents.

See Projecting only the data you need into the event source

Use index terms to filter tracked Sets

For the best performance, especially on large datasets, use an index with terms to filter collection documents based on an exact field value.

For example, instead of using collection.where() to perform an equality comparison:

let produce = Category.byName("produce").first()
let products = Product
                .where(.category == produce && .price < 100_00) {
                  category,
                  name,
                  description,
                  price
                }

products.eventSource()

You can create an index definition with category as an index term and price as an index value:

collection Product {
  ...
  index byCategory {
    terms [.category]
    values [.price, .name, .description]
  }
}

Then update the query to replace the equality comparison with an index call:

let produce = Category.byName("produce").first()
let products = Product
                .byCategory(produce)
                .where( .price < 100_00) {
                  category,
                  name,
                  description,
                  price
                }
products.eventSource()

See Index event sources

Use a key with a built-in role

If you don’t need identity-based authentication, use a key with a built-in role to authenticate Event Feed and Event Stream requests.

An event source only emits events for documents the authentication secret can access.

Event Feed and Event Stream requests that use a key with the same built-in role can access the same documents and always emit the same events. Internally, this lets Fauna unify event processing for these event sources.

Event sources that use a token or a JWT with user-defined roles may discard different events based on attribute-based access control (ABAC). To account for this, Fauna must process events for these event sources individually.

See Costs and performance

Use page cursors when using Event Feeds to track filtered Sets

When polling an event source using an Event Feed, use the feed’s top-level page cursor to periodically get events for a filtered Set.

The cursor tracks any events that were processed but not emitted for the event source. For strict filters, this can be a large number of events. Using the cursor can prevent excessive event replays and event limit errors.

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!