<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 is not 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

Define an index

  1. Define a bestFlavor index on the CoffeeBean collection:

    CoffeeBean.definition.update({
  indexes: {
    bestFlavor: {
      terms: [{ field: "Species" }],
      values: [{ field: "Quality_Parameters.Flavor" }]
    }
  }
})
    {
  name: "CoffeeBean",
  coll: Collection,
  ts: Time("2023-03-24T15:23:45.330Z"),
  indexes: {
    bestFlavor: {
      terms: [
        {
          field: "Species",
        },
      ],
      values: [
        {
          field: "Quality_Parameters.Flavor",
          order: "asc",
        },
      ],
      queryable: true,
      status: "complete",
    },
  },
}

    The index matches on documents with the terms value provided for Species that are also in the Quality_Parameters.Flavor values field range. Results are returned in ascending, asc, order.

  2. Call the bestFlavor index method with the species name and a single range value:

    CoffeeBean.bestFlavor("Robusta", { from: 7.5 })
    {
  data: [
    {
      id: "360008596716519457",
      coll: CoffeeBean,
      ts: Time("2023-03-23T16:43:22.400Z"),
      Species: "Robusta",
      Owner: "nishant gurjer",
      Country_of_Origin: "India",
      Harvest_Year: 2017,
      Grading_Date: "October 31st, 2017",
      Expiration: "October 31st, 2018",
      Quality_Parameters: {
        Aroma: 8,
        Flavor: 7.75,
        Balance: 7.92,
      },
      Altitude: {
        unit_of_measurement: "m",
        mean: 3170,
      },
    },
  ],
}

    It returns the only matching document in the range.

Use indexes with terms and values

  1. Change the bestFlavor index to match on two values, including document id. This allows you to index on multiple values.

    CoffeeBean.definition.update({
  indexes: {
    bestFlavor: {
      terms: [{ field: "Species" }],
      values: [
        { field: "Harvest_Year"},
        { field: "id"}
      ]
    }
  }
})
    {
  name: "CoffeeBean",
  coll: Collection,
  ts: Time("2023-09-10T17:45:08.400Z"),
  constraints: [],
  indexes: {
    bestFlavor: {
      terms: [
        {
          field: "Species"
        }
      ],
      values: [
        {
          field: "Harvest_Year",
          order: "asc"
        },
        {
          field: "id",
          order: "asc"
        }
      ],
      queryable: true,
      status: "complete"
    }
  }
}

  2. Get all documents that match the index terms:

    CoffeeBean.bestFlavor("Arabica")
    {
  data: [
    {
      id: "366190504817197124",
      coll: CoffeeBean,
      ts: Time("2023-09-05T15:20:49.180Z"),
      Owner: "metad plc",
      Country_of_Origin: "Ethiopia",
      Species: "Arabica",
      Harvest_Year: 2014,
        ... elided ...
    },
    {
      id: "374312704818544708",
      coll: CoffeeBean,
      ts: Time("2023-08-28T14:04:33.185Z"),
      Species: "Arabica",
      Owner: "Coffee Co., Inc.",
      Country_of_Origin: "USA",
      Harvest_Year: 2022,
        ... elided ...
    },
    {
      id: "366190711733747780",
      coll: CoffeeBean,
      ts: Time("2023-09-10T17:54:49.440Z"),
      Species: "Arabica",
      Owner: "Healthy Grounds",
      Country_of_Origin: "Guatemala",
      Harvest_Year: 2016,
        ... elided ...
    },
    {
      id: "375505851088109633",
      coll: CoffeeBean,
      ts: Time("2023-09-10T18:05:35.840Z"),
      Species: "Arabica",
      Owner: "Acme Coffee",
      Country_of_Origin: "Ethiopia",
      Harvest_Year: 2016
    }
  ]
}

  3. Filter the results further by the values fields:

    CoffeeBean.bestFlavor("Arabica", { from: [2016] })
    {
  data: [
    {
      id: "366190711733747780",
      coll: CoffeeBean,
      ts: Time("2023-09-10T18:21:37.180Z"),
      Species: "Arabica",
      Owner: "Healthy Grounds",
      Country_of_Origin: "Guatemala",
      Harvest_Year: 2016,
        ... elided ...
    },
    {
      id: "375505851088109633",
      coll: CoffeeBean,
      ts: Time("2023-09-10T18:21:54.980Z"),
      Species: "Arabica",
      Owner: "Acme Coffee",
      Country_of_Origin: "Ethiopia",
      Harvest_Year: 2016
    },
    {
      id: "374312704818544708",
      coll: CoffeeBean,
      ts: Time("2023-08-28T14:04:33.185Z"),
      Species: "Arabica",
      Owner: "Coffee Co., Inc.",
      Country_of_Origin: "USA",
      Harvest_Year: 2022,
        ... elided ...
    }
  ]
}

    All documents that match the index terms and the first element of the values from range are returned.

  4. Filter the results further by matching on the second values field, the id field, of the most recent documents.

    CoffeeBean.bestFlavor("Arabica", { from: [2016, 374312704818544708] })
    {
  data: [
    {
      id: "375505851088109633",
      coll: CoffeeBean,
      ts: Time("2023-09-10T18:21:54.980Z"),
      Species: "Arabica",
      Owner: "Acme Coffee",
      Country_of_Origin: "Ethiopia",
      Harvest_Year: 2016
    },
    {
      id: "374312704818544708",
      coll: CoffeeBean,
      ts: Time("2023-08-28T14:04:33.185Z"),
      Species: "Arabica",
      Owner: "Coffee Co., Inc.",
      Country_of_Origin: "USA",
      Harvest_Year: 2022,
      Quality_Parameters: {
        Aroma: 8.67,
        Flavor: 8.83,
        Balance: 8.42
      }
    }
  ]
}

    This removes one of the documents with the same Harvest_Year value from the results.

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!