Index parameters and tuning for the Virtuoso vector index

The Virtuoso vector index is built on HNSW (Hierarchical Navigable Small World) graphs, which perform approximate nearest neighbor (ANN) search over your embeddings. ANN trades a small amount of recall for orders-of-magnitude faster search than a brute-force scan. The parameters you choose at build time and at query time control exactly where you sit on that speed/recall/memory curve.

This reference covers:

• Two categories of parameters: build-time (set at CREATE VECTOR INDEX) and query-time (set in the query)
• Build-time parameters: hnsw_m, ef_construction, dimensions, distance_metric, and build
• Query-time parameters: the k argument to X_SIMILAR and the limit and ef_search SPARQL options
• Tuning methodology: a four-step process to move from defaults to production-grade accuracy
• Storage estimation: how much space the HNSW graph takes

For an architectural introduction, see Vector index overview.

Overview

The HNSW algorithm builds a multi-layer graph where each node is an embedding vector. Nodes in upper layers are sparse (long-range links) and nodes in lower layers are dense (short-range links). A query starts at the top layer and greedily descends, refining the candidate set at each layer. The number of neighbors per node, how deeply the graph was explored during construction, and how wide the search beam is at query time together determine recall and latency.

Virtuoso exposes these as two distinct parameter categories:

Build-time parameters

Build-time parameters are set in the WITH (...) clause of CREATE VECTOR INDEX. They control the structure and quality of the HNSW graph and cannot be changed without dropping and recreating the index.

CREATE VECTOR INDEX DOCS_VEC
ON DB.DBA.DOCS (content)
USING 'granite-384-local'
WITH (
  dimensions      = 384,
  distance_metric = 'cosine',
  hnsw_m          = 16,
  ef_construction = 200
);

hnsw_m (default 16)

hnsw_m controls the maximum number of neighbors per node per layer in the HNSW graph — 2 × hnsw_m at the bottom layer, hnsw_m above it. It is the single most influential parameter on the graph's connectivity and, consequently, on recall.

• Higher values produce a denser graph with more connections per node. This improves recall because the search has more paths to explore, but each node consumes more space.
• Lower values produce a sparser graph that is cheaper to build and store, but may miss true neighbors during search.

Storage impact: in the packed page format a node stores only the neighbor links it has; in the legacy format each node is a page of its own that reserves room for every layer's links. hnsw_m also sets how wide a vector can be stored inside its node: inline_dim_limit in __VEC_INDEX_PAGE_STATS is 1,742 floats at hnsw_m = 16 and 1,470 at hnsw_m = 32. A wider vector goes to an overflow page of its own, so at 1,536 dimensions hnsw_m = 32 costs a second page per node where 16 does not — see Storage estimation.

Recommended values:

ef_construction (default 200)

ef_construction controls the search depth during index construction — that is, how many candidate nodes are examined when inserting each new node into the graph. A higher value means the builder explores more of the existing graph to find the best neighbors for each insertion, producing a higher-quality graph.

• Higher values produce a better-connected graph with more accurate neighbor links, improving recall. The trade-off is slower build time.
• Lower values build faster but produce a lower-quality graph, which caps the recall achievable even with aggressive query-time tuning.

Recommended values:

Build-time scaling: the graph-building part of a build grows roughly linearly with ef_construction. With a local model, embedding the text usually takes longer than building the graph, so the difference shows mainly on a rebuild, which does not embed. Because the index is built once, the trade-off is usually acceptable for production.

dimensions

dimensions specifies the dimensionality of the embedding vectors stored in the index. It is optional for a model-backed index: omitted, it is taken from the model's output_shape in DB.DBA.ONNX_MODELS.

--  dimensions comes from the model (384 for the bundled granite model)
CREATE VECTOR INDEX "DOCS_VIDX" ON "DB"."DBA"."DOCS" ("content")
  USING 'granite-384-local';

It stays required in two cases:

