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 on instead of scanning every document to find a match for your query. When you cover a value, Fauna doesn’t look up the source document.

When you define an index, you’re defining a method on a Collection. For example, if you create an index named priceRange, you make an indexed query by calling priceRange() on the Collection:

collectionName.priceRange()

In this example only the documents matching the priceRange index definition are returned.

Calling an index returns a set of documents that match your Index definition criteria.

See the Indexes definition reference documentation.

See Limits for the concurrent build and transaction limits.

Index queries

Indexes exist as methods on the Collection object they belong to. For example, if you have an Authors collection with a byLastName index defined, you call the index with the following method, using dot notation as needed:

Author.byLastName("Rothfuss")
Author.byLastName("Rothfuss").first()

The first query returns a Set of documents from the Authors collection with the last name of Rothfuss. The second query gets the first document that matches the index query.

Index properties

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.

The following document field types can be indexed as terms:

Values

Index values define which document values should be used to sort matching documents in the result set. It defines values you want to cover. The query engine uses values to select only the part of the index needed to satisfy the query.

When you query a field covered by an index, Fauna doesn’t have to fetch every source document. For example, if you want to sort query results from a People collection by last_name, you can define the last name value in the index values.

The document order in a set returned by an index is the ascending order of the defined values in the index. If you want different ordering, use the order field to define ascending (asc) or descending (desc) order.

When you use values, you can use range notation to indicate that you want to get those documents with an indexed value in the requested range. The range notation used in the index call is:

{ 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,

Product.definition.update({
    indexes: {
        "priceRange": {
            "values": [{ "field": "price" }]
    }
})

You can get all documents with a price value between 100 and 150, inclusive, with the following query:

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

Covered queries

When an index has all the values a query requires, that query is considered a fully covered query. A fully covered query is the most efficient query because the source document doesn’t have to be read.

Latency and operational costs are significantly less than when using unindexed or partially covered queries.

Constraints

You can define unique constraints are defined on a document using the constraints field, which takes an array of unique constraints.

When one or more fields are part of a unique constraint, multiple documents cannot have the same values for the constrained fields. Constraints aren’t applied retroactively to existing documents but are applied only when a new document is created or an existing document is updated.

You can declare any number of constraints that define which Document field values must be unique in a Collection. A unique constraint can define one or more fields that must be unique in combination. For example, if firstName and lastName fields are included in a unique definition, the first and last name combination must be unique in the collection.

If you create a unique constraint over more than one field, the absence of one or more fields with the presence of other fields in the unique constraint is a combination that the constraint is enforced over. In the firstName / lastName example, if you create a user with only a lastName, you can’t create another user with only that lastName, but you could if you add a firstName.

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!