CreateIndex

Creates and populates an index on one entity or connection property. A successful response contains status: 0. Use GetIndexes to list definitions and RemoveIndex to remove one by class, property and kind.

Requires indexes.create permission. No input or output blobs are used.

Parameters

Parameter	Type / required	Default and behavior
`target`	string / required	`entity` or `connection`.
`class`	string / required	Class whose property is indexed.
`property`	string / required	Stored property name; `_uniqueid` already has an index and is rejected here.
`kind`	string / optional	`ordered` when omitted.
`params`	object / optional	Defaults depend on kind; see the definitions below. Unknown or invalid options fail validation.

Class and property names are matched without case sensitivity. Each property can have at most one index of each kind. Different kinds can coexist, but creating another index of the same kind fails even when its parameters differ. Explicitly specifying default parameters is equivalent to omitting them.

Parameters cannot be changed after creation. To change them, remove the index and create a new one. Both commands can run in the same transaction. Computed properties, descriptor vector indexes, and indexes spanning multiple properties are not supported by this command.

Parameter contracts by kind

params is an object. Only the members listed for the selected kind are accepted; parameters for another kind and unknown members fail validation. Omitting the object or a member uses the defaults below.

Kind	Member	Type / required	Default and bounds
ordered, trigram, similarity	`text`	string / optional	case_sensitive; also accepts case_insensitive or dual_case.
fulltext	`analyzer`	string / optional	unicode_v1; no other analyzer value is accepted.
array	`positions`	array of whole numbers, or string / optional	[]; each number must be finite and in 0–4294967295. The only string value is “all”. Booleans are rejected. Numerically integral values such as 1.0 are accepted, then positions are sorted and deduplicated.
array	`type_postings`	Boolean / optional	true; false omits per-position type postings. It has no effect when no positions are indexed.
type	No members	empty object / optional	{}; every nonempty params object is rejected.

Returned index definitions normalize defaults: text modes and the fulltext analyzer are explicit, array positions are explicit, and array type_postings is emitted only when false. These are stored index definitions, not per-query tuning options.

Index kinds

Each index kind supports a different set of property operations.

Ordered

ordered always indexes booleans, numbers, datetimes, and strings for equality and range comparisons. Its only parameter is text: case_sensitive (default), case_insensitive, or dual_case.

case_insensitive uses Unicode full case folding without removing accents or normalizing Unicode forms. dual_case supports both case-sensitive and case-insensitive comparisons.

Trigram

trigram supports substring searches. Its only parameter is text, which accepts case_sensitive (default), case_insensitive, or dual_case. The case modes have the same meaning as for ordered indexes.

Similarity

similarity supports whole-string fuzzy matching with the similarity and isimilarity functions. Its only parameter is text:

case_sensitive (default): Supports similarity.
case_insensitive: Supports isimilarity.
dual_case: Supports both functions.

These functions also work without an index. A similarity index can accelerate filters that compare a stored string property with a literal string and require a positive score. Trigram indexes support substring searches, not similarity scoring.

Full text

fulltext is required for the fulltext function, which matches words and returns BM25 relevance scores for a native string property.

The only supported parameter is {"analyzer": "unicode_v1"}, which is also the default. The analyzer applies Unicode NFKC case folding and splits text at word boundaries. See Text search expressions for matching rules, score interpretation, and input limits.

Type

type supports property presence and type queries. It distinguishes boolean, number, date, text, JSON, native array, and blob properties. It accepts no parameters; omit params or use {}.

JSON properties have the JSON storage type regardless of their payload. Expression functions such as is_missing and is_finite evaluate the payload’s value.

A type index is optional and can accelerate property presence and type queries. Ordered and trigram indexes do not require a separate type index. Adding or removing an index does not change query results or error behavior. See constraints for supported operators.

Array

array supports in and not_in membership filters between a native Array property and constant values or lists, with the property on either side. String membership uses exact byte matching. JSON payloads are not indexed. An array index can be created before the property contains arrays; scalar and missing values are not included.

positions is a list of zero-based element positions or the string "all" to index every position present in each array. Positions must be whole numbers between 0 and 4294967295. They are sorted and deduplicated in the returned definition. Omitting params or positions is equivalent to {"positions": []}; no positional entries are created.

The default empty position list supports membership queries. Configured positions can also accelerate queries about element values and types. Indexing every position with {"positions": "all"} increases storage and write work with array length.

Set type_postings to false to reduce storage and write work, for example {"positions": "all", "type_postings": false}. This may make mixed-type or null queries slower; results remain the same. The default is true and is omitted from returned parameters. This setting has no effect when no positions are indexed.

Positional entries can accelerate ==, !=, and range comparisons between at("$property", constant_position) and a constant scalar, including field-free expressions such as subtract or to_date. They also support is_missing, is_finite, and membership in a constant list. Null and Boolean values support equality and inequality, not ordering.

Array indexes can also accelerate array-length and whole-array equality queries, even without configured positions. Array equality preserves element order, duplicates, and types; null elements count toward array length.

ApertureDB chooses whether to use an index for each query. An index may provide less benefit for small datasets or queries matching most records. Computed arrays and JSON payloads do not use array indexes.

A small sorted page using one constant-position at expression can benefit from an array index when type_postings is enabled. See sort for details. Remove and recreate an existing index to change its configured positions or type_postings setting.

Response and recovery

Success returns status: 0. If an index with the same target, class, property, and kind already exists, creation fails with status: -1, including when the parameters are identical. There is no if_not_found or if_not_exists option for this command.

status: -1 with Index on property _uniqueid is not needed requires omitting that index request. Creating an index on a computed property also returns -1. Invalid kind-specific options fail validation; use the parameters for the selected kind.

See Responses for error envelopes and transaction behavior.

Index creation during application startup

An application can check whether its required index exists with GetIndexes. The target, class, property, kind, and normalized parameters identify the desired definition. Matching parameters, including defaults, mean the index is ready to use. Different parameters require an explicit decision to remove and recreate the index.

When the index is absent, a separate CreateIndex transaction isolates index creation from other application writes. Concurrent startup processes can both observe an absent index; one creates it, and the other receives an error. A second GetIndexes query establishes whether the desired definition exists. The stored definition determines the outcome; info provides diagnostic text.

A duplicate creation error aborts the graph transaction and rolls back its graph changes. Ignoring the error does not commit other writes in that transaction. See Failures and retrying writes.

Examples

Create an ordered index for names on Person entities:

[{
    "CreateIndex": {
        "kind": "ordered",
        "target": "entity",
        "class": "Person",
        "property": "name",
        "params": {
            "text": "dual_case"
        }
    }
}]

Create an index for the presence and type of an optional property:

[{
    "CreateIndex": {
        "kind": "type",
        "target": "entity",
        "class": "Person",
        "property": "email",
        "params": {
        }
    }
}]

Create a membership index for a list property:

[{
    "CreateIndex": {
        "kind": "array",
        "target": "entity",
        "class": "Palette",
        "property": "colors",
        "params": {"positions": []}
    }
}]

The membership index can accelerate these queries:

["red", "in", "$colors"]
["$colors", "in", {"array": ["red", "blue"]}]

The following at comparison can use an array index configured with {"positions": [0]} or {"positions": "all"}:

[{"at": ["$colors", 0]}, "==", "red"]

Parameters​

Parameter contracts by kind​

Index kinds​

Ordered​

Trigram​

Similarity​

Full text​

Type​

Array​

Response and recovery​

Index creation during application startup​

Examples​