mdcms/neuraldb-docs/pages/nql-basics.md

title	sort	section-id	keywords	description	language
NQL Basics	100	query-language	NQL, NeuralDB Query Language, SQL, syntax, basics, queries	Introduction to NeuralDB Query Language (NQL) — syntax, data types, and basic operations	en

NQL Basics

NQL (NeuralDB Query Language) is a superset of standard SQL. Every valid SQL statement is also valid NQL. NQL adds extensions for vector operations, embedding generation, and semantic search primitives.

Connecting

psql -h localhost -p 5432 -U neuraldb -d mydb
neuraldb-cli -h localhost

Data Types

VECTOR(n)

CREATE TABLE documents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  content TEXT NOT NULL,
  embedding VECTOR(1536)
);

HALFVEC(n) and SPARSEVEC(n)

embedding HALFVEC(1536)   -- 16-bit, half the memory
bm25_vector SPARSEVEC(30000)  -- sparse, non-zero elements only

Basic CRUD

CREATE TABLE products (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL, category TEXT, price DECIMAL(10,2),
  stock INTEGER DEFAULT 0, embedding VECTOR(1536),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

INSERT INTO products (name, category, price, stock, embedding)
VALUES ('Wireless Headphones', 'electronics', 299.99, 150, '[0.023, -0.187, ...]');

SELECT id, name, price FROM products WHERE category = 'electronics';

UPDATE products SET price = 279.99, embedding = '[...]' WHERE id = $1;

DELETE FROM products WHERE id = $1;

Creating Vector Indexes

CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);
CREATE INDEX ON documents USING hnsw (embedding vector_l2_ops);
CREATE INDEX ON documents USING hnsw (embedding vector_ip_ops);

Basic Vector Queries

SELECT id, content, 1 - (embedding <=> $1) AS similarity
FROM documents
ORDER BY embedding <=> $1
LIMIT 10;

Operator	Metric	Index ops
<=>	Cosine distance	vector_cosine_ops
<->	Euclidean (L2)	vector_l2_ops
<#>	Negative dot product	vector_ip_ops

NQL Functions

SELECT vector_dims(embedding) FROM documents LIMIT 1;  -- returns 1536
SELECT vector_norm(embedding) FROM documents LIMIT 5;
SELECT cosine_similarity(embedding, $1) AS similarity FROM documents ORDER BY similarity DESC LIMIT 10;