Vector Index

Overview

A vector index is designed to efficiently store and manage high-dimensional vectors (or embeddings), enabling fast retrieval of similar vectors based on a chosen similarity metric. Instead of performing an exhaustive search across all stored vectors, the vector index significantly reduces the search space, making nearest-neighbor retrieval more efficient.

Ultipa supports two vector index modes:

• Embedded mode (default): Uses a built-in HNSW (Hierarchical Navigable Small World) index within the shard server process. No external dependencies required, with automatic DML synchronization.
• External mode: Uses an external vector server deployed as a separate Docker container. Supports additional index types beyond HNSW.

Vectors and Embeddings

Vectors can be viewed as an ordered list of numbers. For example, the vector [1, 2] represents a direction from the origin to the point (1, 2) in a two-dimensional space, and the distance (or magnitude) to that point.

In the context of machine learning and natural language processing (NLP), the term embedding is commonly used when referring vectors. An embedding is a high-dimensional vector that represents data, often with hundreds of dimensions.

Creating Embeddings

You can create embeddings for both structured data (e.g., text) and unstructured data (e.g., images, graphs) using various models. Some popular models include:

• OpenAI: A collection of models to turn text into embeddings.
• Node2Vec: A model that generates embeddings for graph nodes based on their relationships.
• ResNet (Residual Networks): A series of models for generating image embeddings.

Why Embeddings

Embeddings are often generated by considering the context of the data entity rather than just the data itself. This is especially true for tasks like NLP, where the meaning of a word is influenced by its surrounding context.

Consider the word "bank", which has multiple meanings depending on the context:

1. Bank as a financial institution: "I went to the bank to deposit some money."
2. Bank as the side of a river: "We sat on the bank of the river to watch the sunset."

This contextual information makes embeddings much more powerful for downstream tasks like semantic search, recommendation and classification.

Loading Embeddings into Ultipa

After creating embeddings for entities, they can be imported or stored into Ultipa as properties of type list<float> or list<double>. By creating vector indexes for these properties, you can perform vector searches.

Vector Search

Vector search refers to the process of finding vectors that are most similar to a given query vector, using a similarity measure. Ultipa supports the following similarity measures:

• L2 Distance (Euclidean Distance): Calculates the straight-line distance between two points in a high-dimensional space. This measure is sensitive to the magnitude of the vectors.

• Cosine Similarity: Measures the cosine of the angle between two vectors, indicating their orientation in space. It is independent of vector magnitude.

• Inner Product: Computes the dot product between two vectors, often used when the magnitude of the vectors is important.

Example Graph

The example graph consists of 10 Book nodes, each containing the properties name, author, summary, and summaryEmbedding. The summaryEmbedding holds the 384-dimensional text embeddings of the summary, generated using the all-MiniLM-L6-v2 model from Hugging Face.

Create the graphInsert data to the graph
CREATE GRAPH myGraph { 
  NODE Book ({title string, author string, summary text, summaryEmbedding list<double>})
} PARTITION BY HASH(Crc32) SHARDS [1]

Showing Vector Indexes

To retrieve node vector indexes in the current graph:

GQL
SHOW NODE VECTOR INDEX

To retrieve edge vector indexes in the current graph:

GQL
SHOW EDGE VECTOR INDEX

The information about vector indexes is organized into a _nodeVectorIndex or _edgeVectorIndex table with the following fields:

Creating a Vector Index

You can create a vector index using the CREATE VECTOR INDEX statement for a node property of the list<float> or list<double> type. The vector index creation runs as a job, you may run SHOW JOB <id?> afterward to verify the success of the creation.

To create a vector index named summary_embedding for the property summaryEmbedding of Book nodes:

GQL
CREATE VECTOR INDEX "summary_embedding" ON NODE Book (summaryEmbedding) OPTIONS {
  similarity_function: "COSINE",
  index_type: "FLAT",
  dimensions: 384,
  vector_server: "vector_server_1"
}

Details

• The vector index name must be unique. Naming conventions are:
  • 2 to 64 characters.
  • Begins with a letter.
  • Allowed characters: letters (A-Z, a-z), numbers (0-9) and underscores (_).
• A vector index is applied to a single schema and a single property.
• Configurations for a vector index:

Embedded Mode

In embedded mode, the vector_server parameter is not required. The index uses the built-in HNSW algorithm:

GQL
CREATE VECTOR INDEX "idx_embedding" ON NODE Person (embedding) OPTIONS {
  similarity_function: "COSINE",
  index_type: "HNSW",
  dimensions: 128
}

Edge Vector Index

You can also create vector indexes on edge properties:

GQL
CREATE VECTOR INDEX "idx_edge_vec" ON EDGE Relation (weight_vector) OPTIONS {
  similarity_function: "IP",
  index_type: "HNSW",
  dimensions: 64
}

Using IF NOT EXISTS

The IF NOT EXISTS clause prevents errors when creating a vector index that already exists:

GQL
CREATE VECTOR INDEX "idx_embedding" ON NODE Person (embedding) OPTIONS {
  similarity_function: "COSINE",
  index_type: "HNSW",
  dimensions: 128
} IF NOT EXISTS

Dropping a Vector Index

You can drop a vector index using the DROP VECTOR INDEX statement. Dropping a vector index does not affect the actual property values stored in shards.

NOTE

A property with a vector index cannot be dropped until the vector index is deleted.

To drop a node vector index:

GQL
DROP VECTOR INDEX "summary_embedding" ON NODE

To drop an edge vector index:

GQL
DROP VECTOR INDEX "idx_edge_vec" ON EDGE

Using Vector Indexes

You can use a vector index for vector search by calling the vector.queryNodes() or vector.queryEdges() procedure.

Syntax

Syntax
CALL vector.queryNodes("<vectorIndexName>", <numMostSimNodes>, <targetVector>)

Parameters

Returns

• _uuid: _uuid of the retrieved node.
• score: The similarity score between the vector of retrieved node and the target vector.

Example

Finds the top two books most similar to Pride and Prejudice by the vector index summary_embedding, return the book names along with the similarity scores between them:

GQL
MATCH (target:Book {title: "Pride and Prejudice"})
CALL vector.queryNodes('summary_embedding', 3, target.summaryEmbedding)
YIELD result
MATCH (book WHERE book._uuid = result._uuid)
RETURN table(book.title, result.score)

Result:

Edge Vector Search

To search edge vectors, use the vector.queryEdges() procedure:

GQL
CALL vector.queryEdges("<vectorIndexName>", <numMostSimEdges>, <targetVector>)
YIELD result
RETURN result

The parameters and return fields are the same as vector.queryNodes().

DML Auto-Maintenance

In embedded mode, vector indexes are automatically synchronized when data changes:

Configuration

In embedded mode, add the following section to shard-server.config:

Ini
[VectorIndex]
vector_mode = embedded
hnsw_m = 16
hnsw_ef_construction = 200
hnsw_ef_search = 100
save_interval_s = 60

Annex: Index Types