collection.indexName()
Signature
<indexName>(term: any): set<document>
<indexName>(term: any, range: object): set<document>
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.
For example:
collection Product {
...
index sortedByPriceLowToHigh {
values [.price, .name, .description, .stock]
}
}
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
stock
, then … -
Ascending
id
// Get products by ascending price, name, and description
Product.sortedByPriceLowToHigh()
Calling an index returns a Set of matching documents:
{
data: [
{
id: "<DOCUMENT_ID>",
coll: Product,
...
name: "limes",
description: "Conventional, 1 ct",
price: 35,
stock: 995,
...
},
...
{
id: "<DOCUMENT_ID>",
coll: Product,
...
name: "pinata",
description: "Original Classic Donkey Pinata",
price: 2499,
stock: 40,
...
}
]
}
Descending order
By default, values sort in ascending order. To use descending order, use `desc() `in the index definition:
collection Product {
...
index sortedByPriceHighToLow {
values [desc(.price), .name, .description, .stock]
}
...
}
Call the index with no arguments to return Product
documents sorted by:
-
Descending
price
, then … -
Ascending
name
, then … -
Ascending
description
, then … -
Ascending
stock
, 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_00 (inclusive) and 30_00 (inclusive)
Product.sortedByPriceLowToHigh({ from: 20_00, to: 30_00 })
If a values
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 })
Run an exact match search
The following collection schema defines the byName()
index with an index term:
collection Product {
...
index byName {
terms [.name]
}
...
}
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")
The following collection schema defines the byName()
index with two terms:
collection Customer {
...
index byName {
terms [.firstName, .lastName]
}
...
}
Use a comma to separate multiple terms arguments. Provide arguments in the same field order used in the index definition.
// Get customers named "Alice Appleseed"
Customer.byName("Alice", "Appleseed")
Combine 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 })
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!