Query best practices
This guide covers best practices for querying data in Fauna.
Use indexes for commonly accessed data
Indexes are the most important and effective tool to increase performance and reduce the cost of your queries.
Avoid uncovered queries whenever possible. To reduce document reads, include any frequently queried fields in indexes.
See Indexes |
---|
Use index terms for exact match searches
For the best performance, especially on large datasets, use an index with terms to filter collection documents based on an exact field value.
collection.where()
and
collection.firstWhere()
require a scan of the entire collection and aren’t performant on large
collections.
Avoid using frequently updated fields as index terms. See Avoid using frequently updated fields as index terms.
See Index terms |
---|
Avoid using frequently updated fields as index terms
Internally, Fauna partitions indexes based on its terms, if present. Frequent updates to term field values trigger updates to these partitions.
If you need to filter or run an exact match search on a frequently updated field, consider adding the field as an index value instead:
collection Product {
...
// Defines the `sortedByName()` index.
// The index includes the `name` field as an index value.
// `name` is a frequently updated field.
index sortedByName {
values [.name, .description, .price]
}
}
Then use the index to run a range search on the index value:
// Uses the `sortedByName()` index to run a range search
// on `name` field values. The query only retrieves `Product`
// collection documents with a `name` of `limes`. The query
// is covered and avoids document reads.
Product.sortedByName({ from: "limes", to: "limes" }) {
name,
description,
price
}
Use index values for sorting and range searches
For large collections, use index values instead of
set.order()
to sort a collection’s
documents. Reserve set.order()
for
small, ad-hoc sorting on sets of one page or less.
Similarly, avoid using
collection.where()
to
perform range searches on large collections. Instead, run a range search on
index values.
See Index values |
---|
Use projection to only retrieve fields you need
Projection lets you select the fields to return from a document or set.
For the best performance and costs, use an index and only project fields covered as an index term or value. This lets you read data from the index rather than the underlying documents.
To reduce unneeded compute operations, use projection to only fetch computed fields when needed. Computed fields aren’t persistently stored as part of the document. Instead, the field’s value is computed on each read.
See Projection and field aliasing |
---|
Return null
on document writes
Methods that create or write to a document, such as
Collection.create()
or
document.update()
, typically
return the document.
An FQL query only returns the result of its last statement. If you don’t use the
returned document, you can add a null
statement to the end of the query to
return null
instead. This can lower egress costs.
For example:
// The `update()` call writes to a `Product` collection document.
// `update()` returns the updated document.
Product.byId("<DOCUMENT_ID>")
?.update({ price: 75 })
// FQL queries return the result of the last statement.
// The `null` statement ensures the query returns `null`.
null
Use pageSize()
for pagination
In most cases, you should use
set.pageSize()
, not
set.paginate()
, to control the
page size of paginated results. Unlike pageSize()
, paginate()
:
-
Uses eager loading and fetches results instantly, even if the results aren’t returned or used. This can produce slower and more wasteful queries.
-
Is not compatible with Fauna client driver pagination methods.
See Pagination |
---|
Create UDFs for complex queries and workflows
A ser-defined function (UDF) is a set of one or more FQL statements stored as a reusable resource in a Fauna database.
UDFs are composable, letting you combine multiple UDFs to create more complex functions or workflows.
In most cases, a query that’s rewritten in multiple places or that involves complex logic should be stored as a UDF.
See User-defined functions (UDFs) |
---|
Use query logs to monitor query performance
You can use query logs to monitor the performance of your Fauna queries and diagnose issues.
Instrument your queries with query tags and traceparent identifiers. You can then aggregate the logs to identify trends or visualize the logs in an observability platform, such as Datadog.
See Query logs |
---|
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!