Vector index overview for Virtuoso

Virtuoso Open Source includes a native vector index, backed by HNSW (Hierarchical Navigable Small World), for semantic similarity search over text. Unlike external vector databases, which require you to manage embeddings separately, Virtuoso's server handles the full pipeline: embedding generation, vector storage, approximate nearest-neighbor search, and index maintenance—all integrated with the SQL and SPARQL query engines you already use.

This overview covers:

• What is semantic search: Why vector search differs from keyword search
• Architecture: How embeddings, the HNSW graph, and query surfaces fit together
• Query surfaces: SQL (X_SIMILAR, VECTOR_DISTANCE), SPARQL (bif:vector_search), and search over RDF literals (knnSimilar)
• Embedding models: Local ONNX models and remote HTTP providers
• Automatic maintenance: How inserts, updates, and deletes keep the index current
• Glossary: Key terms and concepts

What is semantic search

Traditional keyword search matches documents by finding exact or stemmed word overlaps. It fails when the query and the relevant document use different vocabulary — "how to reset my password" won't match a document titled "credential recovery procedure."

Semantic search solves this by converting text into embedding vectors — high-dimensional float arrays where texts with similar meaning are close together in vector space. Instead of matching words, it matches meaning.

Virtuoso's vector index makes this work end-to-end inside the database:

1. You store text in a table column (SQL) or as RDF literals (SPARQL)
2. The server converts that text into embedding vectors using a bound model
3. You query with plain text — the server embeds your query and finds the nearest neighbors in the vector space
4. Results are ranked by semantic similarity, not keyword overlap

How it works

Virtuoso's vector index follows a text-in, text-out design. You never handle raw vectors for normal queries — you pass text, and the server embeds it using the index's bound model.

The search pipeline

Query text ──→ Embedding model ──→ Query vector
                                        │
                                        ▼
Data text  ──→ Embedding model ──→ Data vectors ──→ HNSW graph
                                        │                   │
                                        │                   ▼
                                        │           Nearest neighbor search
                                        │                   │
                                        ▼                   ▼
                                    Hidden table ←── Ranked results ──→ SQL/SPARQL output

1. You create a vector index on a text column (SQL) or an RDF graph/predicate pair (SPARQL), binding it to an embedding model.
2. The server embeds your data — each row or RDF resource's text is converted to a float vector and stored in an HNSW graph.
3. You query with text — the server embeds your query text with the same model, searches the HNSW graph for nearest neighbors, and returns ranked results.

Key components

Architecture layers

The vector index is built in three layers:

1. Plugin layer — The vonnx plugin (vonnx.so) provides ONNX Runtime integration, running each loaded model in helper processes on the server host. It exposes BIFs like ONNX_EMBED_TEXT(handle, text) and ONNX_LOAD_MODEL(path, options). HTTP providers are called from SQL procedures (DB.DBA.ONNX_EMBED_TEXT_FOR_MODEL and friends) that share the same model registry.
2. SQL layer — The vector index is implemented in the database engine as native database pages (a dedicated page type for HNSW graph nodes). The SQL compiler rewrites X_SIMILAR and VECTOR_DISTANCE calls to use the HNSW index when one exists on the referenced column. A maintenance queue (VEC_SQL_QUEUE) handles deferred embedding updates.
3. SPARQL layer — RDF-specific catalog tables (SPARQL_VEC_INDEX, SPARQL_VEC_INDEX_TRIGGER), SPARQL DDL (CREATE/REFRESH/DROP VECTOR INDEX), the bif:vector_search magic predicate, and a separate maintenance queue (SPARQL_VEC_QUEUE) with async triggers on RDF quad inserts/updates/deletes. For general (KEY/EMBEDDING/WHERE) selectors, the parser extracts (graph, predicate) dependency pairs at create time so that only relevant triple changes enqueue the changed subject.

An RDF literal index combines the first two: it is an ordinary SQL vector index on DB.DBA.RDF_OBJ, the table that holds RDF literal values, and is searched with knnSimilar as a condition on the object of any triple pattern — see Vector search over RDF literals.

Supported configurations

The vector index is supported on single-server Virtuoso Open Source only. It has not been validated on a clustered (multi-node) instance, and cluster deployment is not supported.

Within a single server:

• Concurrent writers on one index are serialized by a per-index writer lock, so parallel inserts/updates/deletes to the same index are safe. Writers on different indexes still run in parallel, and readers (searches) are never blocked by writers. See Index maintenance for the full contract.
• Durability is crash-safe: each index tracks a durability epoch, and an index found inconsistent with its stored embeddings after a crash refuses to serve searches until it is rebuilt. See Durability and recovery.

Query surfaces

SQL vector index

For relational tables with a text column. You create an index with CREATE VECTOR INDEX, insert data, and query with X_SIMILAR or VECTOR_DISTANCE.

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

SELECT TOP 10 id, content,
       X_SIMILAR(content, 'reset password') AS score,
       VECTOR_DISTANCE(content, 'reset password') AS distance
FROM DB.DBA.DOCS
ORDER BY VECTOR_DISTANCE(content, 'reset password');

Key concepts:

