<indexName>()

Get the Set of matching documents for the user-named index defined in the indexes field of the collection.

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.

Calling <indexName>() indexes a database according to the user-defined <indexName> terms and values fields defined in the collection indexes field. The call returns documents with terms that exactly match term and, if provided, in the defined range of values.

Parameters

Parameter Type Required Description

term

Any

Yes

Exact index terms field value to match on.

range

Object

Range of returned documents values fields to match on in the form: { from: start, to: end } where start is the start of the range, inclusive, and end is the end of the range, inclusive.

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,
8.0, 2022 and 8.6, 2014,
a range parameter of,
{from: [8.0, 2022]}
returns two documents because the first value of the documents satisfies the range request so the second range parameter element isn’t applied.

But if the documents have the following values, where the first values of interest are equal,
8.0, 2022 and 8.0, 2014,
the same range specification returns the document with 8.0, 2022, only, because the second document with a value of 2014 fails the range test.

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.

Return value

Type Description

set<document>

Set of matching documents.

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.

Call the index with no arguments to return Product documents sorted by:

  • Ascending price, then …​

  • Ascending name, then …​

  • Ascending description

// 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

// Get products by desending price,
// ascending name, and ascending description
Product.sortedByPriceHighToLow()

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 })

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")

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.

// Get products named "limes"
// with a quantity between 10 (inclusive) and 50 (inclusive)
Product.byName("limes", { from: 50, to: 10 })

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!