The Fauna service will be ending on May 30, 2025.

For more information on the service wind down, see our announcement and the Fauna Service End-of-Life FAQ.

Indexes

Reference: Index definitions

An index stores, or covers, specific document field values for quick retrieval. You can use indexes to filter and sort a collection’s documents in a performant way.

Using indexes can significantly improve query performance and reduce costs, especially for large datasets. Unindexed queries should be avoided.

Define an index

You create and manage indexes at the collection level as part of an FSL collection schema. An index definition can include:

  • Terms: Document fields for exact match searches

  • Values: Document fields for sorting and range searches

You can only index persistable field values.

An index definition must include at least one term or value. A collection can include multiple index definitions:

collection Product {
  ...

  // Defines the `byName()` index.
  index byName {
    // `terms` are document fields for exact match searches.
    // In this example, you get `Product` collection documents
    // by their `name` field value.
    terms [.name]
    // `values` are document fields for sorting and range searches.
    // In this example, you sort or filter index results by their
    // descending `stock` field value.
    values [desc(.stock)]
  }

  ...
}

You can create and manage schema using any of the following:

FQL index definitions

Fauna stores schema for user-defined collections as documents in the Collection system collection.

Collection documents include an FQL version of the collection’s index definitions:

{
  name: "Customer",
  coll: Collection,
  ts: Time("2099-10-03T20:45:53.780Z"),
  ...
  indexes: {
    byEmail: {
      terms: [
        {
          field: ".email",
          mva: false
        }
      ],
      values: [
        {
          field: ".email",
          order: "desc",
          mva: false
        },
        {
          field: ".name",
          order: "asc",
          mva: false
        }
      ],
      queryable: true,
      status: "complete"
    },
  },
  ...
}

You can use Collection methods to access and manage index definitions in FQL.

Index builds

When you submit a new or updated collection schema, Fauna may need to build (or rebuild) the collection’s indexes. Fauna builds an index if:

  • The index definition is new.

  • The index definition is updated, including:

    • Adding a new index term or index value

    • Changing the order of existing index terms or index values

  • The definition, or function body, of a computed field covered by the index changes. Changing the name of a computed field does not trigger a rebuild.

  • A field that has a field definition and is covered by the index is migrated in a way that affects the field’s values. Other migrations, such as renaming a field, don’t require a rebuild.

If the collection contains more than 128 documents, Fauna uses a background task to build the index. During a build, the index may not be queryable.

If the collection contains 128 or fewer documents, Fauna builds the index in the same transaction as the collection update. The index is immediately queryable.

Monitor index builds

The FQL version of the collection schema, stored as a Collection document, includes status and queryable properties for indexes objects. You can use these properties to monitor the availability of an index during a build:

// Gets the FQL definition of the `Product` collection schema.
// Projects the `indexes` object from the schema.
Collection.byName("Product") { indexes }
{
  indexes: {
    // FQL version of the `byCategory` index definition.
    byEmail: {
      terms: [
        {
          field: ".email",
          mva: false
        }
      ],
      values: [
        {
          field: ".email",
          order: "desc",
          mva: false
        },
        {
          field: ".name",
          order: "asc",
          mva: false
        }
      ],
      queryable: true,    // Indicates the index is queryable.
      status: "complete"  // Indicates the index build is complete.
    },
    ...
  }
}

Call an index

In an FQL query, you call an index as a method on its collection:

// Call the `byName()` index to fet `Product` collection
// documents with a `name` value of `limes`. Values must
// match exactly.
Product.byName("limes")

The call returns a Set of matching collection documents.

Reference: FQL index method docs

Terms

You can use index terms to run exact match searches on document field values.

Use index terms for exact match search

The following index definition includes name as an index term:

collection Product {
  ...

  index byName {
    terms [.name]
  }

  ...
}

When you call the index, you must pass an argument for each term in the index definition.

// Get products named "limes"
Product.byName("limes")

The call returns a Set of Product collection documents with a name of limes.

Pass multiple index terms

The following index definition includes two index terms:

collection Customer {
  ...

  index byName {
    terms [.firstName, .lastName]
  }
}

In an index call, use a comma to separate term arguments. Provide arguments in the same field order used in the index definition.

// Get customers named "Alice Appleseed"
Customer.byName("Alice", "Appleseed")

