Vector indexes

Create vector indexes and run nearest-neighbor search

Guide

A vector index ranks node or edge embeddings by distance to a query vector. Use it for semantic search, recommendations, and retrieval over any label that stores an embedding as a top-level numeric array property.

Every definition declares a non-zero dimension and one distance metric: cosine, Euclidean, or Manhattan. Stored embeddings and every query vector must have exactly the declared dimension.

For background, see What is vector search? and vector distance metrics.

Create a vector index

Rust

write_batch()
    .var_as(
        "index",
        g().create_vector_index_nodes(
            "Doc",
            "embedding",
            std::num::NonZeroUsize::new(3).expect("non-zero dimension"),
            VectorDistanceMetric::Cosine,
            None::<&str>,
        ),
    )
    .returning(["index"]);

Pass a tenant property as the final argument to partition the index by tenant. See tenant-partitioned search indexes.

Creation returns a receipt before the backfill over existing data finishes. The index becomes queryable only after validation and atomic activation.

Search an index

Search the whole index when every record of the label is a valid result. This request returns the ten Doc nodes closest to the query vector:

Rust

read_batch()
    .var_as(
        "hits",
        g().vector_search_nodes("Doc", "embedding", vec![0.1, 0.8, 0.2], 10, None)
            .value_map(Some(vec!["$id", "title", "$distance"])),
    )
    .returning(["hits"]);

Hits arrive closest first, ordered by $distance and then by ID. Use vectorSearchEdges / vector_search_edges (VectorSearchEdges in Go) to search an edge index. For a tenant-partitioned index, pass the tenant value as the final argument.

$distance exists only on the hit stream. Project it before traversing away from a hit if the response needs it.

Prefilter with a traversal

To rank only the nodes or edges a traversal reaches, such as documents a user may access, search within the traversal instead of the whole index. See Prefiltered search.

Search consistency

By default, searches include committed writes that the index worker has not published into the index yet. A read request can opt into eventual search, which bounds that work per search. See Search consistency for both modes, searches in write batches, and index_backpressure.

Result limits

The server caps the effective result count of a whole-index search at 800. A narrower bound from the surrounding plan can lower it. Prefiltered searches have their own limits.

Operational notes

• Creation returns before the backfill necessarily finishes.
• Writes made while an index builds are queued and published after it activates; strong searches include them as soon as the index is active. Until then they count toward index backpressure.
• Malformed source vectors can block the operation.
• A new generation remains hidden until validation and activation succeed.
• Dropping an index is also a durable lifecycle operation.

Next steps

Project search results

Preserve ranked hit metadata before continuing a traversal.

Text indexes

Rank string properties with BM25 keyword search.

Troubleshoot index operations

Resolve blocked builds and lifecycle errors.

Limits

Review supported property types and search limits.