mdcms/sample-sites/neuraldb-docs/pages/concepts.md

title	sort	section-id	keywords	description	language
Core Concepts	110	overview	concepts, vectors, embeddings, hybrid queries, nodes, HNSW, ANN	Core NeuralDB concepts — vectors, embeddings, hybrid queries, and the node model	en

Core Concepts

Understanding these fundamental concepts will help you use NeuralDB effectively and make good architectural decisions for your application.

Vectors and Embeddings

A vector is an ordered list of floating-point numbers — a point in high-dimensional space. In NeuralDB, vectors are used to represent the semantic meaning of data.

An embedding is a vector produced by a machine learning model that encodes the semantic meaning of its input. Similar inputs produce vectors that are close together in the embedding space. For example, the sentences "I love dogs" and "I adore canines" will produce embeddings that are close to each other, even though they share no words.

NeuralDB stores embeddings as VECTOR(n) columns, where n is the dimensionality (the number of float32 values). Common dimensionalities:

Model	Dimensions
OpenAI text-embedding-3-small	1536
OpenAI text-embedding-3-large	3072
Cohere embed-english-v3.0	1024
Google text-embedding-004	768
BAAI/bge-m3	1024

Distance Metrics

NeuralDB computes similarity between two vectors using one of three distance metrics:

Cosine Similarity

Measures the angle between two vectors. Ranges from -1 (opposite) to 1 (identical). Ideal for text embeddings produced by models trained with cosine objectives:

cosine_similarity(a, b) = (a · b) / (|a| × |b|)

In NQL, use the <=> operator or COSINE_SIMILARITY() function.

Dot Product

Measures the product of vector magnitudes and the angle between them. Used when vectors are not normalised and magnitude carries information (e.g., collaborative filtering):

dot_product(a, b) = Σ(aᵢ × bᵢ)

In NQL, use the <#> operator or DOT_PRODUCT() function.

Euclidean Distance (L2)

Measures straight-line distance between two points. Lower is more similar. Useful for spatial data and image embeddings:

l2_distance(a, b) = √(Σ(aᵢ - bᵢ)²)

In NQL, use the <-> operator or L2_DISTANCE() function.

Vector Indexes

NeuralDB builds vector indexes using the HNSW (Hierarchical Navigable Small World) algorithm. HNSW provides:

• Sub-linear approximate nearest neighbour (ANN) search
• Configurable trade-off between speed and recall
• Incremental updates (no full rebuild needed when inserting)

HNSW Parameters

When creating a vector index:

CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

Parameter	Description	Default
m	Number of bi-directional links per node. Higher = better recall, more memory	16
ef_construction	Size of candidate set during index construction. Higher = better quality, slower build	64
ef_search	Size of candidate set at query time. Set per-query with SET hnsw.ef_search = 100	40

Exact vs Approximate Search

By default, vector queries use the HNSW index (approximate). For exact results (slower but 100% recall), use:

SET neuraldb.vector_scan = 'exact';
SELECT * FROM documents ORDER BY embedding <=> :query LIMIT 10;

Hybrid Queries

A hybrid query combines vector similarity with relational predicates in a single query plan. The NeuralDB query planner evaluates two strategies and picks the cheaper one:

1. Pre-filter then search — apply relational filters first to reduce the candidate set, then run ANN search on the filtered set
2. Post-filter — run ANN search to get top-k candidates, then apply relational filters

NeuralDB automatically selects the optimal strategy based on selectivity estimates. You can hint the planner:

SELECT * FROM documents
WHERE /*+ PREFILTER */ category = 'news'
ORDER BY embedding <=> :query
LIMIT 10;

Tables and Schemas

NeuralDB is schema-based, like PostgreSQL. Everything lives inside a database → schema → table hierarchy:

CREATE DATABASE my_app;
\c my_app

CREATE SCHEMA vectors;
CREATE SCHEMA metadata;

CREATE TABLE vectors.documents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  content TEXT NOT NULL,
  embedding VECTOR(1536),
  schema_id TEXT REFERENCES metadata.schemas(id),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Nodes

NeuralDB is a distributed system. A node is a single NeuralDB process. Nodes have one of three roles:

Role	Responsibilities
Primary	Accepts reads and writes, coordinates transactions
Replica	Accepts reads, replicates writes from primary
Index	Maintains vector indexes for shard(s), offloads ANN queries

In a single-node deployment, one process takes all three roles.

Sharding

NeuralDB shards data by shard_key. By default, the primary key is used as the shard key:

CREATE TABLE events (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  event_type TEXT,
  embedding VECTOR(768)
) SHARD BY tenant_id;

All rows with the same tenant_id are guaranteed to reside on the same shard, which enables efficient tenant-scoped queries without cross-shard joins.

Transactions

NeuralDB uses multi-version concurrency control (MVCC) for transaction isolation, identical to PostgreSQL:

BEGIN;
  INSERT INTO documents (content, embedding) VALUES ($1, $2);
  UPDATE document_counts SET count = count + 1 WHERE id = $3;
COMMIT;

Both the vector data and the relational data are committed atomically. If the transaction rolls back, neither the row nor the vector index entry is committed.