The call returns a Set of matching collection documents.

Best practices for 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
}

Values

You can use index values to sort a collection’s documents. You can also use index values for range searches.

Sort collection documents

The following index definition includes several index values:

collection Product {
  ...

  index sortedByPriceLowToHigh {
    values [.price, .name, .description]
  }
}

Call the sortedByPriceLowToHigh() index with no arguments to return Product documents sorted by:

  • Ascending price, then …​

  • Ascending name, then …​

  • Ascending description, then …​

  • Ascending id (default)

// Get products by ascending price, name, and description
Product.sortedByPriceLowToHigh()

Descending order

By default, index values sort results in ascending order. To use descending order, use desc() in the index definition:

collection Product {
  ...

  index sortedByPriceHighToLow {
    values [desc(.price), .name, .description]
  }

  ...
}

Call the index with no arguments to return Product documents sorted by:

  • Descending price, then …​

  • Ascending name, then …​

  • Ascending description, then …​

  • Ascending id (default)

// Get products by descending price,
// ascending name, and ascending description
Product.sortedByPriceHighToLow()

You can also use index values for range searches.

The following index definition includes several index values:

collection Product {
  ...

  index sortedByPriceLowToHigh {
    values [.price, .name, .description]
  }
}

The index specifies price as its first value. The following query passes an argument to run a range search on price:

// Get products with a price between
// 20_00 (inclusive) and 30_00 (inclusive)
Product.sortedByPriceLowToHigh({ from: 20_00, to: 30_00 })

If an index value uses descending order, pass the higher value in from:

// Get products with a price between
// 20_00 (inclusive) and 30_00 (inclusive) in desc order
Product.sortedByPriceHighToLow({ from: 30_00, to: 20_00 })

Omit from or to to run unbounded range searches:

// Get products with a price greater than or equal to 20_00
Product.sortedByPriceLowToHigh({ from: 20_00 })

// Get products with a price less than or equal to 30_00
Product.sortedByPriceLowToHigh({ to: 30_00 })

Pass multiple index values

Use an Array to pass multiple value arguments. Pass the arguments in the same field order used in the index definition.

Product.sortedByPriceLowToHigh({ from: [ 20_00, "l" ], to: [ 30_00, "z" ] })

The index returns any document that matches the first value in the from and to Arrays. If matching documents have the same values, they are compared against the next Array element value, and so on.

For example, the Product collection’s sortedByPriceLowToHigh() index covers the price and name fields as index values. The Product collection contains two documents:

Document

price

name

Doc1

4_99

pizza

Doc2

6_98

cups

The following query returns both Doc1 and Doc2, in addition to other matching documents:

Product.sortedByPriceLowToHigh({ from: [4_99, "p"] })

The first value (4_99 and 6_98) of each document matches the first value (4_99) of the from Array.

Later, you update the document values to:

Document price name

Doc1

4_99

pizza

Doc2

4_99

cups

The following query no longer returns Doc2:

Product.sortedByPriceLowToHigh({ from: [4_99, "p"] })

Although the first value (4_99) in both documents matches the first value in the from Array, the second value (cups) in Doc2 doesn’t match the second value (p) of the from Array.

Run a range search on id

All indexes implicitly include an ascending document id as the index’s last value.

If you intend to run range searches on id, we recommend you explicitly include an ascending id as the last index value in the index definition, even if you have an otherwise identical index.

For example, the following sortByStock() and sortByStockandId() indexes have the same values:

collection Product {
  ...

  index sortByStock {
    values [.stock]
  }

  index sortByStockandId {
    values [.stock, .id]
  }

  ...
}

Although it’s not explicitly listed, sortByStock() implicitly includes an ascending id as its last value.

To reduce your costs, Fauna only builds the sortByStock() index. When a query calls the sortByStockandId() index, Fauna uses the sortByStock() index behind the scenes. sortByStockandId() only acts as a virtual index and isn’t materialized.

Pass terms and values

If an index has both terms and values, you can run an exact match search on documents in a provided range.

The following index definition includes name as an index term and stock as an index value:

collection Product {
  ...

  index byName {
    terms [.name]
    values [.stock]
  }

  ...
}

When you call the index, you must provide a term and can specify an optional range:

