mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 15:24:32 +00:00
89 lines
2.3 KiB
Markdown
89 lines
2.3 KiB
Markdown
---
|
|
title: NQL Basics
|
|
sort: 100
|
|
section-id: query-language
|
|
keywords: NQL, NeuralDB Query Language, SQL, syntax, basics, queries
|
|
description: Introduction to NeuralDB Query Language (NQL) — syntax, data types, and basic operations
|
|
language: 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
|
|
|
|
```bash
|
|
psql -h localhost -p 5432 -U neuraldb -d mydb
|
|
neuraldb-cli -h localhost
|
|
```
|
|
|
|
## Data Types
|
|
|
|
### VECTOR(n)
|
|
|
|
```sql
|
|
CREATE TABLE documents (
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
content TEXT NOT NULL,
|
|
embedding VECTOR(1536)
|
|
);
|
|
```
|
|
|
|
### HALFVEC(n) and SPARSEVEC(n)
|
|
|
|
```sql
|
|
embedding HALFVEC(1536) -- 16-bit, half the memory
|
|
bm25_vector SPARSEVEC(30000) -- sparse, non-zero elements only
|
|
```
|
|
|
|
## Basic CRUD
|
|
|
|
```sql
|
|
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
|
|
|
|
```sql
|
|
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
|
|
|
|
```sql
|
|
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
|
|
|
|
```sql
|
|
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;
|
|
```
|