CreateIndex =========== Creates and populates an index on one entity or connection property. A successful response contains ``status: 0``. Use :doc:`GetIndexes` to list definitions and :doc:`RemoveIndex` to remove one by class, property and kind. Requires ``indexes.create`` permission. No input or output blobs are used. Parameters ---------- .. include:: metadata_targets.rst 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 :doc:`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 :doc:`../DescriptorIndexes` for parameter tables, defaults, bounds, and indexing behavior for each kind. .. code-block:: json [{"CreateIndex":{"target":"descriptor","class":"Faces","property":"_blob", "kind":"hnsw","params":{"dimensions":128,"metric":["L2","CS"], "M":32,"lazy_indexing":true},"metadata":{"model":"face-v1"}}}] .. _index-parameter-fields: 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. .. list-table:: :header-rows: 1 :widths: 22 20 24 34 * - 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. .. _indexes: 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 :ref:`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 :ref:`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 :ref:`text-search` 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 :doc:`../parameters/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 :doc:`../parameters/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 :doc:`../Responses` for error envelopes and transaction behavior. .. _idempotent-startup-migrations: Index creation during application startup ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An application can check whether its required index exists with :doc:`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 :ref:`response-error-phases`. Examples -------- Create an ordered index for names on ``Person`` entities: .. TESTED_EXAMPLE: CreateIndex_1 .. code-block:: json [{ "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: .. TESTED_EXAMPLE: CreateIndex_2 .. code-block:: json [{ "CreateIndex": { "kind": "type", "target": "entity", "class": "Person", "property": "email", "params": { } } }] Create a membership index for a list property: .. TESTED_EXAMPLE: CreateIndex_3 .. code-block:: json [{ "CreateIndex": { "kind": "array", "target": "entity", "class": "Palette", "property": "colors", "params": {"positions": []} } }] The membership index can accelerate these queries: .. TESTED_EXAMPLE: CreateIndex_4 .. code-block:: python ["red", "in", "$colors"] ["$colors", "in", {"array": ["red", "blue"]}] The following ``at`` comparison can use an array index configured with ``{"positions": [0]}`` or ``{"positions": "all"}``: .. TESTED_EXAMPLE: CreateIndex_5 .. code-block:: json [{"at": ["$colors", 0]}, "==", "red"]