// Get products named "donkeypinata"
// with a stock between 10 (inclusive) and 50 (inclusive)
Product.byName("donkey pinata", { from: 10, to: 50 })

Index an Array field

By default, Fauna assumes index term and value field contain scalar values. Use mva() to index an Array field’s values:

collection Product {
  ...
  index byCategory {
    // `categories` is an Array field.
    terms [mva(.categories)]
  }

  index sortedByCategory {
    // `categories` is an Array field.
    values [mva(.categories)]
    // You can combine `mva()` with
    // `desc()` and `asc()`. Ex:
    // values [desc(mva(.categories))]
  }
  ...
}

mva() only works on the last item in the provided field accessor. For more complex nested Arrays, such as an object Array, use a computed field:

collection Order {
  ...
  // `Order` collection documents
  // have the following structure:
  // {
  //   customer: Customer("<CUSTOMER_DOC_ID>"),
  //   items: [
  //     {
  //       product: Product("PRODUCT_DOC_ID"),
  //       quantity: 10
  //     },
  //     ...
  //   ],
  //   ...
  // }

  // Defines the `quantities` computed field.
  // The field uses `map()` to extract `price` values
  // from the `cart` Array's object to a flat Array.
  compute quantities = (.items.map(item => item.quantity))

    // Uses `mva()` to index the computed `quantities` field.
  index byQuantities {
    terms [mva(.quantities)]
  }
  ...
}

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

Covered queries

If you project or map an index’s covered term or value fields, Fauna gets the field values from the index.

The following index definition includes several index values:

collection Product {
  ...

  index sortedByPriceLowToHigh {
    values [.price, .name, .description]
  }
}

The following is a covered query:

// This is a covered query.
// `name`, `description`, and `price` are values
// in the `sortedByPriceLowToHigh()` index definition.
Product.sortedByPriceLowToHigh() {
  name,
  description,
  price
}

If the projection contains an uncovered field, Fauna must retrieve the field values from the documents. This is an uncovered query:

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

Uncovered queries emit a performance hint, if enabled. For example:

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*:1:42
  |
1 | Product.sortedByPriceLowToHigh() { name, stock }
  |                                          ^^^^^
  |

Covered queries are typically faster and less expensive than uncovered queries, which require document reads. If you frequently run uncovered queries, consider adding the uncovered fields to the index definition’s values. For example:

collection Product {
  ...
  // Adds the `stock` field as an index value.
  index sortedByPriceLowToHigh {
    values [.price, .name, .description, .stock]
  }
}

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

No projection or mapping

Index queries without a projection or mapping are uncovered. Fauna must read each document returned in the Set. For example:

// This is an uncovered query.
// Queries without a projection or mapping
// require a document read.
Product.byName("limes")
Performance hint : non_covered_document_read

If performance hints are enabled, index queries without a projection or mapping emit a performance hint. For example:

performance_hint: non_covered_document_read - Full documents returned from Product.byName. See https://docs.fauna.com/performance_hint/non_covered_document_read.
at *query*:1:15
  |
1 | Product.byName("limes")
  |               ^^^^^^^^^
  |

If you frequently run such queries, consider adding the uncovered fields to the index definition’s values. For example:

collection Product {
  ...

  index byName {
    terms [.name]
    values [.price, .stock, .description]
  }

  ...
}

Then use projection or mapping to only return the fields you need. Given the previous index definition, the following query is covered:

// This is a covered query.
// `price`, `stock`, and `description` are values
// in the `byName()` index definition.
Product.byName("limes") {
  price,
  stock,
  description
}

Filter covered values

You can use set.where() to filter the results of an index call. If the set.where() predicate only accesses fields defined in the index definition’s terms and values, the query is covered.

For example, given the following index definition:

collection Product {
  ...

  index byName {
    terms [.name]
    values [.price, .description]
  }

  ...
}

The following query is covered:

// Covered query.
// Calls the `byName()` index.
// Uses `where()` to filter the results of
// the index call. The predicates only
// access covered terms and values.
Product.byName("limes")
  .where(.description.includes("Conventional"))
  .where(.price < 500) {
    name,
    description,
    price
  }

The following query is uncovered:

Product.byName("limes")
  .where(.description.includes("Conventional"))
  // The `where()` predicate accesses the uncovered
  // `stock` field.
  .where(.stock < 100)
  .where(.price < 500) {
    name,
    description,
    price
  }

