sqlite-vec

# sqlite-vec

sqlite-vec is a lightweight SQLite extension for vector similarity search. It enables storing and querying vector embeddings directly in SQLite databases without external vector databases.

## Quick Reference

### Load Extension
```python
import sqlite3
import sqlite_vec
from sqlite_vec import serialize_float32

db = sqlite3.connect(":memory:")
db.enable_load_extension(True)
sqlite_vec.load(db)
db.enable_load_extension(False)
```

### Basic KNN Query
```sql
-- Create table
CREATE VIRTUAL TABLE vec_items USING vec0(
  embedding float[4]
);

-- Insert vectors (use serialize_float32() in Python)
INSERT INTO vec_items(rowid, embedding)
VALUES (1, X'CDCCCC3DCDCC4C3E9A99993E00008040');

-- KNN query
SELECT rowid, distance
FROM vec_items
WHERE embedding MATCH '[0.3, 0.3, 0.3, 0.3]'
  AND k = 10
ORDER BY distance;
```

## Core Concepts

### Vector Types

sqlite-vec supports three vector element types:

1. **float[N]** - 32-bit floating point (4 bytes per element)
   - Most common for embeddings (OpenAI, Cohere, etc.)
   - Example: `float[1536]` for text-embedding-3-small

2. **int8[N]** - 8-bit signed integers (1 byte per element)
   - Range: -128 to 127
   - Used for quantized embeddings

3. **bit[N]** - Binary vectors (1 bit per element, packed into bytes)
   - Most compact storage
   - Used for binary quantization

### Binary Serialization Format

Vectors must be provided as binary BLOBs or JSON strings. Python helper functions:

```python
from sqlite_vec import serialize_float32, serialize_int8
import struct

# Float32 vectors
vector = [0.1, 0.2, 0.3, 0.4]
blob = serialize_float32(vector)
# Equivalent to: struct.pack("%sf" % len(vector), *vector)

# Int8 vectors
int_vector = [1, 2, 3, 4]
blob = serialize_int8(int_vector)
# Equivalent to: struct.pack("%sb" % len(int_vector), *int_vector)
```

NumPy arrays can be passed directly (must cast to float32):
```python
import numpy as np
embedding = np.array([0.1, 0.2, 0.3, 0.4]).astype(np.float32)
db.execute("SELE