• reduce = 'truncate' — the stored width is a free choice rather than a property of the model, so there is nothing to infer.
• source_kind = 'vector' — precomputed vectors have no model to ask.

When you do give it:

• It must match the model's output dimension exactly (unless reducing). Mismatched dimensions cause CREATE VECTOR INDEX to fail with VEC19 (SQL) or VEC75 (SPARQL).
• It cannot be changed after index creation. An index is bound to its model for life: to switch, for example, from the bundled granite model to an OpenAI model, drop the index and create it again with the new model.
• Higher dimensions increase the space per node (the vector itself is dim * 4 bytes) and slow down distance computation, because each distance calculation is O(dim).

Common model dimensions:

distance_metric

distance_metric (distance in SPARQL) selects the function used to measure similarity between vectors. It is set at index creation and cannot be changed without recreating the index.

• cosine (default): measures the angle between vectors, ignoring magnitude. Best for text embeddings, which are typically normalized or near-normalized. A distance of 0 means identical direction; 2 means opposite direction.
• l2: Euclidean (straight-line) distance. Sensitive to vector magnitude — two vectors pointing the same direction but with different magnitudes will have a non-zero L2 distance. Use only when magnitude carries signal.
• l1: Manhattan (taxicab) distance. Less sensitive to outliers than L2 because it sums absolute differences rather than squaring them.

For a detailed explanation of each metric, how scores are derived from distances, and guidance on choosing the right one, see Similarity metrics.

build (default 'auto', which means incremental)

build chooses how the initial backfill constructs the graph: the one a SPARQL index's first refresh does, and the one a SQL CREATE VECTOR INDEX does over the rows already in its table.

SPARQL
CREATE VECTOR INDEX <urn:my:idx>
  ON GRAPH <urn:my:graph>
  for predicate <http://schema.org/text>
  USING MODEL 'granite-384-local'
  WITH (dimensions = 384, distance = 'cosine', hnsw_m = 16,
        ef_construction = 200, build = 'bulk')
;

Measured on 2026-09-05: 57,600 FiQA documents embedded with all-MiniLM-L6-v2 (384-d), hnsw_m=16, ef_construction=200, embedding concurrency 8, on a 10-core arm64 machine. Both rows build from the same vectors, so the comparison is between build methods, not models:

That is 2.2x faster and 4.1x smaller, because incremental linking gets more expensive as the graph grows while a bulk build is a single parallel pass.

On the SQL surface the same option goes in the WITH clause:

CREATE VECTOR INDEX DOCS_VEC ON DB.DBA.DOCS (content) USING 'granite-384-local'
  WITH (dimensions = 384, distance_metric = 'cosine', build = 'bulk');

Measured, CREATE VECTOR INDEX over tables of 10,000–40,000 rows with a synthetic 384-dimension test model (no embedding cost, so this is the graph build alone), the stock virtuoso.ini (NumberOfBuffers = 10000), 10-core arm64, 2026-10-10:

An incremental build writes one 8 KB page per node, so 40,000 nodes needed four times the stock buffer pool.

Later refreshes of a bulk index

A refresh embeds only what is new or changed. What it then does with the graph depends on how much changed:

• A small change is linked in. When the changed rows are at most __vec_bulk_delta_pct percent of the graph's live nodes (default 10), the refresh links them into the existing graph one at a time, exactly as an incremental index would, and leaves every other node where it was. Measured on a 1,000,000-row, 64-dimension index (10-core arm64, 2026-09), a 58-row change went from 25.2 s (a whole-graph rebuild) to 3.5 s.
• A large change rebuilds the graph from all the stored embeddings, as the first build did.
• A graph that is empty or unhealthy is always rebuilt, whatever changed — a refresh is how an operator brings an index back up to date, so it will not link rows into a graph that cannot serve searches.

registry_set ('__vec_bulk_delta_pct', '25');   -- link changes of up to 25% of the graph
registry_set ('__vec_bulk_delta_pct', '0');    -- never link: every change rebuilds the graph
registry_set ('__vec_bulk_delta_pct', '');     -- back to the default of 10

