Indexes

A Set is a sorted group of immutable data from a collection. An Index is a group of sets within a collection. An index is also a database entity that facilitates data lookup.

Indexes allow for the organization and retrieval of documents by attributes other than their refs. They are defined as documents within the indexes collection.

An index cannot be created and read in the same transaction.

When an index is added, it is immediately available for reads, but returns incomplete results until it is built. FaunaDB builds the index asynchronously by scanning over relevant documents. Upon completion, the index’s active field is set to true.

When an index is created, documents are immediately indexed if the associated collection contains up to 128 documents. When an index contains all of a collection’s documents, it is an "active" index.

For collections with more than 128 documents, indexing is handled by a background task, and you may have to wait a short period before the index returns values. Until the indexing task is complete, the index is an "inactive" index.

To check whether an index is "active", run the following query:

Select("active", Get(Index("index_name")))

If you see true in the output, the index is "active" and is ready for your queries. Otherwise, you should wait and check again later, until true appears in the output.

It is possible to rename an index by updating its name field. Renaming an index changes its ref, but preserves inbound references to the index. Index data is not rebuilt.

An index’s terms and values fields may not be changed. If you update the unique field, existing duplicate items are not removed from the index.

When an index is deleted, it becomes inaccessible, and its data is deleted asynchronously.

Field Name Field Type Definition and Requirements

Field Name	Field Type	Definition and Requirements
`name`	String	The logical name of the index. Cannot be `events`, `sets`, `self`, `documents`, or `_`.
`source`	Array	One or more source objects describing source collections and (optional) fields.
`terms`	Array	Optional - An array of term objects describing the fields to be indexed. The default is an empty array.
`values`	Array	Optional - An array of value objects describing the fields to be covered. The default is an empty array.
`unique`	Boolean	Optional - If `true`, maintains a unique constraint on combined `terms` and `values`. The default is `false`.
`serialized`	Boolean	Optional - If `true`, writes to this index are serialized with concurrent reads and writes. The default is `false`.
`permissions`	Object	Optional - Indicates who is allowed to read the index. The default is everyone can read the index.
`data`	Object	Optional - This is user-defined metadata for the index. It is provided for the developer to store information at the index level. The default is an empty object; no data.

name

String

The logical name of the index. Cannot be events, sets, self, documents, or _.

source

Array

One or more source objects describing source collections and (optional) fields.

terms

Array

Optional - An array of term objects describing the fields to be indexed. The default is an empty array.

values

Array

Optional - An array of value objects describing the fields to be covered. The default is an empty array.

unique

Boolean

Optional - If true, maintains a unique constraint on combined terms and values. The default is false.

serialized

Boolean

Optional - If true, writes to this index are serialized with concurrent reads and writes. The default is false.

permissions

Object

Optional - Indicates who is allowed to read the index. The default is everyone can read the index.

data

Object

Optional - This is user-defined metadata for the index. It is provided for the developer to store information at the index level. The default is an empty object; no data.

The length of the field values specified for the terms or values fields must not exceed 32k bytes. The maximum size of an index entry, which is comprised of the terms and values content (and some overhead to distinguish multiple fields), must not exceed 64k bytes. If an index entry is too large, the query that created/updated the index entry fails.

Reading indexes

Entries in an index have zero or more terms, and zero or more covered values.

Entries are partitioned into sets by their terms, which is a strategy to improve index performance. Within each set, entries are sorted by their covered values.

The match function is used to refer to a set of entries within an index:

curl https://db.fauna.com/ \
    -u fnACrVIrDDACAFiX3FN4PhwADpl7dtPRhWObP08j: \
    -d '{ "match": { "index": "spells_by_element" }, "terms": "fire" }'

client.Query(Match(Index("spells_by_element"), "fire"));

System.out.println(
        client.query(
           Match(
              Index(Value("spells_by_element")),
              Value("fire"))
        ).get());

result, _ := client.Query(f.MatchTerm(f.Index("spells_by_element"), "fire"))

fmt.Println(result)

client.query(Match(Index("spells_by_element"), "fire"))

client.query(q.match(q.index("spells_by_element"), "fire"))

$client.query do
  match index('spells_by_element'), 'fire'
end

client.query(
    Match(index: Index("spells_by_element"), terms: "fire")
)

client.query(
  q.Match(q.Index('spells_by_element'), 'fire')
)
.then((ret) => console.log(ret))

