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
An exact node target is its type and class, for example
{"target":"image","class":"Photos"}.
For a connection, class names the source class, connection class, and
destination class. target supplies the corresponding endpoint types.
{
"class": {"src": "People", "connection": "AppearsIn", "dst": "Photos"},
"target": {"src": "entity", "dst": "image"}
}
Metadata mutations require all five values for a connection. Class names are
nonempty, cannot begin with _, and are matched without case sensitivity.
Index selectors also include property and kind. With GetIndexes and
GetAggregates you can supply only the fields you want to match, such as
{"class":{"connection":"AppearsIn"},"target":{"dst":"image"}}.
Required fields are target, class, property, and kind. params holds kind-specific configuration.
metadata optionally stores customer values for vector indexes only.
One column supports one definition of each kind. Repeating the same normalized
definition is idempotent. Use UpdateIndex to change a vector index or
remove and recreate a property index to change its parameters. _uniqueid
and category output fields cannot be indexed.
Vector indexes
Set target to descriptor, property to _blob, and kind to
flat, ivf, hnsw, or acorn. Creation registers the class if needed
and populates the index from existing vectors. To use multiple engines on a
class, issue one CreateIndex per kind.
Supply dimensions and any optional settings directly in params. The
example creates a lazy HNSW index supporting both squared Euclidean distance
and cosine similarity. See Descriptor classes and vector indexes for parameter tables,
defaults, bounds, and indexing behavior for each kind.
[{"CreateIndex":{"target":"descriptor","class":"Faces","property":"_blob",
"kind":"hnsw","params":{"dimensions":128,"metric":["L2","CS"],
"M":32,"lazy_indexing":true},"metadata":{"model":"face-v1"}}}]
Property index parameters
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 |
|
string / optional |
case_sensitive; also accepts case_insensitive or dual_case. |
fulltext |
|
string / optional |
unicode_v1; no other analyzer value is accepted. |
array |
|
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 |
|
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): Supportssimilarity.case_insensitive: Supportsisimilarity.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, matching normalized parameters and supplied metadata
succeed without rebuilding. A different definition fails with status: -1. 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. Stored/computed applicability depends on the index kind; unsupported computed
columns return -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; identical normalized definitions succeed idempotently.
A second GetIndexes query establishes whether the desired definition exists.
The stored definition determines the outcome; info provides diagnostic text.
A conflicting 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"]