Linked rows are searchable at once and are found as reliably as rows in an incremental index. Two things accumulate, though. Each new node takes one page of its own in the legacy format, and each backlink it adds to a node the fast builder packed replaces that node's farthest neighbour, because a packed record has no spare slot. Neither matters for a few percent of the graph; after many small refreshes, a __VEC_INDEX_REBUILD folds everything back into one packed graph.

While any refresh runs — incremental or bulk — the index is in state refreshing, and bif:vector_search on it fails closed with VEC50 rather than returning partial results. For a bulk index that covers the whole first build.

Matryoshka dimension reduction

What it is

Matryoshka Representation Learning (MRL) is a technique where an embedding model is trained so that the first N dimensions of its output vector form a valid, lower-dimensional embedding on their own. The name comes from the Russian nesting doll — each prefix of the vector is a "smaller doll" that still captures semantic meaning, just at a coarser resolution.

Models that support MRL include:

The reduce parameter

The reduce option controls whether vectors are truncated to a lower dimension before they go into the HNSW graph.

When reduce = 'truncate':

1. The model produces vectors at its native dimension (e.g. 1536 for OpenAI text-embedding-3-small)
2. Only the first dimensions elements are kept (e.g. 256)
3. The truncated vector is L2-renormalized (divided by its magnitude) so that cosine similarity remains meaningful
4. The reduced vector goes into the HNSW graph — less space, faster search. The index's embedding table keeps the model's full-width vector.

When to use it

Use Matryoshka reduction when you want to:

• Reduce graph size: a 256-dim vector is a sixth of a 1536-dim one, and at that width several nodes share a page — see the measurements below
• Speed up search: distance computation is proportional to dimensionality
• Trade quality for cost: lower dimensions = slightly lower recall, but significantly faster search and less space

Example: OpenAI text-embedding-3-small reduced to 256 dimensions

-- Register the OpenAI model (native 1536 dimensions):
DB.DBA.ONNX_API_KEY_SET('ONNX_API_KEY_OPENAI', '<your-key>');
DB.DBA.ONNX_REGISTER_HTTP_EMBED_MODEL(
  'openai-small', 'openai',
  'text-embedding-3-small', 1536,
  NULL, 'ONNX_API_KEY_OPENAI', 30);

-- Create an index with Matryoshka reduction to 256 dimensions:
CREATE VECTOR INDEX DOCS_VEC ON DB.DBA.DOCS (content)
USING 'openai-small'
WITH (
  dimensions      = 256,    -- reduced dimension (not 1536)
  reduce          = 'truncate',
  distance_metric = 'cosine',
  hnsw_m          = 32,
  ef_construction = 400
);

This stores 256-element vectors in the graph instead of 1536-element ones — a sixth of the payload — while retaining most of the search quality. The server embeds each text at 1536 dimensions using OpenAI, then truncates to 256 and renormalizes before it goes into the HNSW graph. Query text follows the same pipeline.

Validation rules

The following rules are enforced at CREATE VECTOR INDEX time. The SQL and SPARQL surfaces share the same native-layer checks (VEC13, VEC19, VEC64); the SPARQL surface adds its own catalog-level checks (VEC72–VEC75) that fire before the native DDL is issued.

Memory comparison

SPARQL surface

The reduce option is available on both the SQL and SPARQL CREATE VECTOR INDEX surfaces. The SPARQL DDL forwards the option to the native index layer, which performs the truncation and L2-renormalization on insert and query.

-- Register the OpenAI model (native 1536 dimensions):
DB.DBA.ONNX_API_KEY_SET('ONNX_API_KEY_OPENAI', '<your-key>');
DB.DBA.ONNX_REGISTER_HTTP_EMBED_MODEL(
  'openai-small', 'openai',
  'text-embedding-3-small', 1536,
  NULL, 'ONNX_API_KEY_OPENAI', 30);

