Indexes
Reference: |
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!