Best practices for Event Feeds and Event Streaming

This guide covers best practices for creating and consuming event streams using Event Feeds or Event Streaming.

Follow query best practices

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

Manage the stream’s source and shape

A stream’s cost and performance are closely related to its source and shape.

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

Use projection to limit event fields

Projection lets you select the fields to include in a stream’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 stream read data from the index rather than the underlying documents.

See Projecting only the data you need into the stream

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()
Product.where(.category == produce && .price < 100_00) {
  category, name, description, price }.toStream()

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()
Product.byCategory(produce).where( .price < 100_00) {
  category, name, description, price }.toStream()

See Optimize stream performance with indexes

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 stream requests.

A stream only emits events for documents the authentication secret can access.

Streams 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 streams.

Streams 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 streams individually.

See Costs and performance

Use page cursors when using Event Feeds to track filtered Sets

When polling a stream 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 stream. 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!