-- Create an RDF vector index with Matryoshka reduction to 256 dimensions:
SPARQL DEFINE input:storage ""
CREATE VECTOR INDEX <urn:docs:reduced-idx>
  ON GRAPH <urn:docs:g>
  for predicate <urn:doc:text>
  USING MODEL 'openai-small'
  WITH (
    dimensions      = 256,    -- reduced dimension (not 1536)
    reduce          = 'truncate',
    distance        = 'cosine',
    hnsw_m          = 32,
    ef_construction = 400
  )
;

The catalog records both the stored (reduced) dimension in SVI_DIMENSIONS and the model's native output dimension in SVI_MODEL_DIMENSIONS (here 256 and 1536). Querying with bif:vector_search is unchanged — the query text is embedded at the native dimension, then truncated and renormalized to match the stored vectors.

Query-time parameters

Query-time parameters are set in the query itself — not at index creation. They control how deeply the HNSW search explores the graph at query time. Because they require no index rebuild, they are the cheapest way to improve recall and should be tuned before considering build-time changes.

k parameter (X_SIMILAR 3rd argument)

The k parameter is the third argument to X_SIMILAR in SQL queries. It sets how many candidates the HNSW search returns, nearest first, and the search beam width that finds them. The query's other conditions — the X_SIMILAR threshold included — are then applied to those candidates.

• Default: the query's TOP n. A WHERE threshold with neither k nor TOP is not answered by the HNSW index at all: every row is scored exactly, and the result is complete.
• Higher k = better recall = slower query (the search explores more of the graph and re-ranks more candidates).
• Lower k = faster query = potentially lower recall, and at most k rows: on a six-row table where every row scores above 0.7, X_SIMILAR (content, 'reset password', 2) > 0.7 matches 2 rows.

The same holds for ORDER BY VECTOR_DISTANCE (...): it uses the index only with TOP n, and n is its k.

Recommended: set k to 5–10x your actual TOP N for good recall. For example, if you want TOP 10 results, use k = 100.

-- k=100 retrieves 100 candidates from HNSW, then TOP 10 picks the best:
SELECT TOP 10 id, content,
       X_SIMILAR(content, 'reset password', 100) AS score
FROM DB.DBA.DOCS
WHERE X_SIMILAR(content, 'reset password', 100) > 0.0
ORDER BY X_SIMILAR(content, 'reset password', 100) DESC;

limit and ef_search (SPARQL options)

bif:vector_search separates the two things SQL's k sets: limit is the number of results, and ef_search is the HNSW search beam width that finds them. Both go in the option (...) clause of the magic predicate.

• limit — default 10, from 1 to 10000.
• ef_search — default 100; it must be at least limit and at most 100000.
• Higher ef_search = better recall = slower query.
• Lower ef_search = faster query = potentially lower recall.

Recommended: 100 for most use cases; 200–500 for high accuracy.

SPARQL DEFINE input:storage ""
SELECT ?doc ?score ?distance
WHERE {
  ?doc bif:vector_search "reset customer password"
  option (
    INDEX <urn:docs:idx>,
    score ?score,
    distance ?distance,
    LIMIT 10,
    ef_search 200
  ) .
}
ORDER BY DESC(?score)
;

VectorANNCostBias (server setting)

Whether a SQL query lets the HNSW index lead the scan is a cost-based choice of the optimizer. It estimates a leading ANN search at ef_search × log2(graph nodes) × the index's own average search time, taken from counters the index keeps (with no searches yet, 0.01 ms per unit of ef_search), and multiplies that by VectorANNCostBias:

[Parameters]
VectorANNCostBias = 1.0

The default is 1.0; a value of 0 or below, or one that does not parse, is taken as 1.0. Below 1 makes the ANN access path look cheaper, so the optimizer chooses it more often; above 1, less often. Another selective predicate on the table can still keep a query in filter/rerank mode. The setting is read when the server starts.

