Improve performance with indexes

The previous Iterate on sets example uses built-in Set methods that scan the full 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.

You declare indexes by name and they subsequently reside in 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.

Create an index and submit an indexed query

Using the CoffeeBean collection you created in the Fauna at-a-glance 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.

  1. Use the document update() method to create an index in the CoffeeBean 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 the Species and Altitude fields, and name the index bestFlavor:

    CoffeeBean.definition.update({
  indexes: {
    bestFlavor: {
      terms: [{ field: "Species" }],
      values: [{ field: "Altitude.mean" }]
    }
  }
})
    {
  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 collection indexes field. Also, documents are returned in the default, ascending (asc) order of the values field.

  2. View the indexes you declared by querying the collection definition:

    CoffeeBean.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.

  1. Query using the bestFlavor indexed, requesting all documents for the Arabica species grown at an altitude of 1500 meters and higher:

    CoffeeBean.bestFlavor("Arabica", { from: 1500 })
    {
  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.

  2. Using the values field range parameter further restricted the selection:

    CoffeeBean.bestFlavor("Arabica", { from: 1500, to: 1800 })
    {
  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:

CoffeeBean.definition.update(
  {
    indexes: {
      bestFlavor: null
    }
  }
)
{
  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!