DiskANN¶

DiskANN is an approximate nearest-neighbor (ANN) index that stores its graph on disk. AkasicDB provides DiskANN only in Enterprise Edition; Community Edition does not support it. DiskANN supports squared Euclidean distance (L2) over vector columns and requires a Linux build with DiskANN support.

Index Structure¶

A DiskANN index consists of a static index, a primary index, and a Consistency Overlay.

Component	Role
Static index	Stores rows that are visible when `CREATE INDEX` or `REINDEX` runs. Search reads the graph from disk.
Primary index	Stores vectors added after the static index was built. Vamana is the default.
Consistency Overlay	Excludes dead static entries identified by `VACUUM` from search results.

Search merges candidates from the static and primary indexes, then checks PostgreSQL multiversion concurrency control (MVCC) visibility. Committed INSERT, UPDATE, and DELETE changes are reflected in search results without REINDEX.

Create an Index¶

CREATE INDEX items_embedding_diskann_idx
  ON items
  USING vectoron (embedding vector_l2_ops)
  WITH (options = $$
    [indexing.diskann]
    max_degree = 32
    l_build = 100
    build_memory_mb = 4096
    search_pq_chunks = 3
    build_threads = 4
    cache_nodes = 0
    search_io_limit = 128
  $$);

SELECT fence_vector_index('items_embedding_diskann_idx'::regclass);

This example assumes that items.embedding is a vector(3) tutorial column. search_pq_chunks cannot exceed the vector dimensions, so the example sets it to 3. Higher-dimensional workloads can use the default value of 16.

Option	Default	Description
`indexing.diskann.max_degree`	`32`	Maximum number of edges retained by a static graph node.
`indexing.diskann.l_build`	`100`	Candidate search width used to build the static graph. It must be at least `max_degree`.
`indexing.diskann.build_memory_mb`	`4096`	Memory budget for building the static index.
`indexing.diskann.search_pq_chunks`	`16`	Product quantization (PQ) chunks used for static search. It cannot exceed the vector dimensions.
`indexing.diskann.build_threads`	`4`	Number of static index build threads.
`indexing.diskann.cache_nodes`	`0`	Number of static graph nodes kept in the process. `0` disables the internal cache.
`indexing.diskann.search_io_limit`	`128`	Maximum number of storage I/O requests allowed for one search.

cache_nodes is a node count and cannot exceed the number of rows in the static index. It is not a percentage of dataset rows.

Select the Primary Index¶

The primary index can use Flat, HNSW, or Vamana. Vamana is the default.

CREATE INDEX items_embedding_diskann_hnsw_idx
  ON items
  USING vectoron (embedding vector_l2_ops)
  WITH (options = $$
    [indexing.diskann]

    [indexing.diskann.primary.hnsw]
    m = 12
    ef_construction = 300
  $$);

Quantization cannot be configured for a DiskANN primary index. search_pq_chunks applies only to the static index and is not a primary-index quantization option.

Search Settings¶

GUC	Default	Description
`vectoron.diskann_result_size`	`100`	Result count `K` requested by static search.
`vectoron.diskann_l_search`	`100`	Static graph search list size `L`.
`vectoron.diskann_beam_width`	`16`	Storage I/O beam width.
`vectoron.diskann_overlay_max_expansion`	`2`	Maximum number of static search expansions used to replace candidates removed by tombstones.

K, L, and beam width accept values from 1 to 65,535. K cannot exceed L and should be at least the query LIMIT. vectoron.diskann_overlay_max_expansion accepts values from 0 to 2. A value of 0 disables additional expansion.

BEGIN;
SET LOCAL vectoron.diskann_result_size = 10;
SET LOCAL vectoron.diskann_l_search = 100;
SET LOCAL vectoron.diskann_beam_width = 16;

SELECT id
  FROM items
 ORDER BY embedding <-> '[0.1,0.2,0.3]'::vector
 LIMIT 10;
COMMIT;

DML and REINDEX¶

Operation	Behavior
`INSERT`	Adds the new vector to the primary index.
`UPDATE`	Adds the new row version to the primary index. MVCC visibility excludes the previous version.
`DELETE`	Excludes the deleted row through MVCC visibility.
`VACUUM`	Records dead static entries as tombstones.
`REINDEX INDEX`	Builds a new static generation from visible rows and merges primary rows and tombstones.

Inspect DiskANN state through vectoron_index_stat.

SELECT
  indexname,
  idx_static_rows,
  idx_tombstones,
  idx_reindex_recommended
FROM vectoron_index_stat
WHERE indexname = 'items_embedding_diskann_idx';

idx_reindex_recommended is true when either condition is met:

Primary rows are at least 75% of live indexed rows.
Static tombstones are at least 50% of static rows.

Live indexed rows are the sum of primary rows and static rows that are not tombstones.

AkasicDB does not monitor idx_reindex_recommended or run REINDEX automatically. A user interface or monitoring system must query vectoron_index_stat periodically and notify the operator when an index reports true.

SELECT
  indexname,
  idx_static_rows,
  idx_tombstones,
  idx_reindex_recommended
FROM vectoron_index_stat
WHERE idx_reindex_recommended IS TRUE;

The operator runs REINDEX INDEX for a reported index.

REINDEX INDEX items_embedding_diskann_idx;

After REINDEX completes, verify that idx_reindex_recommended is false for the index.

Limitations¶

Only vector and vector_l2_ops are supported.
Physical replication refresh, replay, and promotion are not supported.