{"_id":"@aeriondyseti/drizzle-sqlite-vec","name":"@aeriondyseti/drizzle-sqlite-vec","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aeriondyseti/drizzle-sqlite-vec","version":"0.1.0","description":"SQLite vector search extension for Drizzle ORM using sqlite-vec","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup","test":"vitest","typecheck":"tsc --noEmit"},"keywords":["drizzle","sqlite","vector","sqlite-vec","embeddings","similarity-search"],"author":"","license":"MIT","peerDependencies":{"drizzle-orm":">=0.30.0","better-sqlite3":">=9.0.0","sqlite-vec":">=0.1.0"},"devDependencies":{"@types/better-sqlite3":"^7.6.13","better-sqlite3":"^12.4.6","drizzle-orm":"^0.44.7","sqlite-vec":"^0.1.7-alpha.2","tsup":"^8.5.1","typescript":"^5.9.3","vitest":"^3.2.0"},"gitHead":"d4d5cf6b4ac39f65c4e33214898a799603912d06","_id":"@aeriondyseti/drizzle-sqlite-vec@0.1.0","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-ph2KRunVzobW+ZyaqXW2ODXdal/DbgA08SheYGqo4I4QjI1iVlg71dizl93JSyfacstAyoOrfD5DP9UVpoFjpg==","shasum":"542f7e225ed9bdc7dd5acd050c17257684429835","tarball":"https://registry.npmjs.org/@aeriondyseti/drizzle-sqlite-vec/-/drizzle-sqlite-vec-0.1.0.tgz","fileCount":8,"unpackedSize":141327,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDTZ7USaFMpEoly/mCIsxlx45W8JawlS/4Uq/QaMVxEMgIgNSTmkOlSQ4+hy1F0+pW0wl0S0TuC0dzGopJzttDtAtE="}]},"_npmUser":{"name":"aeriondyseti","email":"inblessedsilencewaiting@gmail.com"},"directories":{},"maintainers":[{"name":"aeriondyseti","email":"inblessedsilencewaiting@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/drizzle-sqlite-vec_0.1.0_1764233421061_0.6368786790519616"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-27T08:50:20.959Z","0.1.0":"2025-11-27T08:50:21.301Z","modified":"2025-11-27T08:50:21.585Z"},"maintainers":[{"name":"aeriondyseti","email":"inblessedsilencewaiting@gmail.com"}],"description":"SQLite vector search extension for Drizzle ORM using sqlite-vec","keywords":["drizzle","sqlite","vector","sqlite-vec","embeddings","similarity-search"],"license":"MIT","readme":"# drizzle-sqlite-vec\n\nSQLite vector search extension for [Drizzle ORM](https://orm.drizzle.team/) using [sqlite-vec](https://github.com/asg017/sqlite-vec).\n\n## Installation\n\n```bash\nnpm install drizzle-sqlite-vec\n```\n\n### Peer Dependencies\n\nThis package requires the following peer dependencies:\n\n```bash\nnpm install drizzle-orm better-sqlite3 sqlite-vec\n```\n\n## Quick Start\n\n```ts\nimport Database from 'better-sqlite3';\nimport * as sqlite_vec from 'sqlite-vec';\nimport { drizzle } from 'drizzle-orm/better-sqlite3';\nimport { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core';\nimport {\n  vector,\n  vec0Table,\n  vecFloat,\n  vecInteger,\n  serializeVector,\n} from 'drizzle-sqlite-vec';\n\n// 1. Initialize database with sqlite-vec extension\nconst sqlite = new Database(':memory:');\nsqlite_vec.load(sqlite);\nconst db = drizzle(sqlite);\n\n// 2. Create a vec0 virtual table for vector search\nconst itemsVec = vec0Table('items_vec', {\n  itemId: vecInteger('item_id').primaryKey(),\n  embedding: vecFloat('embedding', 384),\n});\n\n// Create the table\nsqlite.exec(itemsVec.createSQL());\n\n// 3. Insert vectors\nconst embedding = Array.from({ length: 384 }, () => Math.random());\nsqlite\n  .prepare('INSERT INTO items_vec(embedding) VALUES (?)')\n  .run(serializeVector(embedding));\n\n// 4. Search for similar vectors (KNN search)\nconst queryEmbedding = Array.from({ length: 384 }, () => Math.random());\nconst results = sqlite\n  .prepare('SELECT rowid, distance FROM items_vec WHERE embedding MATCH ? AND k = 10')\n  .all(serializeVector(queryEmbedding));\n```\n\n## Usage\n\n### Setting Up the Database\n\nAlways load the sqlite-vec extension before using vector operations:\n\n```ts\nimport Database from 'better-sqlite3';\nimport * as sqlite_vec from 'sqlite-vec';\n\nconst sqlite = new Database('my-database.db');\nsqlite_vec.load(sqlite);\n```\n\n### Vector Columns in Regular Tables\n\nUse the `vector` column type to store embeddings in regular SQLite tables as BLOBs:\n\n```ts\nimport { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core';\nimport { vector, serializeVector, deserializeVector } from 'drizzle-sqlite-vec';\n\n// Define schema\nconst documents = sqliteTable('documents', {\n  id: integer('id').primaryKey(),\n  content: text('content'),\n  embedding: vector('embedding', { dimensions: 384 }),\n});\n\n// Create table\nsqlite.exec(`\n  CREATE TABLE documents (\n    id INTEGER PRIMARY KEY,\n    content TEXT,\n    embedding BLOB\n  )\n`);\n\n// Insert with vector\nconst embedding = [0.1, 0.2, 0.3, /* ... */];\nsqlite\n  .prepare('INSERT INTO documents (id, content, embedding) VALUES (?, ?, ?)')\n  .run(1, 'Hello world', serializeVector(embedding));\n\n// Read and deserialize\nconst row = sqlite.prepare('SELECT * FROM documents WHERE id = 1').get();\nconst vector = deserializeVector(row.embedding);\n```\n\n### vec0 Virtual Tables (Recommended for Search)\n\nFor efficient K-nearest neighbor (KNN) search, use vec0 virtual tables:\n\n```ts\nimport { vec0Table, vecFloat, vecInteger, serializeVector } from 'drizzle-sqlite-vec';\n\n// Define a vec0 virtual table\nconst itemsVec = vec0Table('items_vec', {\n  itemId: vecInteger('item_id').primaryKey(),\n  embedding: vecFloat('embedding', 384),\n});\n\n// Create the table\nsqlite.exec(itemsVec.createSQL());\n// Generates: CREATE VIRTUAL TABLE IF NOT EXISTS items_vec USING vec0(item_id integer primary key, embedding float[384])\n\n// Drop the table\nsqlite.exec(itemsVec.dropSQL());\n```\n\n#### Vector Column Types\n\n| Function | Description |\n|----------|-------------|\n| `vecFloat(name, dimensions)` | Float32 vector (default, most common) |\n| `vecInt8(name, dimensions)` | Int8 quantized vector (smaller storage) |\n| `vecBit(name, dimensions)` | Binary vector (smallest storage) |\n\n#### Auxiliary Column Types\n\n| Function | Description |\n|----------|-------------|\n| `vecInteger(name)` | Integer column (use for IDs) |\n| `vecText(name)` | Text column |\n| `vecBlob(name)` | Blob column |\n\n#### Distance Metrics\n\n```ts\n// Set distance metric for a vector column\nconst itemsVec = vec0Table('items_vec', {\n  embedding: vecFloat('embedding', 384).distanceMetric('cosine'), // or 'L2'\n});\n```\n\n### KNN Search\n\nPerform K-nearest neighbor search using the `MATCH` syntax:\n\n```ts\n// Insert vectors\nconst vectors = [\n  [1.0, 0.0, 0.0, 0.0],\n  [0.9, 0.1, 0.0, 0.0],\n  [0.0, 1.0, 0.0, 0.0],\n];\n\nvectors.forEach((vec) => {\n  sqlite\n    .prepare('INSERT INTO items_vec(embedding) VALUES (?)')\n    .run(serializeVector(vec));\n});\n\n// Search for top 5 nearest neighbors\nconst queryVector = [1.0, 0.0, 0.0, 0.0];\nconst results = sqlite\n  .prepare('SELECT rowid, distance FROM items_vec WHERE embedding MATCH ? AND k = 5')\n  .all(serializeVector(queryVector));\n\n// Results are sorted by distance (closest first)\n// [{ rowid: 1, distance: 0 }, { rowid: 2, distance: 0.1414... }, ...]\n```\n\n### Distance Functions\n\nCalculate distances between vectors using SQL functions:\n\n```ts\nimport { vec_distance_L2, vec_distance_cosine, serializeVector } from 'drizzle-sqlite-vec';\n\n// L2 (Euclidean) distance\nconst l2Result = sqlite\n  .prepare('SELECT vec_distance_L2(?, ?) as distance')\n  .get(serializeVector([1, 0, 0, 0]), serializeVector([0, 1, 0, 0]));\n// distance ≈ 1.414 (sqrt(2))\n\n// Cosine distance\nconst cosineResult = sqlite\n  .prepare('SELECT vec_distance_cosine(?, ?) as distance')\n  .get(serializeVector([1, 0, 0, 0]), serializeVector([1, 0, 0, 0]));\n// distance = 0 (identical vectors)\n```\n\n### Vector Operations\n\nAdditional sqlite-vec functions available:\n\n```ts\nimport {\n  vec_length,      // Vector magnitude (L2 norm)\n  vec_normalize,   // Normalize to unit length\n  vec_add,         // Element-wise addition\n  vec_sub,         // Element-wise subtraction\n  vec_slice,       // Extract subset of dimensions\n  vec_f32,         // Convert JSON array to vector\n  vec_to_json,     // Convert vector to JSON array\n  vec_quantize_i8, // Quantize to int8\n  vec_quantize_binary, // Convert to binary\n} from 'drizzle-sqlite-vec';\n```\n\n### Type Utilities\n\nHelper functions for working with vectors in TypeScript:\n\n```ts\nimport {\n  typedVector,\n  createVector,\n  zeroVector,\n  randomVector,\n  normalizeVector,\n  validateVector,\n  l2Distance,\n  cosineSimilarity,\n  cosineDistance,\n  dotProduct,\n} from 'drizzle-sqlite-vec';\n\n// Create typed vectors\nconst vec = typedVector(4, [1, 2, 3, 4]);\n\n// Generate vectors\nconst zeros = zeroVector(384);\nconst random = randomVector(384);\nconst custom = createVector(384, (i) => i * 0.01);\n\n// Normalize to unit length\nconst normalized = normalizeVector([3, 4, 0, 0]); // [0.6, 0.8, 0, 0]\n\n// Validate vectors\nvalidateVector([1, 2, 3]);        // true\nvalidateVector([1, 2, 3], 3);     // true (checks dimensions)\nvalidateVector([1, 2, NaN]);      // throws Error\n\n// Calculate distances (JavaScript, not SQL)\nl2Distance([0, 0], [3, 4]);       // 5\ncosineSimilarity([1, 0], [1, 0]); // 1\ncosineDistance([1, 0], [0, 1]);   // 1\ndotProduct([1, 2], [3, 4]);       // 11\n```\n\n### Common Embedding Dimensions\n\nReference constants for popular embedding models:\n\n```ts\nimport { EmbeddingDimensions } from 'drizzle-sqlite-vec';\n\nEmbeddingDimensions.OPENAI_ADA_002;   // 1536\nEmbeddingDimensions.OPENAI_3_SMALL;   // 1536\nEmbeddingDimensions.OPENAI_3_LARGE;   // 3072\nEmbeddingDimensions.COHERE_V3;        // 1024\nEmbeddingDimensions.MINILM_L6_V2;     // 384\nEmbeddingDimensions.MPNET_BASE_V2;    // 768\nEmbeddingDimensions.BGE_SMALL;        // 384\nEmbeddingDimensions.BGE_BASE;         // 768\nEmbeddingDimensions.BGE_LARGE;        // 1024\n```\n\n## Full Example: Document Search\n\n```ts\nimport Database from 'better-sqlite3';\nimport * as sqlite_vec from 'sqlite-vec';\nimport { drizzle } from 'drizzle-orm/better-sqlite3';\nimport { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core';\nimport {\n  vec0Table,\n  vecFloat,\n  vecInteger,\n  serializeVector,\n  EmbeddingDimensions,\n} from 'drizzle-sqlite-vec';\n\n// Initialize\nconst sqlite = new Database('documents.db');\nsqlite_vec.load(sqlite);\nconst db = drizzle(sqlite);\n\n// Regular table for document data\nsqlite.exec(`\n  CREATE TABLE IF NOT EXISTS documents (\n    id INTEGER PRIMARY KEY,\n    title TEXT,\n    content TEXT\n  )\n`);\n\n// vec0 table for embeddings\nconst documentsVec = vec0Table('documents_vec', {\n  docId: vecInteger('doc_id').primaryKey(),\n  embedding: vecFloat('embedding', EmbeddingDimensions.MINILM_L6_V2),\n});\nsqlite.exec(documentsVec.createSQL());\n\n// Insert a document with its embedding\nfunction insertDocument(id: number, title: string, content: string, embedding: number[]) {\n  sqlite.prepare('INSERT INTO documents (id, title, content) VALUES (?, ?, ?)').run(id, title, content);\n  sqlite.prepare('INSERT INTO documents_vec (doc_id, embedding) VALUES (?, ?)').run(id, serializeVector(embedding));\n}\n\n// Search for similar documents\nfunction searchDocuments(queryEmbedding: number[], limit = 10) {\n  const results = sqlite.prepare(`\n    SELECT d.*, v.distance\n    FROM documents d\n    INNER JOIN (\n      SELECT doc_id, distance\n      FROM documents_vec\n      WHERE embedding MATCH ?\n        AND k = ?\n    ) v ON d.id = v.doc_id\n    ORDER BY v.distance\n  `).all(serializeVector(queryEmbedding), limit);\n\n  return results;\n}\n\n// Usage\nconst embedding = await getEmbedding('Introduction to machine learning'); // Your embedding function\ninsertDocument(1, 'ML Basics', 'Introduction to machine learning...', embedding);\n\nconst queryEmbed = await getEmbedding('what is AI?');\nconst similar = searchDocuments(queryEmbed, 5);\n```\n\n## API Reference\n\n### Vector Serialization\n\n- `serializeVector(vector: number[]): Buffer` - Convert array to sqlite-vec format\n- `deserializeVector(buffer: Buffer): number[]` - Convert buffer back to array\n\n### Virtual Table\n\n- `vec0Table(name, columns)` - Create a vec0 table definition\n- `vecFloat(name, dimensions)` - Float32 vector column\n- `vecInt8(name, dimensions)` - Int8 vector column\n- `vecBit(name, dimensions)` - Binary vector column\n- `vecInteger(name)` - Integer auxiliary column\n- `vecText(name)` - Text auxiliary column\n- `vecBlob(name)` - Blob auxiliary column\n\n### SQL Functions\n\n- `vec_distance_L2(vec1, vec2)` - Euclidean distance\n- `vec_distance_cosine(vec1, vec2)` - Cosine distance\n- `vec_length(vec)` - Vector magnitude\n- `vec_normalize(vec)` - Normalize vector\n- `vec_add(vec1, vec2)` - Add vectors\n- `vec_sub(vec1, vec2)` - Subtract vectors\n- `vec_slice(vec, start, end)` - Slice vector\n- `vec_f32(json)` - JSON to vector\n- `vec_to_json(vec)` - Vector to JSON\n- `vec_quantize_i8(vec)` - Quantize to int8\n- `vec_quantize_binary(vec)` - Convert to binary\n\n### Type Utilities\n\n- `typedVector(dimensions, values)` - Create typed vector\n- `createVector(dimensions, generator)` - Generate vector\n- `zeroVector(dimensions)` - Zero vector\n- `randomVector(dimensions)` - Random vector\n- `normalizeVector(vector)` - Normalize to unit length\n- `validateVector(value, dimensions?)` - Validate vector\n- `l2Distance(a, b)` - L2 distance (JS)\n- `cosineSimilarity(a, b)` - Cosine similarity (JS)\n- `cosineDistance(a, b)` - Cosine distance (JS)\n- `dotProduct(a, b)` - Dot product (JS)\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-f289628da786c500cd79671040062d72"}