@an5/adapters 0.2.11 → 0.2.14

package/README.md

@@ -13,7 +13,7 @@ Standalone runtime database adapter and query engine for AN5 ORM. Provides conne
 - **Field Math Operators** — Atomic updates with `increment`, `decrement`, `multiply`, `divide`, `set`
 - **Vector Search** — Similarity search using NBase, pgvector (PostgreSQL), `VECTOR_DISTANCE` (MSSQL), or in-memory cosine/euclidean/dot similarity
 - **Real Transactions** — Interactive and callback transactions (`$transaction(async tx => ...)` and `$begin()/$commit()/$rollback()`)
-- **Cross-Language** — Unified API in TypeScript, Python, .NET (C#), Golang, and Rust
+- **Cross-Language** — Unified API in TypeScript, Python, .NET (C#), Golang, Rust, Java, Kotlin, and Swift
 - **Google Sheets Database** — Use spreadsheets as a live database with full CRUD and SQL syntax support
 
 ---
@@ -52,6 +52,78 @@ cargo add an5-adapters
 
 The crate is driver-agnostic — it depends on `sqlx` with `any`, so the app enables the driver it needs. See [crates.io](https://crates.io/crates/an5-adapters) and [docs.rs](https://docs.rs/an5-adapters).
 
+### Java
+
+```bash
+# Included in the npm package under java/, which ships its own pom.xml
+```
+
+`java/` is a Maven module with **no dependencies**: the adapter speaks JDBC through
+`java.sql`, so the app picks the driver it already has — `org.xerial:sqlite-jdbc`,
+`org.postgresql:postgresql` or `com.microsoft.sqlserver:mssql-jdbc`. That is what lets one
+runtime serve all three engines and what keeps it usable on Android, where an adapter that
+dragged in three drivers would not fit.
+
+```xml
+<dependency>
+  <groupId>io.github.an5orm</groupId>
+  <artifactId>an5-adapters-java</artifactId>
+  <version>0.2.14</version>
+</dependency>
+```
+
+From a checkout the same module is built and installed into `~/.m2`:
+
+```bash
+mvn -f java/pom.xml install
+mvn -f java/pom.xml test
+```
+
+### Kotlin
+
+```bash
+# Included in the npm package under kotlin/, which ships build.gradle.kts
+```
+
+Gradle rather than Maven, because Kotlin on Android is built with Gradle and a runtime a
+phone app cannot resolve is not a mobile runtime. The Kotlin runtime depends on the Java one
+rather than reimplementing it, so the dialect rules and the where builder exist once:
+
+```kotlin
+dependencies {
+    implementation("io.github.an5orm:an5-adapters-kotlin:0.2.14")
+}
+```
+
+From a checkout the Kotlin module resolves its Java sibling from `~/.m2` — declared as
+`mavenLocal()` in `build.gradle.kts`, so the checkout builds without publishing anything
+first:
+
+```bash
+mvn -f java/pom.xml install
+gradle -p kotlin build
+```
+
+Both JVM modules publish to Maven Central, and each release ships both
+`io.github.an5orm:an5-adapters-java:<version>` and
+`io.github.an5orm:an5-adapters-kotlin:<version>`: a `v*` tag runs the
+`publish-maven` job in `.github/workflows/publish.yml` (`mvn -Prelease deploy` and
+`gradle publish`), and a manual run is available through the workflow's `publish-maven`
+input. It needs the repository secrets `MAVEN_CENTRAL_USERNAME` and `MAVEN_CENTRAL_TOKEN`
+(a Central Portal token), `MAVEN_GPG_PRIVATE_KEY` and `MAVEN_GPG_PASSPHRASE`.
+
+### Swift
+
+```swift
+.package(url: "https://github.com/an5ORM/an5Adapters.git", from: "0.2.14")
+```
+
+A SwiftPM package that links the **system** SQLite — the database every Apple platform
+already ships, so there is no bundled engine and the same file works on device and in the
+simulator. Building it needs SQLite's headers (`apt-get install libsqlite3-dev` on Linux).
+The runtime takes a `SQLDriver`, so an app that already has a database layer can put GRDB or
+SQLite.swift underneath instead.
+
 ---
 
 ## NBase — Neural Vector Database
@@ -97,7 +169,7 @@ returns the NBase hits — id, metadata and `distance` — instead of table rows
 With an `nbase://` connection string, search returns the hits themselves:
 
 ```ts
-const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
+const hits = await db.article.vectorSearch({ vector: queryEmbedding, take: 5 });
 // hits[0] = { id: 'Article:42', an5Id: '42', an5Model: 'Article', distance: 0.11 }
 ```
 
@@ -113,10 +185,10 @@ const db = createAn5Adapter({
   nbase: 'nbase://localhost:1307',
 });
 
-await db.table('Article').indexVectorsInNBase({ vectorField: 'embedding' });
+await db.article.indexVectorsInNBase({ vectorField: 'embedding' });
 // → { indexed: 1200 }
 
-const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
+const hits = await db.article.vectorSearch({ vector: queryEmbedding, take: 5 });
 // hits[0] = { id, title, ..., distance }
 ```
 
@@ -139,6 +211,66 @@ If NBase is unreachable, `vectorSearch` logs a warning and falls back to the
 database's native vector support, then to in-memory similarity, so an outage
 degrades performance rather than breaking queries.
 
+---
+
+## SQLite — vector search without a vector database
+
+For host-language-free distance calculation, build the shared
+[AN5 C extension](native/sqlite/README.md) with
+`npm run build:sqlite:native` and pass the printed library path as `sqliteVec`.
+It runs cosine, Euclidean and dot-product distances natively, with SSE2 on
+x86-64 and query-vector caching. The existing fallback remains available when
+an extension is not loaded.
+
+SQLite has no vector type, so a `VECTOR(n)` column stores a **BLOB of
+little-endian float32** — 4 bytes per dimension. Write a plain array of numbers
+and the adapter encodes it; read it back and you get the same array. A column
+that already holds JSON text (`'[0.1, 0.2]'`) keeps working, so nothing has to
+be migrated.
+
+```ts
+await db.article.create({ data: { title: '…', embedding: queryEmbedding } });
+
+const row = await db.article.findFirst({ where: { title: '…' } });
+row.embedding; // number[]
+```
+
+The search is ranked **inside the database**, trying four strategies in order:
+
+| Order | Strategy | Needs | Reaches |
+|-------|----------|-------|---------|
+| 1 | `sqlite-vec` | The extension loaded | Scalar distances over ordinary tables |
+| 2 | `udf` | A driver that can register a function | `BLOB` and legacy text columns |
+| 3 | `sql` | JSON1 (built in since SQLite 3.38) | Legacy text columns |
+| 4 | `memory` | Nothing | Any column, whole table loaded |
+
+Strategies 1-3 transfer only the rows that match, which is the reason to prefer
+them. A row whose stored vector cannot be scored is left out rather than returned
+with a null distance.
+
+[sqlite-vec](https://github.com/asg017/sqlite-vec) supplies native vector distance
+functions for exact search. The adapter scans an ordinary table with those
+functions; it does not create or synchronize a `vec0` virtual table:
+
+```ts
+const db = createAn5Adapter({
+  connectionString: 'sqlite:///app.db',
+  sqliteVec: require('sqlite-vec').getLoadablePath(),
+});
+```
+
+`vectorStrategy` pins one strategy instead of probing — `'auto'` (the default),
+`'sqlite-vec'`, `'udf'`, `'sql'` or `'memory'`. In TypeScript it can also be
+supplied per query on `vectorSearch`. Every other runtime implements
+the same four strategies with the same order; `sqlx` (Rust) and JDBC (Java,
+Kotlin) use `sql` for JSON text and `memory` for BLOB columns without
+driver-specific vector functions.
+
+```python
+from an5_adapter import create_an5_adapter
+db = create_an5_adapter("sqlite:///app.db", sqlite_vec="vec0", vector_strategy="auto")
+```
+
 
 ## Usage
 
@@ -274,7 +406,7 @@ db.transaction(perform_transfer)
 | `count(args)` | Count matching records |
 | `aggregate(args)` | Compute `_count`, `_sum`, `_avg`, `_min`, `_max` |
 | `groupBy(args)` | Group by fields with aggregations and pagination |
-| `vectorSearch(args)` | Semantic vector similarity search |
+| `vectorSearch(args)` | Semantic vector similarity search; SQLite ranks it in the database (sqlite-vec, `an5_vec_*`, `json_each`), everything else uses the engine's native support or scores in memory |
 
 Generated TypeScript field metadata marks schema primary keys with `isId: true`.
 SQL and Google Sheets `create` use this marker to identify custom primary-key

package/dist/an5Adapter.d.ts

@@ -1,6 +1,7 @@
 import { An5SheetsAdapter, An5SheetsAdapterConfig, SheetsTableClient } from './googlesheets';
 import type { An5AdapterConfig, Dialect, TransactionHandle } from './base/types';
 import { type NBaseAdapterConfig, type NBaseVectorClient } from './nbase';
+import { type SqliteVectorSupport, type VectorStrategyPreference } from './sqlite/vector';
 export type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from './base/types';
 export { setAdapterMetadata, createAdapterProxy, type AdapterMetadata } from './base/metadata';
 export type { TypedAn5Adapter, AdapterAPI } from './typed';
@@ -36,6 +37,14 @@ export declare class An5Adapter {
     private requireEngine;
     private requireSheetsAdapter;
     exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]>;
+    /**
+     * The SQLite engine's vector hooks, or null when this is not a SQLite adapter.
+     * `vectorSearch` needs them to load sqlite-vec and register the distance
+     * functions; a connection with no hooks still searches in memory.
+     */
+    sqliteVectorSupport(): Promise<SqliteVectorSupport | null>;
+    /** `vectorStrategy` from the config, so a project can pin one strategy. */
+    get vectorStrategy(): VectorStrategyPreference | undefined;
     /** INTERNAL: used by AdapterTableClient for DML statements needing row count */
     _executeRaw(query: string, params?: Record<string, any>): Promise<number>;
     /** Execute a raw query with positional values → @p_0, @p_1, ... per dialect */
@@ -125,9 +134,12 @@ export declare class ViewClient<T = any> {
 export declare class An5AdapterTx {
     private readonly handle;
     readonly dialect: Dialect;
+    private readonly parentVectorSupport;
+    readonly vectorStrategy?: VectorStrategyPreference | undefined;
     [key: string]: any;
     private closed;
-    constructor(handle: TransactionHandle, dialect: Dialect);
+    constructor(handle: TransactionHandle, dialect: Dialect, parentVectorSupport?: SqliteVectorSupport | null, vectorStrategy?: VectorStrategyPreference | undefined);
+    sqliteVectorSupport(): Promise<SqliteVectorSupport | null>;
     exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]>;
     _executeRaw(query: string, params?: Record<string, any>): Promise<number>;
     $commit(): Promise<void>;
@@ -141,11 +153,30 @@ export declare class AdapterTableClient<T = any> {
     constructor(adapter: An5Adapter | An5AdapterTx, modelName: string);
     get dialect(): Dialect;
     get tableName(): string;
+    /** The table name this model maps to, before any quoting is applied. */
+    private get mappedTableName();
+    /**
+     * The bare table name, for helpers that take a string literal. `@@map` values
+     * may be pre-quoted or schema-qualified, neither of which `pragma_table_info`
+     * accepts, so the last segment is unwrapped here.
+     */
+    get rawTableName(): string;
     private get nolock();
     /** Build the shared context used by parseWhere to resolve relations and self references. */
     private whereContext;
     private doExec;
     private doExecuteRaw;
+    /**
+     * Encode every `VECTOR(n)` value on its way into SQLite.
+     *
+     * The column holds a float32 BLOB, which is a third of the size of the JSON
+     * text it replaces and is what sqlite-vec reads. Values that already arrived
+     * as text or bytes are left alone, so rows written by an older version stay
+     * readable.
+     */
+    private encodeVectorFields;
+    /** Decode `VECTOR(n)` columns back into `number[]` after a read. */
+    private decodeVectorFields;
     findMany(args?: {
         where?: any;
         orderBy?: any;
@@ -243,9 +274,19 @@ export declare class AdapterTableClient<T = any> {
         vectorField?: string;
         distanceMetric?: 'cosine' | 'euclidean' | 'dot';
         vectorElementType?: 'float32' | 'float16' | 'uint8';
+        vectorStrategy?: VectorStrategyPreference;
     }): Promise<(T & {
         distance: number;
     })[]>;
+    /**
+     * Rank the vector column in the client. This is the last resort for every
+     * provider, and the only option on SQLite connections that offer neither
+     * sqlite-vec, a driver function nor JSON1.
+     *
+     * The whole table is loaded, so it is only reasonable for a table small
+     * enough to fit in memory.
+     */
+    private scoreVectorsInMemory;
 }
 export declare function createAn5Adapter(config: AnyAdapterConfig): AnyAdapter;
 export declare function createAn5Adapter<TModels extends object>(config: AnyAdapterConfig): import('./typed').TypedAn5Adapter<TModels>;

package/dist/an5Adapter.js

@@ -17,6 +17,7 @@ const parseConnectionString_1 = require("./googlesheets/parseConnectionString");
 const SQLITE_FILE_SUFFIXES = ['.sqlite', '.sqlite3', '.db'];
 const nbase_1 = require("./nbase");
 const sql_1 = require("./base/sql");
+const vector_1 = require("./sqlite/vector");
 const metadata_1 = require("./base/metadata");
 var metadata_2 = require("./base/metadata");
 Object.defineProperty(exports, "setAdapterMetadata", { enumerable: true, get: function () { return metadata_2.setAdapterMetadata; } });
@@ -50,7 +51,10 @@ function isDuplicateKeyError(error, dialect) {
 function appendUpdateSet(sets, params, col, val, dialect) {
     const quoted = (0, sql_1.quote)(col, dialect);
     const safeCol = sanitizeParamName(col);
-    if (val && typeof val === 'object' && !(val instanceof Date)) {
+    // `TypedArray.prototype.set` is the copy method, not the update operator, so a
+    // vector written as a float32 BLOB must not be read as `{ set: ... }`.
+    const isLiteral = Array.isArray(val) || ArrayBuffer.isView(val) || val instanceof ArrayBuffer;
+    if (val && typeof val === 'object' && !(val instanceof Date) && !isLiteral) {
         if (val.increment !== undefined) {
             const p = (0, sql_1.bindParam)(params, `s_${safeCol}_inc`, val.increment);
             sets.push(`${quoted} = ${quoted} + @${p}`);
@@ -343,6 +347,21 @@ class An5Adapter {
             return this.sheetsAdapter.exec(query, params);
         return (await this.requireEngine()).exec(query, params);
     }
+    /**
+     * The SQLite engine's vector hooks, or null when this is not a SQLite adapter.
+     * `vectorSearch` needs them to load sqlite-vec and register the distance
+     * functions; a connection with no hooks still searches in memory.
+     */
+    async sqliteVectorSupport() {
+        if (this.sheetsAdapter)
+            return null;
+        const engine = await this.requireEngine();
+        return engine.dialect === 'sqlite' ? (engine.vectorSupport ?? null) : null;
+    }
+    /** `vectorStrategy` from the config, so a project can pin one strategy. */
+    get vectorStrategy() {
+        return this._engineConfig?.vectorStrategy ?? this.engine?.vectorSupport?.options?.vectorStrategy;
+    }
     /** INTERNAL: used by AdapterTableClient for DML statements needing row count */
     async _executeRaw(query, params) {
         return (await this.requireEngine()).executeRaw(query, params);
@@ -430,7 +449,7 @@ class An5Adapter {
             return Promise.all(fn);
         const engine = await this.requireEngine();
         const handle = await engine.beginTransaction();
-        const txAdapter = new An5AdapterTx(handle, this.dialect);
+        const txAdapter = new An5AdapterTx(handle, this.dialect, engine.vectorSupport ?? null, this.vectorStrategy);
         try {
             const result = await fn(txAdapter);
             await handle.commit();
@@ -446,7 +465,7 @@ class An5Adapter {
             throw new Error('Interactive transactions are not supported by the Google Sheets adapter');
         }
         const engine = await this.requireEngine();
-        return new An5AdapterTx(await engine.beginTransaction(), this.dialect);
+        return new An5AdapterTx(await engine.beginTransaction(), this.dialect, engine.vectorSupport ?? null, this.vectorStrategy);
     }
     table(modelName) {
         if (this.sheetsAdapter)
@@ -614,12 +633,17 @@ class ViewClient {
 exports.ViewClient = ViewClient;
 // ─── Transaction-scoped adapter ────────────────────────────────────────────────────
 class An5AdapterTx {
-    constructor(handle, dialect) {
+    constructor(handle, dialect, parentVectorSupport = null, vectorStrategy) {
         this.handle = handle;
         this.dialect = dialect;
+        this.parentVectorSupport = parentVectorSupport;
+        this.vectorStrategy = vectorStrategy;
         this.closed = false;
         return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
     }
+    async sqliteVectorSupport() {
+        return this.dialect === 'sqlite' ? this.parentVectorSupport : null;
+    }
     async exec(query, params) {
         this.ensureOpen();
         return this.handle.exec(query, params);
@@ -655,6 +679,15 @@ class AdapterTableClient {
     }
     get dialect() { return this.adapter.dialect; }
     get tableName() {
+        const t = this.mappedTableName;
+        if (t.startsWith('[') || t.startsWith('"') || t.startsWith('`'))
+            return t;
+        if (t.includes('.'))
+            return t.split('.').map(p => (0, sql_1.quote)(p, this.dialect)).join('.');
+        return (0, sql_1.quote)(t, this.dialect);
+    }
+    /** The table name this model maps to, before any quoting is applied. */
+    get mappedTableName() {
         const name = this.modelName;
         let t = name;
         const modelToTable = (0, metadata_1.getModelToTable)();
@@ -670,11 +703,16 @@ class AdapterTableClient {
                     t = modelToTable[lower];
             }
         }
-        if (t.startsWith('[') || t.startsWith('"') || t.startsWith('`'))
-            return t;
-        if (t.includes('.'))
-            return t.split('.').map(p => (0, sql_1.quote)(p, this.dialect)).join('.');
-        return (0, sql_1.quote)(t, this.dialect);
+        return t;
+    }
+    /**
+     * The bare table name, for helpers that take a string literal. `@@map` values
+     * may be pre-quoted or schema-qualified, neither of which `pragma_table_info`
+     * accepts, so the last segment is unwrapped here.
+     */
+    get rawTableName() {
+        const last = this.mappedTableName.split('.').pop() ?? this.mappedTableName;
+        return last.replace(/^[\s]*[\[\]"`]+|[\[\]"`]+[\s]*$/g, '');
     }
     get nolock() {
         return this.dialect === 'mssql' ? ' WITH (NOLOCK)' : '';
@@ -693,6 +731,58 @@ class AdapterTableClient {
     async doExecuteRaw(query, params) {
         return this.adapter._executeRaw(query, params);
     }
+    /**
+     * Encode every `VECTOR(n)` value on its way into SQLite.
+     *
+     * The column holds a float32 BLOB, which is a third of the size of the JSON
+     * text it replaces and is what sqlite-vec reads. Values that already arrived
+     * as text or bytes are left alone, so rows written by an older version stay
+     * readable.
+     */
+    encodeVectorFields(data) {
+        if (this.dialect !== 'sqlite')
+            return data;
+        const fields = (0, metadata_1.getFieldsForModel)(this.modelName);
+        const vectorFields = Object.keys(fields).filter((name) => (0, vector_1.isVectorField)(fields[name]));
+        if (vectorFields.length === 0)
+            return data;
+        const { encodeVector } = require('./sqlite/vector');
+        const out = { ...data };
+        for (const name of vectorFields) {
+            const value = out[name];
+            if ((0, vector_1.needsVectorEncoding)(value)) {
+                const parsed = Array.from(value);
+                if (parsed.length > 0)
+                    out[name] = encodeVector(parsed);
+            }
+        }
+        return out;
+    }
+    /** Decode `VECTOR(n)` columns back into `number[]` after a read. */
+    decodeVectorFields(rows) {
+        if (this.dialect !== 'sqlite' || !Array.isArray(rows) || rows.length === 0)
+            return rows;
+        const fields = (0, metadata_1.getFieldsForModel)(this.modelName);
+        const vectorFields = Object.keys(fields).filter((name) => (0, vector_1.isVectorField)(fields[name]));
+        if (vectorFields.length === 0)
+            return rows;
+        return rows.map((row) => {
+            if (!row || typeof row !== 'object')
+                return row;
+            let changed = false;
+            const out = { ...row };
+            for (const name of vectorFields) {
+                if (!(name in out))
+                    continue;
+                const decoded = (0, vector_1.decodeVector)(out[name]);
+                if (decoded) {
+                    out[name] = decoded;
+                    changed = true;
+                }
+            }
+            return changed ? out : row;
+        });
+    }
     async findMany(args) {
         const params = {};
         const whereCtx = this.whereContext();
@@ -758,7 +848,7 @@ class AdapterTableClient {
             if (orderSql)
                 query += ` ${orderSql}`;
         }
-        const rows = await this.doExec(query, params);
+        const rows = this.decodeVectorFields(await this.doExec(query, params));
         if (args?.include) {
             await resolveIncludes(this.modelName, rows, args.include, this.adapter);
         }
@@ -800,7 +890,7 @@ class AdapterTableClient {
         }
         const fields = (0, metadata_1.getFieldsForModel)(this.modelName);
         const idFieldName = (0, metadata_1.resolveIdField)(fields);
-        const data = { ...rawData };
+        const data = this.encodeVectorFields(rawData);
         if (idFieldName) {
             const fieldDef = fields[idFieldName];
             const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || fieldDef?.type || '');
@@ -870,9 +960,10 @@ class AdapterTableClient {
             const rowPlaceholders = [];
             for (let r = 0; r < args.data.length; r++) {
                 const row = args.data[r];
+                const encoded = this.encodeVectorFields(row);
                 const vals = firstCols.map(col => {
                     const p = `r${r}_${col}`;
-                    params[p] = row[col] ?? null;
+                    params[p] = encoded[col] ?? null;
                     return `@${p}`;
                 });
                 rowPlaceholders.push(`(${vals.join(', ')})`);
@@ -905,13 +996,14 @@ class AdapterTableClient {
                 delete rawData[key];
             }
         }
+        const data = this.encodeVectorFields(rawData);
         const setCols = Object.keys(rawData).filter(k => rawData[k] !== undefined);
         if (setCols.length > 0) {
             const params = {};
             const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, 'w_', this.whereContext());
             const sets = [];
             for (const col of setCols) {
-                appendUpdateSet(sets, params, col, rawData[col], this.dialect);
+                appendUpdateSet(sets, params, col, data[col], this.dialect);
             }
             if (sets.length > 0) {
                 const query = `UPDATE ${this.tableName} SET ${sets.join(', ')}${whereSql ? ` WHERE ${whereSql}` : ''}`;
@@ -963,10 +1055,11 @@ class AdapterTableClient {
     async updateMany(args) {
         const params = {};
         const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, 'w_', this.whereContext());
+        const data = this.encodeVectorFields(args.data);
         const setCols = Object.keys(args.data).filter(k => args.data[k] !== undefined);
         const sets = [];
         for (const col of setCols) {
-            appendUpdateSet(sets, params, col, args.data[col], this.dialect);
+            appendUpdateSet(sets, params, col, data[col], this.dialect);
         }
         if (sets.length === 0)
             return { count: 0 };
@@ -1307,6 +1400,30 @@ class AdapterTableClient {
                     throw err;
             }
         }
+        else if (this.dialect === 'sqlite') {
+            // SQLite has no vector type, so the ranking runs through sqlite-vec, a
+            // driver function, or json_each — whichever this connection supports.
+            const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, '', this.whereContext());
+            const support = await this.adapter.sqliteVectorSupport?.() ?? null;
+            const ranked = await (0, vector_1.runSqliteVectorSearch)({
+                exec: (sql, p) => this.doExec(sql, p),
+                vectorSupport: support,
+                table: this.tableName,
+                rawTable: this.rawTableName,
+                column: col,
+                rawColumn: vectorField,
+                vector: args.vector,
+                metric,
+                take,
+                tail: whereSql ? ` WHERE ${whereSql}` : '',
+                params,
+                preference: args.vectorStrategy ?? this.adapter.vectorStrategy ?? support?.options?.vectorStrategy,
+            });
+            if (ranked)
+                return this.decodeVectorFields(ranked.rows);
+            // No in-database strategy: score the column in the client instead.
+            return this.scoreVectorsInMemory(args, metric, take, vectorField);
+        }
         else if (this.dialect === 'mssql') {
             const distFn = metric === 'cosine' ? 'cosine' : metric === 'euclidean' ? 'euclidean' : 'dot';
             const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, '', this.whereContext());
@@ -1333,35 +1450,26 @@ class AdapterTableClient {
             }
         }
         // 2. Fallback: in-memory similarity computation when native vector support is unavailable
+        return this.scoreVectorsInMemory(args, metric, take, vectorField);
+    }
+    /**
+     * Rank the vector column in the client. This is the last resort for every
+     * provider, and the only option on SQLite connections that offer neither
+     * sqlite-vec, a driver function nor JSON1.
+     *
+     * The whole table is loaded, so it is only reasonable for a table small
+     * enough to fit in memory.
+     */
+    async scoreVectorsInMemory(args, metric, take, vectorField = 'embedding') {
         const rows = await this.findMany({ where: args.where });
         const scored = [];
         for (const row of rows) {
-            const raw = row[vectorField];
-            if (!raw)
+            const vec = (0, vector_1.decodeVector)(row[vectorField]);
+            if (!vec)
                 continue;
-            let vec = [];
-            try {
-                vec = typeof raw === 'string' ? JSON.parse(raw) : raw;
-            }
-            catch {
+            const dist = (0, vector_1.vectorDistance)(args.vector, vec, metric);
+            if (dist === null)
                 continue;
-            }
-            if (!Array.isArray(vec) || vec.length !== args.vector.length)
-                continue;
-            let dot = 0, m1 = 0, m2 = 0;
-            for (let i = 0; i < args.vector.length; i++) {
-                const av = args.vector[i] ?? 0;
-                const bv = vec[i] ?? 0;
-                dot += av * bv;
-                m1 += av ** 2;
-                m2 += bv ** 2;
-            }
-            const cosine = m1 && m2 ? dot / (Math.sqrt(m1) * Math.sqrt(m2)) : 0;
-            const dist = metric === 'cosine'
-                ? 1 - cosine
-                : metric === 'dot'
-                    ? -dot
-                    : Math.sqrt(args.vector.reduce((s, v, i) => s + (v - (vec[i] ?? 0)) ** 2, 0));
             scored.push({ row, dist });
         }
         scored.sort((a, b) => a.dist - b.dist);

package/dist/base/types.d.ts

@@ -1,3 +1,4 @@
+import type { SqliteVectorSupport, VectorStrategyPreference } from '../sqlite/vector';
 export type Dialect = 'mssql' | 'postgres' | 'mysql' | 'sqlite' | 'googlesheets';
 export interface An5AdapterConfig {
     connectionString?: string;
@@ -7,6 +8,17 @@ export interface An5AdapterConfig {
      * run in NBase while the rows stay in `connectionString`'s database.
      */
     nbase?: string;
+    /**
+     * Path to sqlite-vec or the AN5 native vector extension. On SQLite it is loaded before the
+     * vector capabilities are probed, so `vectorSearch` ranks inside the database
+     * instead of loading the table into memory. Other providers ignore it.
+     */
+    sqliteVec?: string;
+    /**
+     * Pin the SQLite vector search strategy. `auto` (the default) probes for
+     * sqlite-vec, a driver function and JSON1, and uses the first that works.
+     */
+    vectorStrategy?: VectorStrategyPreference;
     engine?: QueryEngine;
     db?: any;
     driver?: any;
@@ -27,4 +39,6 @@ export interface QueryEngine {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     beginTransaction(): Promise<TransactionHandle>;
+    /** SQLite only: extension loading and distance-function registration. */
+    vectorSupport?: SqliteVectorSupport;
 }

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { parseWhere, buildOrderBy, quote } from './base/sql';
 export { NBaseVectorClient, NBaseError, createNBaseVectorClient, createNBaseClient, parseNBaseConnectionString, buildVectorId, parseVectorId, } from './nbase';
 export type { NBaseAdapterConfig, NBaseClientConfig, NBaseVector, NBaseSearchOptions, NBaseSearchResult, NBaseStats, } from './nbase';
 export type { An5AdapterConfig, AdapterMetadata, Dialect, } from './an5Adapter';
+export { encodeVector, decodeVector, vectorDistance, isVectorField, AN5_VECTOR_FUNCTIONS, SQLITE_VEC_FUNCTIONS, } from './sqlite/vector';
+export type { SqliteVectorStrategy, VectorMetric, VectorStrategyPreference, } from './sqlite/vector';
 export type { TypedAn5Adapter, AdapterAPI } from './typed';
 export { getLlmConfig, setLlmConfig, getEmbeddingConfig, setEmbeddingConfig, resetAdapter, } from './config';
 export type { LlmConfigData, EmbeddingConfigData, } from './config';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.parseVectorId = exports.buildVectorId = exports.parseNBaseConnectionString = exports.createNBaseClient = exports.createNBaseVectorClient = exports.NBaseError = exports.NBaseVectorClient = exports.quote = exports.buildOrderBy = exports.parseWhere = exports.setAdapterMetadata = exports.executorFromAdapter = exports.createAdapterProxy = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
+exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.SQLITE_VEC_FUNCTIONS = exports.AN5_VECTOR_FUNCTIONS = exports.isVectorField = exports.vectorDistance = exports.decodeVector = exports.encodeVector = exports.parseVectorId = exports.buildVectorId = exports.parseNBaseConnectionString = exports.createNBaseClient = exports.createNBaseVectorClient = exports.NBaseError = exports.NBaseVectorClient = exports.quote = exports.buildOrderBy = exports.parseWhere = exports.setAdapterMetadata = exports.executorFromAdapter = exports.createAdapterProxy = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
 var an5Adapter_1 = require("./an5Adapter");
 Object.defineProperty(exports, "An5Adapter", { enumerable: true, get: function () { return an5Adapter_1.An5Adapter; } });
 Object.defineProperty(exports, "AdapterTableClient", { enumerable: true, get: function () { return an5Adapter_1.AdapterTableClient; } });
@@ -20,6 +20,13 @@ Object.defineProperty(exports, "createNBaseClient", { enumerable: true, get: fun
 Object.defineProperty(exports, "parseNBaseConnectionString", { enumerable: true, get: function () { return nbase_1.parseNBaseConnectionString; } });
 Object.defineProperty(exports, "buildVectorId", { enumerable: true, get: function () { return nbase_1.buildVectorId; } });
 Object.defineProperty(exports, "parseVectorId", { enumerable: true, get: function () { return nbase_1.parseVectorId; } });
+var vector_1 = require("./sqlite/vector");
+Object.defineProperty(exports, "encodeVector", { enumerable: true, get: function () { return vector_1.encodeVector; } });
+Object.defineProperty(exports, "decodeVector", { enumerable: true, get: function () { return vector_1.decodeVector; } });
+Object.defineProperty(exports, "vectorDistance", { enumerable: true, get: function () { return vector_1.vectorDistance; } });
+Object.defineProperty(exports, "isVectorField", { enumerable: true, get: function () { return vector_1.isVectorField; } });
+Object.defineProperty(exports, "AN5_VECTOR_FUNCTIONS", { enumerable: true, get: function () { return vector_1.AN5_VECTOR_FUNCTIONS; } });
+Object.defineProperty(exports, "SQLITE_VEC_FUNCTIONS", { enumerable: true, get: function () { return vector_1.SQLITE_VEC_FUNCTIONS; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "getLlmConfig", { enumerable: true, get: function () { return config_1.getLlmConfig; } });
 Object.defineProperty(exports, "setLlmConfig", { enumerable: true, get: function () { return config_1.setLlmConfig; } });