{
  @set = {
    match: ref(id = "spells_by_element", collection = ref(id = "indexes")),
    terms: "fire"
  }
}

{map[match:{spells_by_element 0xc4203be2c0 <nil>} terms:fire]}

SetRef({"match":{"@ref":{"id":"spells_by_element","class":{"@ref":{"id":"indexes"}}}},"terms":"fire"})

If the index is configured to index multiple terms (i.e. a compound index), match should be passed an Array with the required number of term values:

curl https://db.fauna.com/ \
    -u fnACrVIrDDACAFiX3FN4PhwADpl7dtPRhWObP08j: \
    -d '{
          "match": { "index": "spells_by_element_and_name" },
          "terms": [ "fire", "Fire Beak" ]
        }'

client.Query(
  Match(
    Index("spells_by_element_and_name"),
    Arr("fire", "Fire Beak")));

System.out.println(
        client.query(
           Match(
             Index(Value("spells_by_element_and_name")),
             Arr(Value("fire"), Value("Fire Beak"))
           )
        ).get());

result, _ := client.Query(
    f.MatchTerm(
        f.Index("spells_by_element_and_name"),
        f.Arr{"fire", "Fire Beak"},
    ),
)

fmt.Println(result)

client.query(
  Match(
    Index("spells_by_element_and_name"),
    Arr("fire", "Fire Beak")))

client.query(
  q.match(
    q.index("spells_by_element_and_name"),
    ["fire", "Fire Beak"]
  ))

$client.query do
  match index('spells_by_element_and_name'),
        ['fire', 'Fire Beak']
end

client.query(
    Match(
        index: Index("spells_by_element_and_name"),
        terms: "fire", "Fire Beak"
    )
)

client.query(
  q.Match(
    q.Index('spells_by_element_and_name'),
    ['fire', 'Fire Beak'],
  )
)
.then((ret) => console.log(ret))

{
  @set = {
    match: ref(id = "spells_by_element_and_name", collection = ref(id = "indexes")),
    terms: ["fire", "Fire Beak"]
  }
}

{map[terms:[fire Fire Beak] match:{spells_by_element_and_name 0xc4203b46c0 <nil>}]}

SetRef({"match":{"@ref":{"id":"spells_by_element_and_name","class":{"@ref":{"id":"indexes"}}}},"terms":["fire","Fire Beak"]})

Or conversely, if the index is configured with no terms, then only the index ref need be provided:

curl https://db.fauna.com/ \
    -u fnACrVIrDDACAFiX3FN4PhwADpl7dtPRhWObP08j: \
    -d '{ "match": { "index": "all_spells" } }'

client.Query(Match(Index("all_spells")));

System.out.println(
    client.query(Match(Index(Value("all_spells"))))
    .get());

result, _ := client.Query(f.Match(f.Index("all_spells")))

fmt.Println(result)

client.query(Match(Index("all_spells")))

client.query(q.match(q.index("all_spells")))

$client.query do
  match index('all_spells')
end

client.query(Match(index: Index("all_spells")))

client.query(
  q.Match(q.Index('all_spells'))
)
.then((ret) => console.log(ret))

HTTP/1.1 200 OK
{
  "resource": { "@set": { "match": { "@ref": "indexes/all_spells" } } }
}

{ "@set": { "match": { "@ref": "indexes/all_spells" } } }

{ @set = {match: ref(id = "all_spells", collection = ref(id = "indexes"))} }

{map[match:{all_spells 0xc420399180 <nil>}]}

{ "@set": { "match": { "@ref": "indexes/all_spells" } } }

{ "@set": { "match": { "@ref": "indexes/all_spells" } } }

{ "@set": { "match": { "@ref": "indexes/all_spells" } } }

{ "@set": { "match": { "@ref": "indexes/all_spells" } } }

SetRef({"match":{"@ref":{"id":"all_spells","class":{"@ref":{"id":"indexes"}}}}})

Index terms are always scalar values, and match interprets Arrays as tuples. For single-term indexes, the following expressions are equivalent:

curl https://db.fauna.com/ \
    -u fnACrVIrDDACAFiX3FN4PhwADpl7dtPRhWObP08j: \
    -d '{ "match": { "index": "spells_by_element" }, "terms": "fire" }'

client.Query(Match(Index("spells_by_element"), "fire"));

System.out.println(
    client.query(
      Match(Index(Value("spells_by_element")), Value("fire"))
    ).get());