To cover the query, add the uncovered field to the index definition’s values:

collection Product {
  ...

  index byName {
    terms [.name]
    // Adds `stock` to the index's values
    values [.price, .description, .stock]
  }

  ...
}

Dynamic filtering using advanced query composition

Complex applications may need to handle arbitrary combinations of search criteria. In these cases, you can use query composition to dynamically apply indexes and filters to queries.

The following template uses query composition to:

  • Automatically select the most selective index

  • Apply remaining criteria as filters in priority order

  • Support both index-based and filter-based search patterns

The template uses TypeScript and the JavaScript driver. A similar approach can be used with any Fauna client driver.

/**
 * A Javascript object with a sorted list of indexes or filters.
 *
 * Javascript maintains key order for objects.
 * Sort items in the map from most to least selective.
 */
type QueryMap = Record<string, (...args: any[]) => Query>

/** Object to represent a search argument.
 *
 * Contains the name of the index to use and the arguments
 * to pass to it.
 *
 * Example:
 * { name: "by_name", args: ["limes"] }
 * { name: "range_price", args: [{ from: 100, to: 500 }] }
 */
type SearchTerm = {
  name: string
  args: any[]
}

/**
 * Composes a query by prioritizing the most selective index and then
 * applying filters.
 *
 * @param default_query - The initial query to which indexes and filters are applied.
 * @param index_map - A map of index names to functions that generate query components.
 * @param filter_map - A map of filter names to functions that generate query components.
 * @param search_terms - An array of search terms that specify the type and arguments
 *                       for composing the query.
 * @returns The composed query after applying all relevant indices and filters.
 */
const build_search = (
  default_query: Query,
  index_map: QueryMap,
  filter_map: QueryMap,
  search_terms: SearchTerm[]
): Query => {
  const _search_terms = [...search_terms]

  // Initialize a default query. Used if no other indexes are applicable.
  let query: Query = default_query

  // Iterate through the index map, from most to least selective.
  build_index_query: for (const index_name of Object.keys(
    index_map
  )) {
    // Iterate through each search term to check if it matches the highest priority index.
    for (const search_term of _search_terms) {
      // If a match is found, update the query. Then remove the search term from the
      // list and break out of the loop.
      if (index_name === search_term.name) {
        query = index_map[search_term.name](...search_term.args)
        _search_terms.splice(_search_terms.indexOf(search_term), 1)
        break build_index_query
      }
    }
  }

  // Iterate through the filter map, from most to least selective.
  for (const filter_name of Object.keys(filter_map)) {
    // Iterate through each search term to check if it matches the highest priority filter.
    for (const search_term of _search_terms) {
      // If a match is found, update the query. Then remove the search term from the list.
      if (filter_name === search_term.name) {
        const filter = filter_map[search_term.name](...search_term.args)
        query = fql`${query}${filter}`
        _search_terms.splice(_search_terms.indexOf(search_term), 1)
      }
    }
  }

  // If there are remaining search terms, you can't build the full query.
  if (_search_terms.length > 0) {
    throw new Error("Unable to build query")
  }

  return query
}

The following example implements the template using the Fauna Dashboard's demo data:

// Implementation of `index_map` from the template.
// Sort items in the map from most to least selective.
const product_index_priority_map: QueryMap = {
  by_order: (id: string) =>
    fql`Order.byId(${id})!.items.map(.product!)`,
  by_name: (name: string) => fql`Product.byName(${name})`,
  by_category: (category: string) =>
    fql`Product.byCategory(Category.byName(${category}).first()!)`,
  range_price: (range: { from?: number; to?: number }) =>
    fql`Product.sortedByPriceLowToHigh(${range})`,
}

// Implementation of `filter_map` from the template.
// Sort items in the map from most to least selective.
const product_filter_map: QueryMap = {
  by_name: (name: string) => fql`.where(.name == ${name})`,
  by_category: (category: string) =>
    fql`.where(.category == Category.byName(${category}).first()!)`,
  range_price: ({ from, to }: { from?: number; to?: number }) => {
    // Dynamically filter products by price range.
    if (from && to) {
      return fql`.where(.price >= ${from} && .price <= ${to})`
    } else if (from) {
      return fql`.where(.price >= ${from})`
    } else if (to) {
      return fql`.where(.price <= ${to})`
    }
    return fql``
  },
}

