<indexName>()
Signature
<indexName>(term: any): set<document>
<indexName>(term: any, range: object): set<document>
Description
An index is a fast lookup mechanism that returns only those documents with fields that match the index parameters defined for a collection.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
term |
Yes |
Exact index |
|
range |
Range of returned documents The start definition is a single value or an array of values. Arrays are ordered by tuple where entries that match on the first element are then ordered on succeeding elements so anything greater than the first from value and less than the first to value is returned. If matching documents have the same from value, they are compared against the next array element value and returned, accordingly. For example: Given database documents with values of interest as, But if the documents have the following values, where the first values of
interest are equal, The range from and to array element ordering must match the order of the values defined for the index. Array results are sorted in from array element order. If range is omitted, the call returns all documents that match terms. |
Examples
Sort documents
You define indexes in Fauna Schema Language (FSL) as part of a
collection schema. You manage
schemas using the Fauna Dashboard or the
Fauna CLI with .fsl
files.
For example, Fauna’s demo data includes the
sortedByPriceLowToHigh
index in the Product
collection’s schema:
collection Product {
...
index sortedByPriceLowToHigh {
values [.price, .name, .description]
}
}
The index’s values
are used for sorting and range searches. All indexes
implicitly include an ascending document id
as the index’s last value.
Call the index with no arguments to return Product
documents sorted by:
-
Ascending
price
, then … -
Ascending
name
, then … -
Ascending
description
, then … -
Ascending
id
// Get products by ascending price, name, and description
Product.sortedByPriceLowToHigh()
Calling an index returns a Set of matching documents:
{
data: [
{
id: "394086673314480192",
coll: Product,
...
name: "limes",
description: "Conventional, 1 ct",
price: 0.35,
quantity: 995,
...
},
...
{
id: "394086673309237312",
coll: Product,
...
name: "pinata",
description: "Original Classic Donkey Pinata",
price: 24.99,
quantity: 40,
...
}
]
}
Descending order
By default, values sort in ascending order. To use descending order, use `desc(<field>) `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
// Get products by desending price,
// ascending name, and ascending description
Product.sortedByPriceHighToLow()
Run a range search
In addition to sorting, you can use an index’s values to run a range search.
The sortedByPriceLowToHigh
index specifies price
as its first values
field. The following query passes an argument to run a range search on price
.
// Get products with a price between
// 20 (inclusive) and 30 (inclusive)
Product.sortedByPriceLowToHigh({ from: 20, to: 30 })
If a values
uses descending order, pass the higher value in from
.
// Get products with a price between
// 20 (inclusive)and 30 (inclusive) in desc order
Product.sortedByPriceHighToLow({ from: 30, to: 20 })
Omit from
or to
to run unbounded range searches.
// Get products with a price greater than or equal to 20
Product.sortedByPriceLowToHigh({ from: 20 })
// Get products with a price less than or equal to 30
// Product.sortedByPriceLowToHigh({ to: 30 })
Run an exact match search
Fauna’s demo data includes the
byName
index in the Product
collection’s schema:
collection Product {
...
index byName {
terms [.name]
values [desc(.quantity)]
}
...
}
The index’s terms
are used for exact match searches.
When you call byName
, you must pass an argument for any terms
fields:
// Get products named "limes"
Product.byName("limes")
Use a comma to separate multiple terms arguments. Provide arguments in the same field order used in the index definition. For example:
// Get customers named "Alice Appleseed"
Customer.byName("Alice", "Appleseed")
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!