result, _ := client.Query(f.MatchTerm(f.Index("spells_by_element"), "fire"))

fmt.Println(result)

client.query(Match(Index("spells_by_element"), "fire"))

client.query(q.match(q.index("spells_by_element"), "fire"))

$client.query do
  match index('spells_by_element'), 'fire'
end

client.query(
    Match(index: Index("spells_by_element"), terms: "fire")
)

client.query(
  q.Match(q.Index('spells_by_element'), 'fire')
)
.then((ret) => console.log(ret))

HTTP/1.1 200 OK
{
  "resource": {
    "@set": {
      "match": { "@ref": "indexes/spells_by_element" },
      "terms": "fire"
    }
  }
}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

{
  @set = {
    match: ref(id = "spells_by_element", collection = ref(id = "indexes")),
    terms: "fire"
  }
}

{map[match:{spells_by_element 0xc4203b0680 <nil>} terms:fire]}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

SetRef({"match":{"@ref":{"id":"spells_by_element","class":{"@ref":{"id":"indexes"}}}},"terms":"fire"})

curl https://db.fauna.com/ \
    -u fnACrVIrDDACAFiX3FN4PhwADpl7dtPRhWObP08j: \
    -d '{
          "match": { "index": "spells_by_element" },
          "terms": [ "fire" ]
        }'

client.Query(Match(Index("spells_by_element"), Arr("fire")));

System.out.println(
        client.query(
           Match(Index(Value("spells_by_element")), Arr(Value("fire")))
        ).get());

result, _ := client.Query(
    f.MatchTerm(f.Index("spells_by_element"), f.Arr{"fire"}),
)

fmt.Println(result)

client.query(Match(Index("spells_by_element"), Arr("fire")))

client.query(q.match(q.index("spells_by_element"), ["fire"]))

$client.query do
  match index('spells_by_element'), ['fire']
end

client.query(
    Match(index: Index("spells_by_element"), terms: "fire")
)

client.query(
  q.Match(q.Index('spells_by_element'), ['fire'])
)
.then((ret) => console.log(ret))

HTTP/1.1 200 OK
{
  "resource": {
    "@set": {
      "match": { "@ref": "indexes/spells_by_element" },
      "terms": "fire"
    }
  }
}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

{
  @set = {
    match: ref(id = "spells_by_element", collection = ref(id = "indexes")),
    terms: "fire"
  }
}

{map[match:{spells_by_element 0xc42038d940 <nil>} terms:fire]}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

SetRef({"match":{"@ref":{"id":"spells_by_element","class":{"@ref":{"id":"indexes"}}}},"terms":"fire"})

Source objects

Source objects describe the source collection of index entries and, optionally, bindings. A binding must be a pure lambda function that emits values to be used as a term and/or value.

The collection field can be a single collection ref or set of refs. Documents within collections matching the collection field apply the associated bindings to be used in the index’s terms or values. A collection ref can only exist in one source object. If the collection field is a wildcard (_), the index evaluates all collections. Bindings associated with a wildcard are only used if the collection is not matched by any other source object.

An index cannot be created in the same transaction that creates its source collection(s).

Field Type Definition and Requirements

Field	Type	Definition and Requirements
`collection`	Ref	The collection or collections to be indexed, or a wildcard.
`fields`	Object	An object mapping a binding name to a transformer.

collection

Ref

The collection or collections to be indexed, or a wildcard.

fields

Object

An object mapping a binding name to a transformer.

Binding objects

A binding object contains field names bound to pure, single-argument lambda functions. The function must take the document to be indexed and emit either a single scalar value or an array of scalar values. Binding functions are not permitted to perform reads or writes.

curl https://db.fauna.com/ \
    -u fnACrVIrDDACAFiX3FN4PhwADpl7dtPRhWObP08j: \
    -d '{
          "object": {
            "binding1": {
              "query": {
                "lambda": "document",
                "expr": {
                  "select": [ "data", "field" ],
                  "from": { "var": "document" }
                }
              }
            }
          }
        }'

client.Query(
  Obj(
    "binding1", Query(document => Select(Arr("data", "field"), document))
  ));

System.out.println(
  client.query(
    Obj(
      "binding1", Query(
        Lambda(
          Value("document"),
          Select(
            Arr(Value("data"), Value("field")),
            Var("document"))))
    )
  ).get());