// Hybrid implementation of `index_map` and `filter_map` from the template.
// Combines filters and indexes to compose FQL query fragments.
// Sort items in the map from most to least selective.
const product_filter_with_indexes_map: QueryMap = {
  by_name: (name: string) =>
    fql`.where(doc => Product.byName(${name}).includes(doc))`,
  by_category: (category: string) =>
    fql`.where(doc => Product.byCategory(Category.byName(${category}).first()!).includes(doc))`,
  range_price: (range: { from?: number; to?: number }) =>
    fql`.where(doc => Product.sortedByPriceLowToHigh(${range}).includes(doc))`,
}

const order_id = (await client.query(fql`Order.all().first()!`))
  .data.id

const query = build_search(
  fql`Product.all()`,
  product_index_priority_map,
  product_filter_with_indexes_map,
  [
    // { type: "by", name: "name", args: ["limes"] },
    // { type: "by", name: "category", args: ["produce"] },
    { type: "range", name: "price", args: [{ to: 1000 }] },
    { type: "by", name: "order", args: [order_id] },
  ]
)

const res = await client.query(query)

Null values are uncovered

Missing or null field values are not stored or covered by an index, even if the field is listed as one of the values in the index’s definition. Projecting or mapping a field with a null value requires a document read.

For example, the following byName() index definition includes the description field as an index value:

collection Product {
  ...

  index byName {
    terms [.name]
    values [.price, .description]
  }
}

The following query creates a document that omits the description field, which is equivalent to a null value for the field:

Product.create({
  name: "limes",
  price: 2_99
  // The `description` field is omitted (effectively `null`).
})

If you use byName() to retrieve the indexed name, price, and description field values, the query is uncovered. A document read is required to retrieve the null value of the description field.

Product.byName("limes") {
  name,
  price,
  // Projects the `description` field.
  description
}
{
  data: [
    {
      name: "limes",
      price: 299,
      // Retrieving the `description` field's `null` value
      // requires a document read.
      description: null
    }
  ]
}

Index document relationships

When you index a field that contains a document, you index a document reference. The reference consists of the document’s collection and document ID:

collection Product {
  ...
  // The `category` field contains a reference to
  // a `Category` collection document.
  category: Ref<Category>
  ...
  // Indexes the `category` field as an index term.
  // The index stores `Category` document references.
  // Example reference: Category("123")
  index byCategory {
    terms [.category]
  }
}

An index can’t store a referenced document’s fields. An index also can’t store a computed field that references another document. See Patterns to avoid.

Missing or null values

  • Terms: If an index definition contains terms, Fauna doesn’t index a document if all its index terms are missing or otherwise evaluate to null. This applies even if the document contains index values.

  • Values: If an index definition contains only values, Fauna indexes all documents in the collection, regardless of whether the document’s index values are missing or otherwise null.

Missing or null field values are not stored or covered by an index, even if the field is listed as one of the values in the index’s definition. Projecting or mapping a field with a null value requires a document read.

Partitions

When an index has one or more terms, the index is internally partitioned by its terms. Partitioning lets Fauna scale indexes efficiently.

Virtual indexes

To reduce your costs, Fauna doesn’t build duplicate indexes that have the same terms and values. Instead, Fauna only builds a single index and internally points any duplicates to the single index.

For example, in the following collection, the byDescription() and byDesc() indexes are duplicates:

collection Product {
  ...

  index byDescription {
    terms [.description]
  }

  index byDesc {
    terms [.description]
  }
}

When a query calls the byDesc() index, Fauna uses the existing byDescription() index internally. byDesc() is considered a virtual index and is never materialized.

Document history

To support temporal queries, indexes cover field values from both current documents and their historical document snapshots.

To enable quicker sorting and range searches, current and historical index entries are stored together, sorted by index values. All indexes implicitly include an ascending document id as the index’s last value.

When you read data from an index, including the collection.all() index, Fauna must read from both current and historical index entries to determine if they apply to the query. Fauna then filters out any data not returned by the query.

You are charged for any Transactional Read Operations (TROs) used to read current or historical index data, including data not returned by the query.

You are not charged for any historical data older than the retention period set by the history_days setting.

\