---
title: "Quickstart - Vector Index for Virtuoso"
description: "Get started with Virtuoso's native vector index in 5 minutes — create a table, build an HNSW-backed index with the bundled granite embedding model, and run your first semantic search."
url: urn:osdi:this
dateModified: 2026-10-30T15:45:34Z
language: en
---
One page of the Vector Index documentation, MERGED by build_vector_index_docs.py from this template and the markdown in fixture/vector-index/. Do not edit the generated file: change this template or the generator and rebuild. It opens on the documentation header (dxshell.py), not on the site hero.

[Home](urn:osdi:site)/[Virtuoso](urn:osdi:sitevirtuoso/)/[Vector index](urn:osdi:sitevirtuoso/docs/vector-index/)/Quickstart: Vector index for Virtuoso

# Quickstart: Vector index for Virtuoso

Get started with Virtuoso's native vector index in 5 minutes — create a table, build an HNSW-backed index with the bundled granite embedding model, and run your first semantic search.

Start  [Overview](urn:osdi:sitevirtuoso/docs/vector-index/) Quickstart [Tutorial: FAQ semantic search](urn:osdi:sitevirtuoso/docs/vector-index/tutorial-faq-semantic-search/)  Build  [SQL vector index how-to](urn:osdi:sitevirtuoso/docs/vector-index/howto-sql-vector-index/) [SPARQL vector index how-to](urn:osdi:sitevirtuoso/docs/vector-index/howto-sparql-vector-index/) [Search RDF literals (knnSimilar)](urn:osdi:sitevirtuoso/docs/vector-index/knn-similar/)  Configure  [Embedding models](urn:osdi:sitevirtuoso/docs/vector-index/embedding-models/) [Index parameters](urn:osdi:sitevirtuoso/docs/vector-index/index-parameters/) [Similarity metrics](urn:osdi:sitevirtuoso/docs/vector-index/similarity-metrics/)  Operate  [VVec Console (web UI)](urn:osdi:sitevirtuoso/docs/vector-index/vvec-console/) [Troubleshooting](urn:osdi:sitevirtuoso/docs/vector-index/troubleshooting/)  Reference  [API reference](urn:osdi:sitevirtuoso/docs/vector-index/api-reference/)

In this quickstart, you create a table, build a vector index backed by the bundled granite embedding model, and run your first semantic similarity search — all in under five minutes.

## Prerequisites

Before you begin, make sure you have:

- **Virtuoso Open Source** (single-server) built with the ONNX plugin (`--enable-onnxruntime`)
- **The `vonnx` plugin** loaded in your `virtuoso.ini` (the `virtuoso.ini` that `make install` writes already loads it)

Note

The bundled `granite-384-local` model (IBM granite-embedding-30m-english, 384 dimensions) is auto-provisioned at startup. It runs on your server: no external API key or network access is needed to use it.

Important