Tuning methodology

Tuning the vector index is a measured process: start with defaults, quantify recall, and increase parameters in order of cost — query-time first, build-time only when necessary. Follow these four steps.

Step 1: Start with defaults

Begin with the default build-time and query-time parameters. This gets you a working index quickly and establishes a recall baseline.

• Build-time: hnsw_m = 16, ef_construction = 200
• Query-time: k = your TOP n (SQL), or limit 10 and ef_search = 100 (SPARQL)

CREATE VECTOR INDEX DOCS_VEC
ON DB.DBA.DOCS (content)
USING 'granite-384-local'
WITH (
  dimensions      = 384,
  distance_metric = 'cosine',
  hnsw_m          = 16,
  ef_construction = 200
);

Step 2: Measure recall

Before tuning, quantify where you stand. Use the built-in __VEC_INDEX_VALIDATE function to measure ANN recall against an exact brute-force search:

SELECT obj2json (__VEC_INDEX_VALIDATE('DOCS_VEC'));

This returns a vector of name/value pairs. Its recall_at_10 is the recall score, between 0 and 1, where 1.0 means the ANN search returned exactly the same results as a brute-force scan; the others say what was tested and whether the graph agrees with the stored embeddings. On a six-row table:

["queries_tested",6,"recall_at_10",1,"distance_metric","cosine","dimension",384,
 "consistent",1,"consistency_detail","graph agrees with the stored embeddings",
 "graph_epoch",6,"data_epoch",6,"active_nodes",6,"embedding_rows",6]

Record this baseline — it tells you how much room for improvement you have. To read one value, use get_keyword ('recall_at_10', __VEC_INDEX_VALIDATE ('DOCS_VEC')).

Published recall baseline

For a sense of what "good" looks like, here are recall@10 figures from the engine's ANN-quality test in the test suite, which compares each search with a brute-force scan of the same vectors: 5,000 clustered 384-dimensional vectors (200 clusters), hnsw_m = 16, ef_construction = 64, ef_search = 128, k = 10, 100 queries. Measured on this build, 2026-10-20:

Takeaways: at these parameters, all three full-precision metrics land at or near perfect recall on well-clustered data. Build parameters set the ceiling — the starved graph in the last row cannot be rescued at query time. Dimension truncation trades recall for space — halving the dimensions here cost roughly a third of recall, so benchmark reduce = 'truncate' on your own data before adopting it. Deleted rows are never returned, but the graph is not repaired around them: deleting a fifth of the rows cost a fifth of the recall, and a wider ef_search does not win it back. __VEC_INDEX_REBUILD builds a fresh graph from the remaining embeddings (see Durability and recovery).

Step 3: Increase query-time parameters first

If recall is below your target, increase the query-time parameters. This requires no index rebuild — you simply change the value in your query. This is the cheapest way to improve accuracy.

For SQL: increase the k argument to X_SIMILAR.

-- Increase k from 10 to 100 — no rebuild needed:
SELECT TOP 10 id, content,
       X_SIMILAR(content, 'reset password', 100) AS score
FROM DB.DBA.DOCS
ORDER BY VECTOR_DISTANCE(content, 'reset password');

For SPARQL: increase the ef_search option.

SPARQL DEFINE input:storage ""
SELECT ?doc ?score WHERE {
  ?doc bif:vector_search "reset customer password"
  option (INDEX <urn:docs:idx>, score ?score, LIMIT 10, ef_search 200) .
}
ORDER BY DESC(?score)
;

After each increase, re-run __VEC_INDEX_VALIDATE and check whether recall has improved to your target. Query-time tuning typically yields the largest recall gains for the least effort.

Step 4: Rebuild with higher build-time parameters

If query-time tuning alone does not reach your recall target, the graph structure itself is the limiting factor. Drop and recreate the index with higher hnsw_m and ef_construction values.