result, _ := client.Query(
    f.Obj{
        "binding1": f.Query(
            f.Lambda(
                "document",
                f.Select(f.Arr{"data", "field"}, f.Var("document")),
            ),
        ),
    },
)

fmt.Println(result)

client.query(
  Obj(
    "binding1" -> Query(
      Lambda { document =>
        Select(Arr("data", "field"), document)
      })
  ))

client.query(
  {
    "binding1": q.query(
      lambda document: q.select(["data", "field"], document)
    )
  })

$client.query do
  {
    binding1: query(do |document| select(['data', 'field'], document) end)
  }
end

client.query(
    Obj(
        "binding1" => Query(
            { document in
                Select(path: "data", "field", from: document)
            }
        )
    )
)

client.query({
  binding1: q.Query(
    q.Lambda('document', q.Select(['data', 'field'], q.Var('document')))
  ),
})
.then((ret) => console.log(ret))

HTTP/1.1 200 OK
{
  "resource": {
    "binding1": {
      "@query": {
        "lambda": "document",
        "expr": {
          "select": [ "data", "field" ],
          "from": { "var": "document" }
        }
      }
    }
  }
}

{
  "binding1": {
    "@query": {
      "lambda": "document",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "document" }
      }
    }
  }
}

{
  binding1: QueryV({
    lambda=document,
    expr={
      select=[data, field],
      from={var=document}
    }
  })
}

map[binding1:{[123 34 108 97 109 98 100 97 34 58 34 105 110 115 116 97 110 99 101 34 44 34 101 120 112 114 34 58 123 34 115 101 108 101 99 116 34 58 91 34 100 97 116 97 34 44 34 102 105 101 108 100 34 93 44 34 102 114 111 109 34 58 123 34 118 97 114 34 58 34 105 110 115 116 97 110 99 101 34 125 125 125]}]

{
  "binding1": {
    "@query": {
      "lambda": "document",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "document" }
      }
    }
  }
}

{
  "binding1": {
    "@query": {
      "lambda": "document",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "document" }
      }
    }
  }
}

{
  "binding1": {
    "@query": {
      "lambda": "document",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "document" }
      }
    }
  }
}

{
  "binding1": {
    "@query": {
      "lambda": "document",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "document" }
      }
    }
  }
}

{ binding1: Query("[object Object]") }

Term objects

Term objects describe the fields used to locate entries in the index. If multiple terms are provided, documents that are missing a value emit a Null term in the index for that field.

If no term objects are defined, passing term values to match is not required. The resulting set contains all documents within the source collection.

A value can be from a field in the document or a binding defined by the source object.

Field Type Definition

Field	Type	Definition
`field`	Array	The path of the field within an document to be indexed.
`binding`	String	The name of a binding from a source object.

field

Array

The path of the field within an document to be indexed.

binding

String

The name of a binding from a source object.

Value objects

Value objects describe the data covered by the index, which are included in query results on the index and control ordering of entries having the same terms. By default, indexes cover only the refs of included documents.

A value can be from a field in the document or a binding defined in a source object.

Field Type Definition

Field	Type	Definition
`field`	Array	The path of the field within an document to be indexed.
`binding`	String	The name of a binding from a source object.
`reverse`	Boolean	Whether this field’s value should sort reversed. Defaults to `false`.

field

Array

The path of the field within an document to be indexed.

binding

String

The name of a binding from a source object.

reverse

Boolean

Whether this field’s value should sort reversed. Defaults to false.

The document’s ref may also appear in before and after cursors when paging through an index with Paginate, even if the ref does not appear as a covered value in the index configuration. These "extra" refs are used to stabilize pagination.

Field values

Any of a document’s fields may be indexed. The value of field in a Term or Value object indicates the position within a document for a field. For example, the field ref refers to the top-level ref field. The field ["data", "address", "street"] refers to the street field contained in an address object within the document’s data object.

Ordering

Covered values sort lexically according to their type. Strings and Numbers sort using their natural order, while Arrays and Objects sort according to their contents. For example, { "name": "Hen Wen" } appears after { }, and { "age": 110 }.

Documents may have different types of values in the same field, or a document may be missing a field entirely. An index covering that path sorts values in this order: Numbers, Strings, Refs, Timestamps, Dates, Booleans, Nulls. Note that objects and arrays are not indexed, although the fields of an object can be indexed.

The default sort order may be reversed on a per-field basis using the reverse flag in the index configuration.

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!