Search

Get the nearest 5 neighbors to a vector

SET vectors.hnsw_ef_search = 64;
SELECT * FROM items ORDER BY embedding <-> '[3,2,1]' LIMIT 5;

Operators

These operators are used for distance metrics:

Name	Description
<->	squared Euclidean distance
<#>	negative dot product
<=>	cosine distance

For their definitions, see overview.

Filter

For a given category, get the nearest 10 neighbors to a vector

SELECT 1 FROM items WHERE category_id = 1 ORDER BY embedding <#> '[0.5,0.5,0.5]' limit 10

Query options

Search options are specified by PostgreSQL GUC.

Set ivf scan lists to 1 in session:

SET vectors.ivf_nprobe=1;

Set hnsw search scope to 40 in transaction:

SET LOCAL vectors.hnsw_ef_search=40;

For all options, refer to search options.

Advanced usage

In traditional vector database, sometimes you expect the search to return the exact number of vectors equal to LIMIT, but it can't:

SELECT COUNT(1) FROM (SELECT 1 FROM t WHERE (category_id = 1) ORDER BY val <-> '[1,1,1]' limit 10) t2;
--- returns 1, much less than 10

That is why we introduce vbase search mode and set it as default.

Search modes

There are two search modes: vbase and basic.

vbase

As the default search mode, vbase is suitable for most scenarios. In most cases, vbase mode would return enough vectors for your filter.

For how it works, refer to the thesis VBASE: Unifying Online Vector Similarity Search and Relational Queries via Relaxed Monotonicity.

It's recommended to use vbase in these situations:

• Search with filter or transaction
• Returning sufficient vectors is important
• Tired of tuning query options in basic mode

basic

basic is behaviorally consistent with traditional vector databases. It will be useful if you want to align other vector databases.

Enabling basic, you must respect these restrictions:

• Search without filter and transaction
• Returning insufficient vectors is acceptable