`CreateIndex`

CreateIndex( param_object )

CreateIndex( param_object )

CreateIndex( param_object )

CreateIndex( param_object )

create_index( param_object )

CreateIndex( param_object )

Description

The CreateIndex function adds a new index to the database 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. Fauna builds the index asynchronously by scanning over relevant documents of the source collection(s).

When an index is created, documents are immediately indexed if the associated collection contains up to 128 events (which include document creation, updates, and deletions). When an index contains all of a collection’s documents, including each document’s events, it is an "active" index.

For collections with more than 128 events (which include document creation, updates, and deletions), 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 (replacing index_name with the name of the index that you want to check):

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.

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.

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 and values.

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

Parameter Type Definition and Requirements

Parameter	Type	Definition and Requirements
`param_object`	Object	The `param_object` fields are described below.

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 _. Cannot contain the % character.

source

Reference or Array

A Collection reference, or an array of one or more source objects describing source collections and (optional) binding fields.

terms

Array

Optional - An array of Term objects describing the fields that should be searchable. Indexed terms can be used to search for field values, via the Match function. The default is an empty Array.

values

Array

Optional - An array of Value objects describing the fields that should be reported in search results. The default is an empty Array. When no values fields are defined, search results report the indexed document’s Reference.

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. Subsequent reads or writes must wait until this index’s writes for covered documents have completed.

If false, writes to this index occur asynchronously and do not block subsequent reads or writes. This is better performance-wise, but the lack of serialization makes it notably more difficult to use this index to read your own writes.

The default is true.

See Isolation levels for details.

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 having no data.

ttl

Timestamp

Optional - A timestamp indicating the document’s time-to-live, which is when the document should be removed. When a document is removed, the document’s existence ceases (as if it never existed); temporal queries cannot recover the document.

Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens) "expires" due to the setting in the ttl field, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal actually occurs.

As of version 3.0.0, the ttl field is honored on read — a document that should have been removed behaves as if it has been removed. However, until removal actually occurs due to background task processing, you can continue to access the history of the document, provided you have its reference, via the Events function.

Returns

An object containing the metadata about the CreateIndex operations.

Field Name Field Type Definition and Requirements

Field Name	Field Type	Definition and Requirements
`ref`	Reference	The Reference to the index that was created in the database.
`name`	String	The name of the index created.
`source`	Array	The source and binding of the newly created index.
`ts`	Long	The timestamp, with microsecond resolution, associated with the creation of the index.
`active`	Boolean	Indicates if the index has completed building and is fully operational.
`partitions`	Integer	The number of sub-partitions used by this index. This value can be 8 or 1: `1` when `unique` is `true`. `8` when the index has no `terms`. `1` in all other cases.

ref

Reference

The Reference to the index that was created in the database.

name

String

The name of the index created.

source

Array

The source and binding of the newly created index.

ts

Long

The timestamp, with microsecond resolution, associated with the creation of the index.

active

Boolean

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

partitions

Integer

The number of sub-partitions used by this index. This value can be 8 or 1:

1 when unique is true.
8 when the index has no terms.
1 in all other cases.

Examples

The following query creates an index on the collection "spells" with the name "new-index":

try
{
    Value result = await client.Query(
        CreateIndex(
            Obj("name", "new-index", "source", Collection("spells"))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(ref: RefV(id = "new-index", collection = RefV(id = "indexes")),ts: LongV(1603756181200000),active: BooleanV(True),serialized: BooleanV(True),name: StringV(new-index),source: RefV(id = "spells", collection = RefV(id = "collections")),partitions: LongV(8))

result, err := client.Query(
	f.CreateIndex(
		f.Obj{
			"name": "new-index",
			"source": f.Collection("decrepit_huts"),
		}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[active:true name:new-index partitions:8 ref:{new-index 0xc00016a0c0 0xc00016a0c0 <nil>} serialized:true source:{decrepit_huts 0xc00016a1b0 0xc00016a1b0 <nil>} ts:1603747135990000]

System.out.println(
    client.query(
        CreateIndex(
            Obj(
                "name", Value("new-index"),
                "source", Collection("spells")
            )
        )
    ).get());

{ref: ref(id = "new-index", collection = ref(id = "indexes")), ts: 1593464646510000, active: true, serialized: true, name: "new-index", source: ref(id = "spells", collection = ref(id = "collections")), partitions: 8}

client.query(
  q.CreateIndex({
    name: 'new-index',
    source: q.Collection('spells'),
  })
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  ref: Index("new-index"),
  ts: 1591996190530000,
  active: true,
  serialized: true,
  name: 'new-index',
  source: Collection("spells"),
  partitions: 8
}

result = client.query(
  q.create_index({
    "name": "new-index",
    "source": q.collection("spells")
  })
)
print(result)

{'ref': Ref(id=new-index, collection=Ref(id=indexes)), 'ts': 1592856422060000, 'active': True, 'serialized': True, 'name': 'new-index', 'source': Ref(id=spells, collection=Ref(id=collections)), 'partitions': 8}

CreateIndex({
  name: 'new-index',
  source: Collection('spells'),
})

{
  ref: Index("new-index"),
  ts: 1624310362210000,
  active: true,
  serialized: true,
  name: 'new-index',
  source: Collection("spells"),
  partitions: 8
}

Query metrics:

bytesIn: 81
bytesOut: 252
computeOps: 1
readOps: 0
writeOps: 5
readBytes: 1,825
writeBytes: 855
queryTime: 70ms
retries: 0

Indexes

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!

CreateIndex

Description

Updating index fields

Unique name required

Deleting an index

Parameters

param_object

Returns

Examples

Related References

Keyboard shortcuts

While reading

While searching

URL fragments

`CreateIndex`

`param_object`