Performance hints

Performance hints provide actionable steps for improving an FQL query’s performance. You typically use performance hints when testing or prototyping queries in the Fauna Dashboard Shell.

Enable performance hints

Performance hints are disabled by default. To enable hints in the Dashboard Shell, toggle Performance Hints .

Enable performance hints in the Dashboard

Example

As an example, Fauna emits performance hints for uncovered index queries. The following FQL query uses an index but projects fields that aren’t covered by the index definition:

// This is an uncovered query.
// `stock` is not one of the terms or values
// in the `sortedByPriceLowToHigh()` index definition.
Product.sortedByPriceLowToHigh() {
  name,
  stock
}

In the Dashboard Shell, the result includes a performance hint, if enabled:

performance_hint: non_covered_document_read - .stock is not covered by the Product.sortedByPriceLowToHigh index. See https://docs.fauna.com/performance_hint/non_covered_document_read.
at *query*:6:3
  |
6 |   stock
  |   ^^^^^
  |

{
  data: [
    ...
  ]
}

Performance hint codes

Each performance hint includes a leading code that indicates its type.

The following table provides a description of each hint type, along with examples and resolutions to address the hint.

Hint code Description Examples and resolutions

Hint code	Description	Examples and resolutions
`collection_scan`	The query calls `collection.firstWhere()` or `collection.where()` on a collection. This can cause a billable read of every document in the collection. To address the hint, use an index with a `terms` to look up matching documents instead.	`collection.firstWhere()` `collection.where()`
`non_covered_document_read`	Returned for uncovered index queries. The query uses an index but returns entire documents or field values not covered by the index. Consider adding the uncovered fields to the index definition’s `values`. Then use projection or mapping to return only the fields you need. Fauna does not return the `non_covered_document_read` performance hint for uncovered index queries that pass an `mva()` term.	Uncovered index queries Index queries with no projection or mapping
`full_set_read`	The query calls an eager-loading method on a document Set. To address the hint, do one of the following: Use `set.take()` to explicitly limit the size of the calling Set to fewer than 100 documents. This applies even if the original, unbounded Set contains fewer than 100 documents. Rewrite the query to avoid calling the method. Alternatively, the query calls `set.order()` on a document Set, causing all documents in the Set to be read. If you frequently run such queries, consider adding the fields used for ordering to an index definition’s `values`.	`set.aggregate()` `set.count()` `set.distinct()` `set.every()` `set.fold()` `set.foldRight()` `set.forEach()` `set.includes()` `set.order()` `set.reduce()` `set.reduceRight()` `set.toArray()`

collection_scan

The query calls collection.firstWhere() or collection.where() on a collection. This can cause a billable read of every document in the collection.

To address the hint, use an index with a terms to look up matching documents instead.

non_covered_document_read

Returned for uncovered index queries. The query uses an index but returns entire documents or field values not covered by the index.

Consider adding the uncovered fields to the index definition’s values. Then use projection or mapping to return only the fields you need.

Fauna does not return the non_covered_document_read performance hint for uncovered index queries that pass an mva() term.

full_set_read

The query calls an eager-loading method on a document Set. To address the hint, do one of the following:

Use set.take() to explicitly limit the size of the calling Set to fewer than 100 documents. This applies even if the original, unbounded Set contains fewer than 100 documents.
Rewrite the query to avoid calling the method.

Alternatively, the query calls set.order() on a document Set, causing all documents in the Set to be read. If you frequently run such queries, consider adding the fields used for ordering to an index definition’s values.

`X-Performance-Hints` header

Internally, performance hints are enabled and disabled using the X-Performance-Hints request header for the Core HTTP API’s Query endpoint. Performance hints are returned in the response’s summary. For more information, see Query summary.