Vector search

NYXDB stores embeddings in typed vector(N[, element_type]) columns and can build an HNSW region for each immutable part.

Vector type

CREATE TABLE documents (
  id UInt64,
  embedding vector(768),
  PRIMARY KEY (id)
) SETTINGS storage_policy = 'disk_data';

N is 1–65535. The default element type is Float32; Float64 vectors are valid values, but the current HNSW implementation accepts Float32 vectors only. A dimension mismatch is a bind or ingest error, not a truncated value.

HNSW declaration

CREATE TABLE documents (
  id UInt64,
  tenant UInt64,
  embedding vector(768),
  INDEX ix_tenant tenant TYPE bitmap,
  INDEX ix_embedding embedding TYPE hnsw,
  PRIMARY KEY (id)
) SETTINGS storage_policy = 'disk_data';

A bare HNSW declaration uses cosine distance. The region is built at part flush and rebuilt when parts compact. Attribute vectors can declare the index inline:

CREATE TABLE entity_embeddings (
  id UInt64,
  ATTRIBUTE (embedding vector(8) INDEX hnsw)
) SETTINGS
  kind = 'attribute',
  storage_policy = 'memory_data',
  entity = (id);

ANN query shape

An ordered distance expression with a constant query vector and LIMIT k is eligible for the VectorTopK rewrite:

SELECT id, cosine_distance(embedding, '[1,0,0,0,0,0,0,0]') AS distance
FROM entity_embeddings
ORDER BY distance
LIMIT 10;

Confirm the rewrite:

EXPLAIN
SELECT id
FROM entity_embeddings
ORDER BY cosine_distance(embedding, '[1,0,0,0,0,0,0,0]')
LIMIT 10;

Filtering and exact fallback

A supported bitmap predicate can pre-filter the HNSW candidate set:

SELECT id
FROM documents
WHERE tenant = 42
ORDER BY cosine_distance(embedding, '[...]')
LIMIT 20;

If the filter cannot be applied safely inside ANN, the optimizer falls back to an exact scan rather than returning an incorrectly filtered top-k. The same principle applies when an HNSW region is absent or incompatible.

Distance functions

The native vector family includes cosine_distance, cosine_similarity, l2_distance, inner_product, dot_product, and negative_inner_product.