Querying¶

AkasicDB vector search uses PostgreSQL's ORDER BY ... LIMIT pattern. Without an index, the query runs as exact search. With an AkasicDB vector index, the planner may use ANN search for the same query.

Exact Search¶

When there is no usable index, or when the planner does not choose one, PostgreSQL evaluates matching rows and sorts by distance. For small datasets or ANN validation, this result serves as ground truth.

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

Operator	Meaning
`<->`	Squared L2 distance
`<#>`	Negative dot product
`<=>`	Cosine distance

Indexed ANN Search¶

When an AkasicDB vector index exists, ORDER BY embedding <operator> query_vector LIMIT k may use ANN search. The opclass chosen at index creation and the ORDER BY operator must belong to the same distance family.

CREATE INDEX items_embedding_hnsw_idx
  ON items
  USING vectoron (embedding vector_l2_ops);

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

Search-time GUCs are separate from index build options. For example, HNSW ef_construction is fixed when the index is built, while vectoron.hnsw_ef_search sets search width at query time.

Index	Search-time GUC	Default	Notes
HNSW	`vectoron.hnsw_ef_search`	`100`	Candidate exploration width during HNSW search. Higher values evaluate more candidates and may increase CPU work and latency.
Vamana	`vectoron.vamana_l_search`	`100`	Candidate exploration width during Vamana search. Higher values evaluate more candidates and may increase CPU work and latency.
IVF	`vectoron.ivf_nprobe`	`10`	Number of IVF clusters to scan. Higher values scan more clusters and may increase I/O work and latency.

When tuning these parameters, evaluate their impact on both recall and latency to determine the best configuration for your workload.

Use SET for a session-wide value.

SET vectoron.hnsw_ef_search = 100;
SET vectoron.ivf_nprobe = 10;
SET vectoron.vamana_l_search = 100;

Filtered Search¶

Vector search supports PostgreSQL predicates. Plan shape and latency depend on filter selectivity, scalar indexes, vector indexes, and search mode. Measure with filters representative of the target workload.

CREATE INDEX items_category_idx ON items (category_id);

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

AkasicDB's planner considers ANN search and relational filtering together.

Search Mode¶

vectoron.search_mode selects how vector search is combined with the PostgreSQL query plan.

Mode	Use
`vbase`	Default mode for SQL queries, including filtered searches.
`basic`	Vector-only comparison or debugging. It requires `VACUUM` before use and is not intended for filtered queries.

If basic is used, keep the session scope explicit.

SET vectoron.search_mode = 'basic';

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

After the comparison, use a new session or set the desired mode again.

Query-Local Tuning¶

Use SET LOCAL for a query-scoped tuning value. SET LOCAL is valid only inside a transaction; place it in BEGIN/COMMIT.

BEGIN;
SET LOCAL vectoron.hnsw_ef_search = 200;

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

A single transaction can set multiple search GUCs.

BEGIN;
SET LOCAL vectoron.vamana_l_search = 200;
SET LOCAL vectoron.ivf_nprobe = 20;

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

Increasing search width affects recall, latency, and CPU cost.