The vector index is supported on **single-server** Virtuoso Open Source only. It has not been validated on a clustered (multi-node) instance. See [Supported configurations](urn:osdi:sitevirtuoso/docs/vector-index/#supported-configurations).

If you need help building Virtuoso with ONNX support, see the [SQL vector index how-to](urn:osdi:sitevirtuoso/docs/vector-index/howto-sql-vector-index/) for full build instructions.

---

## Step 1: Verify the bundled model loaded

After starting Virtuoso, confirm the embedding model is registered and its handle is non-null (a null handle means the ONNX model failed to load):

SQL

```
SELECT model_name, handle
FROM DB.DBA.ONNX_MODELS;
```

You should see output similar to:

| model_name | handle |
| --- | --- |
| granite-384-local | 1 |

Tip

If there is no row, or `handle` is null, check that the `vonnx` plugin loaded: the Virtuoso log should show `SUCCESS plugin N: loaded from .../vonnx.so` and `ONNX bootstrap refreshed 1 model(s)`. A line starting `ONNX bootstrap disabled granite-384-local` names the model and helper paths it could not find — fix `[ONNX] ModelRoot` and `HelperPath` in `virtuoso.ini`, then restart the server.

---

## Step 2: Create a table and insert sample data

Create a table with a single-column integer primary key and a text column, then insert a few sample rows:

SQL

```
CREATE TABLE DB.DBA.DOCS (
  id      INTEGER NOT NULL PRIMARY KEY,
  content LONG VARCHAR
);

INSERT INTO DB.DBA.DOCS VALUES (1, 'How do I Install Virtuoso on Linux?');
INSERT INTO DB.DBA.DOCS VALUES (2, 'How do I install virtuoso on Windows?');
INSERT INTO DB.DBA.DOCS VALUES (3, 'How do I install virtuoso on macOS?');
```

Important

The source table must have a **single-column integer primary key**, and the text column must be a character column (`VARCHAR`, `NVARCHAR`, `LONG VARCHAR` or `LONG NVARCHAR`). These are hard requirements for the vector index.

---

## Step 3: Create a vector index

Create the vector index, binding it to the bundled model:

SQL

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

When this statement returns, the index is built and searchable — existing rows are backfilled inline, so there is no separate loading step.

Note

`dimensions` must match the model's output dimension exactly. The bundled `granite-384-local` model produces 384-dimensional vectors.

---

## Step 4: Search with X_SIMILAR and VECTOR_DISTANCE

Now run your first semantic search. Pass the query as plain text — the server embeds it with the index's bound model and searches the HNSW graph for the closest matches:

SQL

```
SELECT TOP 10 id, content,
       VECTOR_DISTANCE(content, 'how to install') AS distance,
       X_SIMILAR(content, 'how to install')       AS score
FROM DB.DBA.DOCS
ORDER BY VECTOR_DISTANCE(content, 'how to install');
```

Example output:

| id | content | distance | score |
| --- | --- | --- | --- |
| 1 | How do I Install Virtuoso on Linux? | 0.229 | 0.886 |
| 2 | How do I install virtuoso on Windows? | 0.250 | 0.875 |
| 3 | How do I install virtuoso on macOS? | 0.283 | 0.858 |

All three rows are semantically related to the query, so they score well above the ~0.73 that unrelated text gets with this model (see below).

### What about unrelated queries?

Try a query that has nothing to do with the indexed content:

SQL

```
SELECT TOP 10 id, content,
       VECTOR_DISTANCE(content, 'is the sun yellow') AS distance,
       X_SIMILAR(content, 'is the sun yellow')       AS score
FROM DB.DBA.DOCS
ORDER BY VECTOR_DISTANCE(content, 'is the sun yellow');
```

Example output:

| id | content | distance | score |
| --- | --- | --- | --- |
| 2 | How do I install virtuoso on Windows? | 0.530 | 0.735 |
| 1 | How do I Install Virtuoso on Linux? | 0.530 | 0.735 |
| 3 | How do I install virtuoso on macOS? | 0.537 | 0.731 |

Unrelated content does not land at a cosine distance of 1.0 with this model: even text with nothing in common sits at a distance of about 0.53 — a cosine similarity of about 0.47, not 0 — which `X_SIMILAR` reports as a score of about 0.73. Judge relevance by the *gap* between related and unrelated text (here 0.86–0.89 against ~0.73) rather than against an absolute 1.0, and set a threshold from your own corpus, e.g. `WHERE X_SIMILAR(content, '...') > 0.8`.

Note

Absolute distances depend on the model. These figures are from the bundled `granite-384-local` model, whose `pooled_output` is the CLS token, L2-normalised. Another model puts the same texts on a different scale, so compare scores within one index, never across models.

Tip

**`VECTOR_DISTANCE`** returns the raw distance (lower = closer), while **`X_SIMILAR`** returns similarity in `[0, 1]` (higher = closer). For cosine distance, `score = 1 - distance / 2`.

---

## Clean up

When you are done, remove the index and table:

SQL

```
DROP INDEX DOCS_VEC;
DROP TABLE DB.DBA.DOCS;
```

---

## Next steps

- **[SQL vector index how-to](urn:osdi:sitevirtuoso/docs/vector-index/howto-sql-vector-index/)** — Complete guide for creating, querying, and maintaining SQL vector indexes
- **[SPARQL vector index how-to](urn:osdi:sitevirtuoso/docs/vector-index/howto-sparql-vector-index/)** — Use vector indexes with RDF data and SPARQL queries
- **[Vector index overview](urn:osdi:sitevirtuoso/docs/vector-index/)** — Architecture, HNSW parameters, and embedding model options

## Related content

**Reference:**

- [granite-embedding-30m-english](https://huggingface.co/ibm-granite/granite-embedding-30m-english) — The bundled embedding model
- [HNSW algorithm](https://github.com/nmslib/hnswlib) — Background on Hierarchical Navigable Small World graphs

[PreviousVector index overview for Virtuoso](urn:osdi:sitevirtuoso/docs/vector-index/) [NextTutorial: Semantic search over OpenLink FAQs with a SPARQL vector index](urn:osdi:sitevirtuoso/docs/vector-index/tutorial-faq-semantic-search/)

On this page

1. [Prerequisites](#prerequisites)
2. [Step 1: Verify the bundled model loaded](#step-1-verify-the-bundled-model-loaded)
3. [Step 2: Create a table and insert sample data](#step-2-create-a-table-and-insert-sample-data)
4. [Step 3: Create a vector index](#step-3-create-a-vector-index)
5. [Step 4: Search with X_SIMILAR and VECTOR_DISTANCE](#step-4-search-with-x_similar-and-vector_distance)
6. [Clean up](#clean-up)
7. [Next steps](#next-steps)
8. [Related content](#related-content)