Vamana¶

Vamana is an ANN index for L2-distance workloads. Index build options and search-time GUCs are applied at different stages and are tuned separately.

Note

Vamana documentation and examples use vector_l2_ops and <->.

Create a Vamana Index¶

CREATE INDEX items_embedding_vamana_idx
  ON items
  USING vectoron (embedding vector_l2_ops)
  WITH (options = $$
    [indexing.vamana]
    alpha = 1.2
    r = 32
    l_search = 64
    phase = 1
  $$);

Build-time Options¶

Build-time options are applied when the index is created. Changing them requires rebuilding the index.

Option	Default	Notes
`indexing.vamana.alpha`	`1.2`	Controls graph pruning. Its effect on recall, build time, and index size depends on the dataset.
`indexing.vamana.r`	`32`	Number of neighbors retained for each node. Higher values may add edges and increase memory use and build cost.
`indexing.vamana.l_search`	`64`	Candidate search width during index construction. This is not the search-time exploration width.
`indexing.vamana.phase`	`1`	Index build phase.

Search-time Option¶

At query time, tune vectoron.vamana_l_search. This GUC is separate from build-time indexing.vamana.l_search.

GUC	Default	Notes
`vectoron.vamana_l_search`	`100`	Candidate exploration width during Vamana search. Higher values evaluate more candidates and may increase CPU work and latency.

When tuning vectoron.vamana_l_search, evaluate its impact on both recall and latency to determine the best configuration for your workload.

Use SET for a session-wide value.

SET vectoron.vamana_l_search = 100;

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

Use SET LOCAL inside a transaction for a single query.

BEGIN;
SET LOCAL vectoron.vamana_l_search = 200;

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

Tuning Notes¶

Separate settings that change the index graph from settings that change search width.

Setting	Applies at	Watch
`r`	Index build	Build time, memory/index size, recall
`alpha`	Index build	Recall and build/search cost changes
`indexing.vamana.l_search`	Index build	Build time and search quality
`vectoron.vamana_l_search`	Query execution	Recall, latency, CPU use

Check recall and latency changes with query sets that match the target filters and data distribution, and choose appropriate values.