---
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;
```