HelixDB Docs

Guide

Secondary indexes narrow node or edge sources by property. Index creation is asynchronous and includes existing data through a durable backfill.

Index families

Family	Use
Equality	Exact property matches
Unique equality	Exact matches plus uniqueness enforcement
Range ascending	Ordered comparisons and ascending scans
Range descending	Descending-first ordered scans

Definitions include the entity kind, label, property, and range direction where applicable.

Create an equality index

write_batch()
    .var_as(
        "index",
        g().create_index_if_not_exists(IndexSpec::node_equality("User", "status")),
    )
    .returning(["index"]);

writeBatch()
  .varAs(
    "index",
    g().createIndexIfNotExists(IndexSpec.nodeEquality("User", "status")),
  )
  .returning(["index"]);

helix.WriteQuery("create_user_status_index").
	VarAs(
		"index",
		helix.G().CreateIndexIfNotExists(
			helix.NodeEqualityIndex("User", "status"),
		),
	).
	Returning("index")

(
    write_batch()
    .var_as(
        "index",
        g().create_index_if_not_exists(
            IndexSpec.node_equality("User", "status")
        ),
    )
    .returning(["index"])
)

{
  "request_type": "write",
  "query_name": "create_user_status_index",
  "query": {
    "write": {
      "entries": [{
        "query": {
          "name": "index",
          "root": {
            "create_index": {
              "spec": {
                "node_equality": {
                  "label": "User",
                  "property": "status",
                  "unique": false
                }
              },
              "if_not_exists": true
            }
          }
        }
      }],
      "returns": ["index"]
    }
  }
}

The returned DDL receipt identifies the durable operation. A build is not listed as an active index until it succeeds, so poll its operation_id before depending on indexed performance.

Track an index operation

read_batch()
    .var_as("status", g().get_index_operation(operation_id))
    .returning(["status"]);

readBatch()
  .varAs("status", g().getIndexOperation(operationId))
  .returning(["status"]);

helix.ReadQuery("index_operation").
	VarAs("status", helix.G().GetIndexOperation(operationID)).
	Returning("status")

(
    read_batch()
    .var_as("status", g().get_index_operation(operation_id))
    .returning(["status"])
)

{
  "request_type": "read",
  "query": {
    "read": {
      "entries": [{
        "query": {
          "name": "status",
          "root": { "get_index_operation": { "operation_id": "<operation_id>" } }
        }
      }],
      "returns": ["status"]
    }
  }
}

status is queued, running, blocked, succeeded, or aborted. A blocked operation carries a blocker_code and does not resume on its own. Fix the cause, then run retry_index_operation (retryIndexOperation) as a write with the same operation_id, or abort_index_operation (abortIndexOperation) to discard the build. While the build is in flight, repeating the same CREATE returns existing_operation with the same operation_id instead of starting another build. Once the index is active, it returns already_active without an operation_id. After an abort finishes, it starts a new build with a new operation_id.

Query indexed data

Use nWithLabelWhere("User", SourcePredicate.eq("status", "active")) (or the language-equivalent snake_case builder) for index push-down, then project the required fields. The read must be scoped to the index’s label: a source predicate without a label scans every node. A .where(...) directly after nWithLabel("User") is pushed down to the index too; later in a traversal it filters a possibly larger intermediate stream. Cypher statements use these indexes automatically, without naming them. An equality or IN match on a labeled node reads an equality index, and range comparisons and ordered LIMIT reads use a range index:

// parameters: {"status": "active"}
MATCH (u:User {status: $status})
RETURN u.name AS name

Explain the statement to see which index the plan reads. See Cypher indexes and performance for the conditions that keep an index in use.

Unique indexes

A unique equality backfill becomes blocked if existing data contains duplicates. Fix the source data, then retry the same operation instead of creating a new definition.

Start Here

Core Concepts

Query Guides

Secondary indexes

Index families

Create an equality index

Track an index operation

Query indexed data

Unique indexes

Next steps

Troubleshoot index operations

Filtering

​Index families

​Create an equality index

​Track an index operation

​Query indexed data

​Unique indexes

​Next steps

Troubleshoot index operations

Filtering

Index families

Create an equality index

Track an index operation

Query indexed data

Unique indexes

Next steps