• X_SIMILAR returns a similarity score in [0, 1] (higher = more similar)
• VECTOR_DISTANCE returns a raw distance (lower = more similar)
• When in WHERE or ORDER BY, the compiler rewrites these to use the HNSW index
• The query text is embedded with the index's bound model when the query runs

For the full SQL guide, see SQL vector index how-to.

SPARQL vector index

For RDF data indexed by graph and predicate, or by any graph pattern. You create an index with SPARQL DDL and query with the bif:vector_search magic predicate.

SPARQL DEFINE input:storage ""
CREATE VECTOR INDEX <urn:docs:idx>
  ON GRAPH <urn:docs:g>
  for predicate <urn:doc:text>
  USING MODEL 'granite-384-local'
  WITH (dimensions = 384, distance = 'cosine')
;

-- Embed the triples the graph already holds; until this runs, the index is empty
SPARQL DEFINE input:storage ""
refresh VECTOR INDEX <urn:docs:idx>
;

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

Key concepts:

• bif:vector_search is a SPARQL magic predicate, not a regular triple match
• The query lowers to VEC_INDEX_SEARCH_ROWS in the generated SQL
• Graph permission checks (ACLs) filter results the user can't read
• Supports shorthand selectors (graph + predicate) and general selectors (graph pattern)
• One query can search several indexes: option (index (<a>, <b>)) or option (index *)

For the full SPARQL guide, see SPARQL vector index how-to.

Search over RDF literals (knnSimilar)

For semantic search over literal values wherever they occur, without choosing a graph or predicate in advance. One call indexes the string literals of DB.DBA.RDF_OBJ; knnSimilar then constrains the object of a triple pattern, much as bif:contains does for free-text search:

DB.DBA.RDF_OBJ_VEC_INDEX_CREATE ('urn:faq:literals', 'granite-384-local');

SPARQL
SELECT ?s ?sim
WHERE {
  ?s ?p ?o .
  ?o bif:knnSimilar "how do I back up the database" option (LIMIT 5, score ?sim) .
}
ORDER BY DESC (?sim)
;

For the full guide, see Vector search over RDF literals.

When to use which surface

Embedding models

Virtuoso supports two categories of embedding models, both managed through the DB.DBA.ONNX_MODELS catalog table.

Local ONNX models

The bundled granite-384-local model (IBM granite-embedding-30m-english, 384 dimensions) is auto-provisioned at startup. It runs on the host through the vonnx plugin and ONNX Runtime, in helper processes the server starts — no network calls, no API keys, no per-query cost.

Remote HTTP embedding providers

You can register external embedding APIs through a unified OpenAI-compatible interface:

For the full model guide, see Embedding models.

HNSW and similarity metrics

The vector index uses the HNSW (Hierarchical Navigable Small World) algorithm for approximate nearest neighbor search. HNSW builds a multi-layer graph where each node is a vector, and edges connect similar vectors. Search starts from the top layer (sparse, fast traversal) and descends to the bottom layer (dense, accurate matching).

Build-time parameters

For accuracy-focused builds with high-dimensional models (e.g. 1536-dim OpenAI embeddings), use hnsw_m = 32 and ef_construction = 400. For memory-constrained deployments, use reduce = 'truncate' to reduce vector dimensions (e.g. 1536 → 256) with MRL-compatible models.

Query-time parameters

Distance metrics

For the full parameter guide, see Index parameters. For metric details, see Similarity metrics.

Automatic maintenance

After index creation, base-table writes keep the index current without running embedding generation in the write transaction:

• INSERT / UPDATE / DELETE triggers enqueue work into a transactional queue
• Hash-skip detects unchanged text and skips re-embedding (via SOURCE_HASH)
• An explicit drain call, or a scheduled worker for SQL indexes, processes the queue and updates the HNSW graph

New rows become searchable after the next queue drain. A SQL CREATE VECTOR INDEX backfills existing rows inline, so create-then-search works immediately; a SPARQL index is populated by REFRESH VECTOR INDEX.

For the full maintenance guide, see Index maintenance.

Prerequisites

• Virtuoso Open Source built with --enable-onnxruntime — see Build Virtuoso with ONNX support
• The vonnx plugin loaded in virtuoso.ini
• An embedding model registered in DB.DBA.ONNX_MODELS (auto-provisioned for the bundled granite-384-local model)

Glossary

Documentation map

Next steps

• Quickstart — Get a vector index running in 5 minutes
• SQL vector index how-to — Complete guide for SQL vector indexes
• SPARQL vector index how-to — Complete guide for SPARQL vector indexes
• FAQ semantic search tutorial — End-to-end example with real RDF data

Related content

Reference:

• Embedding models — Local ONNX and remote HTTP provider guide
• Index parameters — HNSW tuning guide
• Similarity metrics — Cosine, L2, L1 explained
• API reference — Complete function reference
• Troubleshooting — Diagnostics and fixes

External:

• ONNX Runtime — Microsoft ONNX Runtime project
• granite-embedding-30m-english — Bundled embedding model
• HNSW algorithm — Hierarchical Navigable Small World graphs

NextQuickstart: Vector index for Virtuoso