CreateIndex

CreateIndex( param_object )
CreateIndex( param_object )
CreateIndex( param_object )
CreateIndex( param_object )
create_index( param_object )
create_index param_object
CreateIndex( param_object )
CreateIndex( param_object )

Description

The CreateIndex function adds a new index to the cluster with the specified parameters. After the transaction containing the CreateIndex is completed, the index is immediately available for reads. (The index may not be used in the transaction it was created, and it may not be created in the same transaction as its source collection(s).) The index may return incomplete results until it is fully built and marked as active. FaunaDB builds the index asynchronously by scanning over relevant documents of the source collection(s).

You can set active: true during index creation. If you do so, the index is assumed to be built and relevant documents are not included in the index creation. As you create, update, or delete relevant documents, the index is updated to reflect those modifications.

As such, we recommend only using active: true during index creation for empty collections. For collections with relevant documents, it is better to not set active: true and await the completion of its build, to avoid queries returning unexpectedly small result sets.

You can query whether an index is built:

Get(Index("index_name"))

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

Updating index fields

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

  • If you update the unique field, it does not remove existing duplicated items from the index, but does prevent future duplicates from being added.

  • The fields of an index which may not be modified are: terms, values, or partitions.

Unique name required

The index name must be unique within the database. If you try to lookup an index by name and only create it if it does not exist, the operation might fail if another transaction created the index in the meantime.

Deleting an index

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

Parameters

Argument Type Definition and Requirements

param_object

Object

The param_object fields are described below.

param_object

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.

active

Boolean

Set to true to avoid building the index from relevant documents. The default is false.

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.

partitions

Integer

Optional - The number of sub-partitions within each term.

When unique is true, partitions is always 1.

Otherwise, the default is:

  • 8 when the index has no terms.

  • 1 in all other cases.

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.

Returns

An object containing the metadata about the CreateIndex operations.

Field Name Field Type Definition and Requirements

ref

Reference

The reference is an automatically-generated, unique identifier within the database to the index that was created.

name

String

The logical name of the index created.

source

Array

The source and binding of the newly created index.

ts

Long

The timestamp associated with the creation of the index.

active

Boolean

Indicates if the index has completed building and is fully operational.

partitions

Long

The timestamp associated with the creation of the index.

Examples

The CreateIndex operation builds an index on the collection "spells" with the name "new-index".

curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "create_index": {
            "object": { "name": "new-index", "source": { "collection": "spells" } }
          }
        }'
client.Query(
  CreateIndex(
    Obj("name", "new-index", "source", Collection("spells"))));
System.out.println(
      client.query(
          CreateIndex(
              Obj(
                  "name", Value("new-index"),
                  "source", Collection(Value("spells"))
              )
          )
      ).get());
result, _ := client.Query(
    f.CreateIndex(
        f.Obj{"name": "new-index", "source": f.Collection("spells")},
    ),
)

fmt.Println(result)
client.query(
  CreateIndex(
    Obj("name" -> "new-index", "source" -> Collection("spells"))))
client.query(
  q.create_index(
    {"name": "new-index", "source": q.collection("spells")}
  ))
$client.query do
  create_index name: 'new-index', source: collection('spells')
end
client.query(
    CreateIndex(
        Obj("name" => "new-index", "source" => Collection("spells"))
    )
)
client.query(
  q.CreateIndex(
    { name: "new-index", source: q.Collection("spells") }))
.then((ret) => console.log(ret))
HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "indexes/new-index" },
    "class": { "@ref": "indexes" },
    "ts": 1509244540009619,
    "active": false,
    "partitions": 8,
    "name": "new-index",
    "source": { "@ref": "classes/spells" }
  }
}
{
  "ref": { "@ref": "indexes/new-index" },
  "class": { "@ref": "indexes" },
  "ts": 1509244540009619,
  "active": false,
  "partitions": 8,
  "name": "new-index",
  "source": { "@ref": "classes/spells" }
}
{
  ref: ref(id = "new-index", collection = ref(id = "indexes")),
  ts: 1526674566835735,
  active: false,
  partitions: 8,
  name: "new-index",
  source: ref(id = "spells", collection = ref(id = "collections"))
}
map[ref:{new-index 0xc4201ef8e0 <nil>} ts:1509244540009619 active:false partitions:8 name:new-index source:{spells 0xc4201efb40 <nil>}]
{
  "ref": { "@ref": "indexes/new-index" },
  "class": { "@ref": "indexes" },
  "ts": 1509244540009619,
  "active": false,
  "partitions": 8,
  "name": "new-index",
  "source": { "@ref": "classes/spells" }
}
{
  "ref": { "@ref": "indexes/new-index" },
  "class": { "@ref": "indexes" },
  "ts": 1509244540009619,
  "active": false,
  "partitions": 8,
  "name": "new-index",
  "source": { "@ref": "classes/spells" }
}
{
  "ref": { "@ref": "indexes/new-index" },
  "class": { "@ref": "indexes" },
  "ts": 1509244540009619,
  "active": false,
  "partitions": 8,
  "name": "new-index",
  "source": { "@ref": "classes/spells" }
}
{
  "ref": { "@ref": "indexes/new-index" },
  "class": { "@ref": "indexes" },
  "ts": 1509244540009619,
  "active": false,
  "partitions": 8,
  "name": "new-index",
  "source": { "@ref": "classes/spells" }
}
{ ref: Ref(id=new-index, collection=Ref(id=indexes)),
  ts: 1527275052756370,
  active: false,
  partitions: 8,
  name: 'new-index',
  source: Ref(id=spells, collection=Ref(id=collections)) }

Was this article helpful?

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

Thank you for your feedback!