Use indexes for more efficient queries
The previous Query on collections tutorial uses built-in Set methods that traverse the whole dataset to get the data you want. This tutorial shows you how to use indexes as a more cost-effective and performant alternative.
Indexes
scale with your workload and give you predictable performance and cost.
Effectively, an index is a lookup table. You define the fields you’re
interested in, and Fauna indexes the documents that match your selection
criteria. As an example of how this works, and the optimization you can
realize if you define a bestFlavor
index as follows,
CoffeeBean.definition.update({
indexes: {
bestFlavor: {
terms: [{ field: "Species" }],
values: [{ field: "Harvest_Year" }]
}
}
})
and then make the following query:
CoffeeBean.bestFlavor("Robusta").map(.Harvest_Year).toArray()
Fauna returns an array of harvest years for all Robusta species in the
collection but Fauna didn’t read any documents because the term
.Harvest_Year
is covered by the index, which makes the query significantly
less expensive compared to if the value .Harvest_Year
wasn’t covered.
You declare indexes by name, which then populate the
Collection indexes
field with the terms and values fields set
to what you want to index on. For defined values, all documents are indexed,
including those that have a null value for the field.
See Indexes definition.
Two indexes with the same shape, except for the |
The following shows how to define, query, and manage indexes. The examples use FQL directly to create an index. You can also use the Dashboard or CLI schema management in keeping with best practices for defining schema:
-
To define an index using the Dashboard, select the database, and with the Collections menu item selected in the lower panel for the database, click the collection you want to index to expand the panel and display the Documents and Indexes menu items. Choose Indexes and click the CREATE INDEX button. Enter the index Name, Terms, and Values.
-
To define an index using the CLI, define the index in a .fsl schema file and push the file to Fauna. See Get started with FSL for more information.
Create an index and submit an indexed query
Using the CoffeeBean
collection you created in the
Populate the cookbook database
tutorial, you should already have documents that you can index. Call
CoffeeBean.all()
to verify the documents and see the terms used as
selection criteria in this tutorial. You can experiment with indexing by
adding more documents with different data.
-
Use the document
update()
method to create an index in theCoffeeBean
collection. Give the index a name and define the terms and values fields you’re interested in. For this tutorial, declare an index that selects on theSpecies
andAltitude
fields, and name the indexbestFlavor
:{ name: "CoffeeBean", coll: Collection, ts: Time("2023-06-03T21:34:26.710Z"), indexes: { bestFlavor: { terms: [ { field: "Species" } ], values: [ { field: "Altitude.mean", order: "asc" } ], queryable: true, status: "complete" } }, constraints: [] }
Notice that the
bestFlavor
index is added to the collectionindexes
field. Also, documents are returned in the default, ascending (asc
) order of thevalues
field. -
View the indexes you declared by querying the collection definition:
Get the indexed documents that match your selection criteria
This tutorial selects all documents matching a given species terms value and introduces you to the values range parameter.
-
Query using the bestFlavor indexed, requesting all documents for the
Arabica
species grown at an altitude of 1500 meters and higher:{ data: [ { id: "366190711733747780", coll: CoffeeBean, ts: Time("2023-06-03T14:58:52.120Z"), Species: "Arabica", Owner: "Healthy Grounds", Country_of_Origin: "Guatemala", Harvest_Year: "", Quality_Parameters: { Aroma: 8.42, Flavor: 8.5, Balance: 8.42 }, Altitude: { unit_of_measurement: "m", mean: 1700 }, Best_of_Class: Date("2023-06-03") }, { id: "366190504817197124", coll: CoffeeBean, ts: Time("2023-06-03T14:58:37.770Z"), Owner: "metad plc", Country_of_Origin: "Ethiopia", Species: "Arabica", Harvest_Year: 2014, Quality_Parameters: { Aroma: 8.67, Flavor: 8.83, Balance: 8.42 }, Altitude: { unit_of_measurement: "m", mean: 2075 }, Best_of_Class: Date("2023-06-03") } ] }
At least two documents are returned that match the terms and values fields in order of ascending altitude.
-
Using the values field range parameter further restricted the selection:
{ data: [ { id: "366190711733747780", coll: CoffeeBean, ts: Time("2023-06-03T14:58:52.120Z"), Species: "Arabica", Owner: "Healthy Grounds", Country_of_Origin: "Guatemala", Harvest_Year: "", Quality_Parameters: { Aroma: 8.42, Flavor: 8.5, Balance: 8.42 }, Altitude: { unit_of_measurement: "m", mean: 1700 }, Best_of_Class: Date("2023-06-03") } ] }
The response should include only the document with a mean
Altitude
value between 1500 and 1800 meters, inclusive.
Delete an index
Delete your index by setting the index name to null
in the collection
definition:
{
name: "CoffeeBean",
coll: Collection,
ts: Time("2023-06-03T22:07:27.070Z"),
indexes: {},
constraints: []
}
The response shows that the bestFlavor
index is removed from the collection
indexes
.
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!