Indexes

reference:

Indexes definition

Indexes are the preferred way to query your data. They’re effectively a lookup table for organizing and retrieving documents by attributes instead of by reference. When you use an index, Fauna uses index terms and values to search instead of scanning every document to find a match for your query. When you cover a value, Fauna doesn’t have to look up the source document.

An index exists as a method of the collection for which it is defined. Defining an index defines a method on the collection. Querying an index returns a set of documents that match your index definition. For example, if you create an index named priceRange in the Product collection, an indexed query on priceRange() has the following form:

Product.priceRange()

Only documents that match the priceRange index definition are returned.

Two fields are used to define an index:

  • terms

  • values

Terms

Including the terms field in an index allows you to select one or more document fields to be searchable in the index. For example, consider a collection called People in which documents have fields called first_name and last_name. If you include those fields in the terms of an index on the People collection, you can run queries that search for matches in those fields.

When an index has one or more terms, the index is partitioned by the terms, which allows Fauna to scale indexes efficiently.

The resulting index method on the collection takes as many arguments as terms the index is defined with. Calling an index method with arguments returns the set of documents contained in the index whose corresponding field values match the arguments.

See terms for more detailed information.

Values

Index values define which document values should be used to select matching documents to return in the result set. It defines values you want to cover. For example, if you want to sort query results from a Customer collection by last_name, define last_name in the values field:

collection Customer {
  index sortedOnLastname {
      values [.lastname]
  }
}

The example also defines an ascending, asc, sort order.

When you query a field covered by an index, Fauna doesn’t have to fetch the source document to get the covered value. When an index has all the values a query requires, that query is considered fully covered. A fully covered query is the most efficient query.

The default document order in a set returned by an index is the ascending order of the values for the field. You can use the order field to define ascending, asc, or descending, desc, order.

The values field also allows you to query on range to get only those documents in the requested range. Range notation has the following format:

{ from: <startValue>, to: <endValue> }

<startValue> and <endValue> are optional.

For example, if you create a priceRange index with a price field for the Product collection,

collection Product {
  index priceRange {
   values [.price]
  }
}

For example, to get all Product collection documents with a price value between 100 and 150, inclusive, submit the following query against the priceRange index:

Product.priceRange({ from: 100, to: 150 })

See values for more detailed information.

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 behind the scenes. byDesc is considered a virtual index and is never materialized.

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!