-- Drop the existing index:
DROP INDEX DOCS_VEC;

-- Recreate with production-grade parameters:
CREATE VECTOR INDEX DOCS_VEC
ON DB.DBA.DOCS (content)
USING 'granite-384-local'
WITH (
  dimensions      = 384,
  distance_metric = 'cosine',
  hnsw_m          = 32,
  ef_construction = 400
);

After recreating, re-run __VEC_INDEX_VALIDATE to confirm the recall improvement. You may then be able to lower your query-time parameters (k or ef_search) to recover latency, since the higher-quality graph needs a narrower beam to achieve the same recall.

Storage estimation

Before building a production index, estimate how much space its graph will take so you can size your instance accordingly. A graph node holds the vector, its neighbor links, and a little metadata; how much disk that takes depends on the page format and on whether the vector fits inside its node.

Per-node size

• Legacy format (an incremental build, or nodes linked in later): one 8 KB page per node, plus a second, overflow page when the vector is wider than inline_dim_limit (1,742 floats at hnsw_m = 16, 1,470 at hnsw_m = 32).
• Packed format (build = 'bulk', or after a fast rebuild): node records share pages, up to eight to a page, and each stores only the links it has. A vector wider than inline_dim_limit still takes an overflow page of its own.

Measured with 2,000 vectors per index, 2026-10-20 (physical_node_pages and overflow_pages from __VEC_INDEX_PAGE_STATS):

The packed 384-dim figure holds at scale: 57,600 FiQA vectors took 14,064 pages after a bulk build, 4.1 nodes per page.

Worked example: 1536-dim, hnsw_m = 32

For 100,000 documents embedded with OpenAI text-embedding-3-small, with hnsw_m = 32:

packed:  100,000 nodes * ~9 KB/node  ≈ 0.9 GB for the HNSW graph
legacy:  100,000 nodes * 16 KB/node  ≈ 1.6 GB

At hnsw_m = 16 both formats come to about 0.8 GB, because a 1536-dim vector then fits inside its node; reduced to 256 dimensions, the packed graph is about 0.14 GB.

Performance characteristics

Understanding the algorithmic complexity of HNSW helps you reason about how the parameters scale with your data.

Practical expectations:

• Graph build time grows linearly with ef_construction and slightly super-linearly with dataset size; embedding the text often costs more than building the graph.
• Query time is sublinear in dataset size — searching 10x more data does not take 10x longer. It grows with ef_search (or k), so widening the beam costs latency.
• Recall of 95% and above is the usual target for HNSW with hnsw_m = 32, ef_construction = 400, and ef_search = 100 (or k = 100); higher targets call for larger values of all three. Measure on your own data with __VEC_INDEX_VALIDATE.

Parameter reference table

The following table summarizes all parameters, where they are set, their defaults, valid ranges, and primary effect.

Accepted aliases

The SQL WITH clause accepts short aliases for each parameter. The SPARQL DDL takes only the full names (plus build_method and rebuild_method), and fails with VEC13 on any other.

Next steps

• Similarity metrics — Detailed explanation of cosine, L2, and L1 distance functions, score derivation, and how to choose the right metric for your data
• SQL vector index how-to — Complete guide for creating, querying, and maintaining SQL vector indexes, including the k parameter and explicit-vector patterns
• SPARQL vector index how-to — Complete guide for RDF vector indexes with bif:vector_search, including the ef_search option and graph ACL security
• Maintenance — Queue-based index updates, workers, and operational guidance for keeping your index current
• Naming an index — The label and comment options, the <urn:vvec:indexes> RDF view they are published in, and who may set and read them

Related content

Reference:

• Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs — Malkov & Yashunin, the foundational HNSW paper
• hnswlib on GitHub — Reference implementation of HNSW and background on the algorithm
• Vector index overview — Architecture, HNSW parameters, and embedding model options

PreviousEmbedding models for the Virtuoso vector index NextSimilarity metrics for the Virtuoso vector index