@an5/adapters 0.2.6 → 0.2.10

package/README.md

@@ -11,9 +11,9 @@ Standalone runtime database adapter and query engine for AN5 ORM. Provides conne
 - **Query Builder & Dialects** — Dialect-aware SQL formatting for MSSQL, PostgreSQL, MySQL, and SQLite
 - **Aggregations & GroupBy** — Standard ORM aggregates (`_count`, `_sum`, `_avg`, `_min`, `_max`) and `groupBy`
 - **Field Math Operators** — Atomic updates with `increment`, `decrement`, `multiply`, `divide`, `set`
-- **Vector Search** — Similarity search using pgvector (PostgreSQL), `VECTOR_DISTANCE` (MSSQL), or in-memory cosine/euclidean/dot similarity
+- **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#), and Golang
+- **Cross-Language** — Unified API in TypeScript, Python, .NET (C#), Golang, and Rust
 - **Google Sheets Database** — Use spreadsheets as a live database with full CRUD and SQL syntax support
 
 ---
@@ -44,8 +44,102 @@ dotnet add package An5Adapters
 # Included in the npm package under golang/ or via go module
 ```
 
+### Rust
+
+```bash
+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).
+
 ---
 
+## NBase — Neural Vector Database
+
+[NBase](https://github.com/N2FlowJS/nbase) is a partitioned vector database with
+HNSW, LSH and KNN indexing behind a REST API. an5 can run vector search there
+instead of loading every row into memory, which matters once a table holds
+millions of embeddings.
+
+The rows stay in your relational table: only the vectors move to NBase, each one
+tagged with its row id, and search results are hydrated from the table.
+
+### Configure
+
+NBase is configured through the connection string, like every other backend:
+
+```ts
+import { createAn5Adapter } from '@an5/adapters';
+
+const db = createAn5Adapter({ connectionString: 'nbase://localhost:1307' });
+await db.$connect(); // probes NBase
+```
+
+Accepted forms:
+
+| Form | Result |
+|------|--------|
+| `nbase://localhost:1307` | `http://localhost:1307` |
+| `nbase:localhost:1307` | `http://localhost:1307` |
+| `nbase:http://localhost:1307` | `http://localhost:1307` |
+| `nbase:https://vectors.example.com` | `https://vectors.example.com` |
+| `nbase://localhost:1307?token=t&timeoutMs=500&method=hnsw` | options applied |
+
+`?token`, `?timeoutMs`, `?method`, `?idField` and `?modelField` are read from the
+query string, and a path is kept as a base path for deployments behind a
+reverse proxy.
+
+This adapter is **vector-only**: it has no relational database, so a search
+returns the NBase hits — id, metadata and `distance` — instead of table rows.
+
+### Search
+
+With an `nbase://` connection string, search returns the hits themselves:
+
+```ts
+const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
+// hits[0] = { id: 'Article:42', an5Id: '42', an5Model: 'Article', distance: 0.11 }
+```
+
+### Search rows from your own table
+
+To get real rows back, keep your database connection string and point it at the
+same NBase instance. NBase is still configured with a connection string, never a
+params object:
+
+```ts
+const db = createAn5Adapter({
+  connectionString: 'sqlserver://localhost:1433;database=mydb',
+  nbase: 'nbase://localhost:1307',
+});
+
+await db.table('Article').indexVectorsInNBase({ vectorField: 'embedding' });
+// → { indexed: 1200 }
+
+const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
+// hits[0] = { id, title, ..., distance }
+```
+
+Vectors are tagged with their row id, so a hit is hydrated from the table by
+that id and the result keeps the `{ ...row, distance }` shape the other engines
+return.
+
+### Standalone client
+
+```ts
+import { createNBaseVectorClient } from '@an5/adapters/nbase';
+
+const nbase = createNBaseVectorClient({ url: 'http://localhost:1307' });
+await nbase.health();
+await nbase.addVectors([{ id: 'a:1', vector: [0.1, 0.2], metadata: { an5Id: '1' } }]);
+const { results } = await nbase.search([0.1, 0.2], { k: 5, distanceMetric: 'cosine' });
+```
+
+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.
+
+
 ## Usage
 
 ### TypeScript

package/dist/an5Adapter.d.ts

@@ -1,5 +1,6 @@
 import { An5SheetsAdapter, An5SheetsAdapterConfig, SheetsTableClient } from './googlesheets';
 import type { An5AdapterConfig, Dialect, TransactionHandle } from './base/types';
+import { type NBaseAdapterConfig, type NBaseVectorClient } from './nbase';
 export type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from './base/types';
 export { setAdapterMetadata, createAdapterProxy, type AdapterMetadata } from './base/metadata';
 export type { TypedAn5Adapter, AdapterAPI } from './typed';
@@ -13,6 +14,23 @@ export declare class An5Adapter {
     private _engineType;
     private _engineConfig;
     sheetsAdapter: An5SheetsAdapter | null;
+    private _nbase;
+    private _nbaseConfig;
+    private _nbaseOnly;
+    /**
+     * Returns the NBase client for this adapter, if the project configured one.
+     * The connection string may also point straight at NBase, which keeps
+     * `DATABASE_URL=nbase://host:port` working on its own.
+     */
+    nbaseClient(): {
+        client: NBaseVectorClient;
+        config: NBaseAdapterConfig;
+    } | null;
+    /**
+     * True when the adapter only knows about NBase, so there is no relational
+     * database to read rows from.
+     */
+    get nbaseOnly(): boolean;
     get dialect(): Dialect;
     constructor(adapterConfig: An5AdapterConfig | An5SheetsAdapterConfig);
     private requireEngine;
@@ -25,6 +43,15 @@ export declare class An5Adapter {
     $executeRaw(query: string, ...values: any[]): Promise<number>;
     $executeRawUnsafe(query: string, ...values: any[]): Promise<number>;
     $connect(): Promise<void>;
+    /**
+     * Health check for the configured NBase instance, or the database when the
+     * adapter has none.
+     */
+    $nbaseHealth(): Promise<{
+        connected: boolean;
+        endpoint?: string;
+        error?: string;
+    }>;
     $disconnect(): Promise<void>;
     /** Real transaction with BEGIN / COMMIT / ROLLBACK */
     $transaction<R>(fn: (tx: An5AdapterTx) => Promise<R>, options?: {
@@ -179,6 +206,36 @@ export declare class AdapterTableClient<T = any> {
     }): Promise<T>;
     aggregate(args: any): Promise<any>;
     groupBy(args: any): Promise<any[]>;
+    /**
+     * Runs similarity search in NBase and hydrates the matching rows from the
+     * relational table, keeping the `{ ...row, distance }` shape the other
+     * engines return.
+     */
+    private searchViaNBase;
+    /**
+     * Vector search for an adapter configured with only an NBase connection
+     * string. The hit id and metadata are the result, since there is no
+     * relational row to hydrate.
+     */
+    private searchViaNBaseOnly;
+    /** The primary key column registered for this model, falling back to `id`. */
+    private primaryKeyColumn;
+    /** Scalar column names known for this model from the generated metadata. */
+    private modelFields;
+    /**
+     * Pushes a table's embedding column into NBase so it can be searched there.
+     *
+     * Each vector keeps the row id in its metadata, which is what lets
+     * `vectorSearch` return real rows instead of bare vector ids.
+     */
+    indexVectorsInNBase(args?: {
+        vectorField?: string;
+        where?: any;
+        take?: number;
+        batchSize?: number;
+    }): Promise<{
+        indexed: number;
+    }>;
     vectorSearch(args: {
         vector: number[];
         take?: number;

package/dist/an5Adapter.js

@@ -7,6 +7,15 @@ exports.executorFromAdapter = executorFromAdapter;
 const uuid_1 = require("./base/uuid");
 const googlesheets_1 = require("./googlesheets");
 const parseConnectionString_1 = require("./googlesheets/parseConnectionString");
+/**
+ * File extensions that mean SQLite when a connection string has no scheme.
+ *
+ * `.sqlite3` is here as well as in `@an5/orm`'s `detectProvider`, because the ORM
+ * validates field types and writes the DDL from the provider this file picks: if the
+ * two lists differed, a `.sqlite3` file would be pushed as SQL Server DDL.
+ */
+const SQLITE_FILE_SUFFIXES = ['.sqlite', '.sqlite3', '.db'];
+const nbase_1 = require("./nbase");
 const sql_1 = require("./base/sql");
 const metadata_1 = require("./base/metadata");
 var metadata_2 = require("./base/metadata");
@@ -171,6 +180,29 @@ async function resolveIncludes(modelName, rows, include, adapter) {
 }
 // ─── An5Adapter ────────────────────────────────────────────────────────────────────
 class An5Adapter {
+    /**
+     * Returns the NBase client for this adapter, if the project configured one.
+     * The connection string may also point straight at NBase, which keeps
+     * `DATABASE_URL=nbase://host:port` working on its own.
+     */
+    nbaseClient() {
+        if (this._nbase && this._nbaseConfig)
+            return { client: this._nbase, config: this._nbaseConfig };
+        if (!this._nbaseConfig)
+            return null;
+        const config = this._nbaseConfig;
+        const client = (0, nbase_1.createNBaseVectorClient)(config);
+        this._nbase = client;
+        this._nbaseConfig = config;
+        return { client, config };
+    }
+    /**
+     * True when the adapter only knows about NBase, so there is no relational
+     * database to read rows from.
+     */
+    get nbaseOnly() {
+        return this._nbaseOnly === true;
+    }
     get dialect() {
         if (this.sheetsAdapter)
             return 'googlesheets';
@@ -189,12 +221,32 @@ class An5Adapter {
         this._engineType = null;
         this._engineConfig = null;
         this.sheetsAdapter = null;
+        this._nbase = null;
+        this._nbaseConfig = null;
+        this._nbaseOnly = false;
         this._listeners = {};
         this._middlewares = [];
         if (isSheetsConfig(adapterConfig)) {
             this.sheetsAdapter = new googlesheets_1.An5SheetsAdapter(adapterConfig);
             return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
         }
+        // Keep the config even when the caller supplies its own engine: the NBase
+        // settings and anything else on the config are read from it later.
+        this._engineConfig = adapterConfig;
+        // `nbase://host:port` as the connection string configures the vector store
+        // on its own: there is no relational database, so the adapter is
+        // vector-only. The same string passed as `nbase` keeps the database from
+        // `connectionString` as the source of rows.
+        const rawConnectionString = String(this._engineConfig.connectionString ?? '').trim();
+        if ((0, nbase_1.isNBaseConnectionString)(rawConnectionString)) {
+            this._nbaseConfig = (0, nbase_1.parseNBaseConnectionString)(rawConnectionString);
+            this._nbaseOnly = true;
+            return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
+        }
+        const attached = this._engineConfig.nbase;
+        if (attached && (0, nbase_1.isNBaseConnectionString)(attached)) {
+            this._nbaseConfig = (0, nbase_1.parseNBaseConnectionString)(attached);
+        }
         if (adapterConfig.engine) {
             this._engine = adapterConfig.engine;
             this._engineType = this._engine?.dialect || 'sqlite';
@@ -206,19 +258,26 @@ class An5Adapter {
             this._engineType = 'sqlite';
             return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
         }
+        // Lower-cased for the dialect test only; the connection string itself keeps its
+        // case for the driver. A URI scheme is case-insensitive, and `@an5/orm` reads the
+        // provider the same way to validate field types and write DDL — if the two
+        // disagreed, a schema would be checked against one database and run on another.
         const cs = (adapterConfig.connectionString || '').trim();
-        if (cs.startsWith('googlesheets://')) {
+        const forDialect = cs.toLowerCase();
+        if (forDialect.startsWith('googlesheets://')) {
             this.sheetsAdapter = new googlesheets_1.An5SheetsAdapter((0, parseConnectionString_1.parseSheetsConnectionString)(cs));
             return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
         }
         this._engineConfig = adapterConfig;
-        if (cs.startsWith('postgres://') || cs.startsWith('postgresql://')) {
+        if (forDialect.startsWith('postgres://') || forDialect.startsWith('postgresql://')) {
             this._engineType = 'postgres';
         }
-        else if (cs.startsWith('mysql://') || cs.startsWith('mariadb://')) {
+        else if (forDialect.startsWith('mysql://') || forDialect.startsWith('mariadb://')) {
             this._engineType = 'mysql';
         }
-        else if (cs.startsWith('sqlite://') || cs.endsWith('.sqlite') || cs.endsWith('.db')) {
+        else if (forDialect === ':memory:'
+            || forDialect.startsWith('sqlite:')
+            || SQLITE_FILE_SUFFIXES.some((suffix) => forDialect.endsWith(suffix))) {
             this._engineType = 'sqlite';
         }
         else {
@@ -310,8 +369,36 @@ class An5Adapter {
     async $connect() {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$connect();
+        if (this._nbaseOnly) {
+            // NBase is stateless over HTTP, so there is nothing to open. Report the
+            // endpoint so a misconfiguration is obvious.
+            const config = this.nbaseClient()?.config;
+            if (config)
+                await this.nbaseClient().client.health();
+            return;
+        }
         await (await this.requireEngine()).connect();
     }
+    /**
+     * Health check for the configured NBase instance, or the database when the
+     * adapter has none.
+     */
+    async $nbaseHealth() {
+        const nbase = this.nbaseClient();
+        if (!nbase)
+            return { connected: false, error: 'No NBase instance configured.' };
+        try {
+            const health = await nbase.client.health();
+            return { connected: health.status === 'ok', endpoint: nbase.config.url };
+        }
+        catch (err) {
+            return {
+                connected: false,
+                endpoint: nbase.config.url,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
     async $disconnect() {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$disconnect();
@@ -1001,6 +1088,158 @@ class AdapterTableClient {
         }
         return this.doExec(query, params);
     }
+    /**
+     * Runs similarity search in NBase and hydrates the matching rows from the
+     * relational table, keeping the `{ ...row, distance }` shape the other
+     * engines return.
+     */
+    async searchViaNBase(nbase, args, metric, take) {
+        const { client, config } = nbase;
+        const idField = config.idField ?? 'an5Id';
+        const modelField = config.modelField ?? 'an5Model';
+        const results = await client.search(args.vector, {
+            k: take,
+            // NBase implements cosine and euclidean; a dot-product request falls back
+            // to cosine, which still orders the results sensibly.
+            distanceMetric: metric === 'euclidean' ? 'euclidean' : 'cosine',
+            includeMetadata: true,
+            ...(config.method ? { method: config.method } : {}),
+        });
+        // Map each hit back to its row id. Ids are written as `Model:id`, and the
+        // metadata key is honoured for projects that index vectors themselves.
+        const ids = [];
+        const distances = new Map();
+        for (const hit of results) {
+            const fromMetadata = hit.metadata?.[idField];
+            const rawId = fromMetadata !== undefined && fromMetadata !== null
+                ? String(fromMetadata)
+                : (0, nbase_1.parseVectorId)(hit.id).id;
+            if (!rawId)
+                continue;
+            const model = hit.metadata?.[modelField] ?? (0, nbase_1.parseVectorId)(hit.id).model;
+            ids.push(model === this.modelName ? rawId : `${model}:${rawId}`);
+            distances.set(ids[ids.length - 1], hit.dist);
+        }
+        if (ids.length === 0)
+            return [];
+        const pk = this.primaryKeyColumn();
+        const inList = ids.map((_, i) => `@nbase_id_${i}`).join(', ');
+        const idParams = {};
+        ids.forEach((id, i) => { idParams[`nbase_id_${i}`] = id; });
+        idParams.take = take;
+        const selectColumns = this.modelFields().map((f) => (0, sql_1.quote)(f, this.dialect)).join(', ');
+        const columns = selectColumns ? `${selectColumns}, ${(0, sql_1.quote)(pk, this.dialect)} AS __an5_nbase_key` : `${(0, sql_1.quote)(pk, this.dialect)} AS __an5_nbase_key`;
+        const query = `SELECT ${columns} FROM ${this.tableName} WHERE ${(0, sql_1.quote)(pk, this.dialect)} IN (${inList})`;
+        const rows = await this.adapter.exec(query, idParams);
+        const byKey = new Map();
+        for (const row of rows ?? []) {
+            byKey.set(String(row.__an5_nbase_key), row);
+        }
+        const hydrated = [];
+        for (const id of ids) {
+            const row = byKey.get(id);
+            if (!row)
+                continue;
+            const { __an5_nbase_key, ...rest } = row;
+            hydrated.push({ ...rest, distance: distances.get(id) ?? 0 });
+            if (hydrated.length >= take)
+                break;
+        }
+        return hydrated;
+    }
+    /**
+     * Vector search for an adapter configured with only an NBase connection
+     * string. The hit id and metadata are the result, since there is no
+     * relational row to hydrate.
+     */
+    async searchViaNBaseOnly(nbase, args, metric, take) {
+        const { client, config } = nbase;
+        const idField = config.idField ?? 'an5Id';
+        const results = await client.search(args.vector, {
+            k: take,
+            distanceMetric: metric === 'euclidean' ? 'euclidean' : 'cosine',
+            includeMetadata: true,
+            ...(config.method ? { method: config.method } : {}),
+        });
+        return results.map((hit) => {
+            const metadata = { ...(hit.metadata ?? {}) };
+            if (metadata[idField] === undefined) {
+                const parsed = (0, nbase_1.parseVectorId)(hit.id);
+                if (parsed.id)
+                    metadata[idField] = parsed.id;
+                if (parsed.model)
+                    metadata[config.modelField ?? 'an5Model'] = parsed.model;
+            }
+            return { id: hit.id, ...metadata, distance: hit.dist };
+        });
+    }
+    /** The primary key column registered for this model, falling back to `id`. */
+    primaryKeyColumn() {
+        const fields = this.modelFields();
+        const marked = fields.find((f) => f === 'id');
+        return marked ?? fields[0] ?? 'id';
+    }
+    /** Scalar column names known for this model from the generated metadata. */
+    modelFields() {
+        const fields = (0, metadata_1.getFieldsForModel)(this.modelName);
+        if (fields && typeof fields === 'object' && !Array.isArray(fields)) {
+            return Object.keys(fields);
+        }
+        return [];
+    }
+    /**
+     * Pushes a table's embedding column into NBase so it can be searched there.
+     *
+     * Each vector keeps the row id in its metadata, which is what lets
+     * `vectorSearch` return real rows instead of bare vector ids.
+     */
+    async indexVectorsInNBase(args = {}) {
+        const nbase = this.adapter.nbaseClient?.() ?? null;
+        if (!nbase) {
+            throw new Error('No NBase instance configured. Use a nbase:// connection string, e.g. createAn5Adapter({ connectionString: "nbase://localhost:1307" }).');
+        }
+        if (this.adapter.nbaseOnly) {
+            throw new Error('indexVectorsInNBase reads the vectors from a table, but this adapter was created with an nbase:// connection string and has no database. ' +
+                'Create the adapter with your database connection string to index, or add the vectors with the NBase client directly.');
+        }
+        const vectorField = args.vectorField || 'embedding';
+        const batchSize = args.batchSize ?? 200;
+        const pk = this.primaryKeyColumn();
+        const rows = await this.findMany({ ...(args.where ? { where: args.where } : {}), ...(args.take ? { take: args.take } : {}) });
+        let indexed = 0;
+        for (let i = 0; i < rows.length; i += batchSize) {
+            const batch = rows.slice(i, i + batchSize);
+            const vectors = batch
+                .map((row) => {
+                const raw = row[vectorField];
+                if (raw === undefined || raw === null)
+                    return null;
+                let vector;
+                try {
+                    vector = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                }
+                catch {
+                    return null;
+                }
+                if (!Array.isArray(vector) || vector.length === 0)
+                    return null;
+                return {
+                    id: (0, nbase_1.buildVectorId)(this.modelName, String(row[pk])),
+                    vector,
+                    metadata: {
+                        [nbase.config.idField ?? 'an5Id']: String(row[pk]),
+                        [nbase.config.modelField ?? 'an5Model']: this.modelName,
+                    },
+                };
+            })
+                .filter((v) => v !== null);
+            if (vectors.length === 0)
+                continue;
+            const result = await nbase.client.addVectors(vectors);
+            indexed += result.count;
+        }
+        return { indexed };
+    }
     async vectorSearch(args) {
         const vectorField = args.vectorField || 'embedding';
         const METRICS = ['cosine', 'euclidean', 'dot'];
@@ -1012,6 +1251,26 @@ class AdapterTableClient {
         const vectorJson = JSON.stringify(args.vector);
         const col = (0, sql_1.quote)(vectorField, this.dialect);
         const params = { query_vector: vectorJson };
+        // 0. NBase, when the project configured one: the vectors live in the vector
+        //    database, so the search never loads the table into memory.
+        const nbase = this.adapter.nbaseClient?.() ?? null;
+        if (nbase) {
+            try {
+                // With an NBase-only connection string there is no table to read rows
+                // from, so the hits are returned as the vector metadata itself.
+                if (this.adapter.nbaseOnly) {
+                    return (await this.searchViaNBaseOnly(nbase, args, metric, take));
+                }
+                return await this.searchViaNBase(nbase, args, metric, take);
+            }
+            catch (err) {
+                if (!(err instanceof nbase_1.NBaseError))
+                    throw err;
+                // A NBase outage must not take vector search down with it; fall through
+                // to the database instead of failing the query.
+                console.warn(`[an5] NBase vector search unavailable (${err.message}); falling back to ${this.dialect}.`);
+            }
+        }
         // 1. Try native dialect execution
         if (this.dialect === 'postgres') {
             const op = metric === 'cosine' ? '<=>' : metric === 'dot' ? '<#>' : '<->';

package/dist/base/sql.js

@@ -68,9 +68,10 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
     if (!where)
         return '';
     const conditions = [];
+    const relations = ctx?.relationMap?.[modelName] || {};
     const cleanWhere = {};
     for (const [key, value] of Object.entries(where)) {
-        if (key.includes('_') &&
+        if (key.includes('_') && !relations[key] &&
             value && typeof value === 'object' &&
             !(value instanceof Date) &&
             !isOperatorValue(value)) {
@@ -80,13 +81,13 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
             cleanWhere[key] = value;
         }
     }
-    const relations = ctx?.relationMap?.[modelName] || {};
     const colPrefix = ctx?.colPrefix || '';
     for (const [key, value] of Object.entries(cleanWhere)) {
+        if (value === undefined)
+            continue;
         if (key === 'OR' && Array.isArray(value)) {
-            const sub = value.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}or_${i}_`, ctx)).filter(Boolean);
-            if (sub.length > 0)
-                conditions.push(`(${sub.join(' OR ')})`);
+            const sub = value.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}or_${i}_`, ctx) || '1=1');
+            conditions.push(sub.length > 0 ? `(${sub.join(' OR ')})` : '1=0');
         }
         else if (key === 'AND') {
             const items = Array.isArray(value) ? value : [value];
@@ -96,12 +97,12 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
         }
         else if (key === 'NOT') {
             const items = Array.isArray(value) ? value : [value];
-            const sub = items.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}not_${i}_`, ctx)).filter(Boolean);
+            const sub = items.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}not_${i}_`, ctx) || '1=1');
             if (sub.length > 0)
-                conditions.push(`NOT (${sub.join(' AND ')})`);
+                conditions.push(`NOT (${sub.join(' OR ')})`);
         }
         else if (relations[key] && value && typeof value === 'object') {
-            const clause = buildRelationClause(relations[key], value, modelName, params, dialect, prefix, ctx);
+            const clause = buildRelationClause(relations[key], value, modelName, params, dialect, `${prefix}${key}_`, ctx);
             if (clause)
                 conditions.push(clause);
         }
@@ -220,16 +221,16 @@ function buildRelationClause(relation, value, modelName, params, dialect, prefix
     const parts = [];
     if (isMany) {
         if (value.some !== undefined) {
-            const inner = buildInnerWhere(relation.modelName, value.some === null ? {} : value.some, params, dialect, prefix, ctx, childAlias);
+            const inner = buildInnerWhere(relation.modelName, value.some === null ? {} : value.some, params, dialect, `${prefix}some_`, ctx, childAlias);
             parts.push(buildExists(inner));
         }
         if (value.none !== undefined) {
-            const inner = buildInnerWhere(relation.modelName, value.none === null ? {} : value.none, params, dialect, prefix, ctx, childAlias);
+            const inner = buildInnerWhere(relation.modelName, value.none === null ? {} : value.none, params, dialect, `${prefix}none_`, ctx, childAlias);
             parts.push(`NOT ${buildExists(inner)}`);
         }
         if (value.every !== undefined) {
             // "every" = no related row violates the condition.
-            const inner = buildInnerWhere(relation.modelName, value.every === null ? {} : value.every, params, dialect, prefix, ctx, childAlias);
+            const inner = buildInnerWhere(relation.modelName, value.every === null ? {} : value.every, params, dialect, `${prefix}every_`, ctx, childAlias);
             const negated = inner ? `NOT (${inner})` : '';
             const violated = `EXISTS (SELECT 1 FROM ${childTable} AS ${childAlias} WHERE ${correlation}${negated ? ` AND ${negated}` : ' AND 1=0'})`;
             parts.push(`NOT ${violated}`);
@@ -237,12 +238,12 @@ function buildRelationClause(relation, value, modelName, params, dialect, prefix
     }
     else {
         if (value.is !== undefined) {
-            const inner = buildInnerWhere(relation.modelName, value.is === null ? {} : value.is, params, dialect, prefix, ctx, childAlias);
-            parts.push(buildExists(inner));
+            const inner = buildInnerWhere(relation.modelName, value.is === null ? {} : value.is, params, dialect, `${prefix}is_`, ctx, childAlias);
+            parts.push(value.is === null ? `NOT ${buildExists(inner)}` : buildExists(inner));
         }
         if (value.isNot !== undefined) {
-            const inner = buildInnerWhere(relation.modelName, value.isNot === null ? {} : value.isNot, params, dialect, prefix, ctx, childAlias);
-            parts.push(`NOT ${buildExists(inner)}`);
+            const inner = buildInnerWhere(relation.modelName, value.isNot === null ? {} : value.isNot, params, dialect, `${prefix}isNot_`, ctx, childAlias);
+            parts.push(value.isNot === null ? buildExists(inner) : `NOT ${buildExists(inner)}`);
         }
     }
     return parts.length > 0 ? parts.join(' AND ') : null;

package/dist/base/types.d.ts

@@ -1,6 +1,12 @@
 export type Dialect = 'mssql' | 'postgres' | 'mysql' | 'sqlite' | 'googlesheets';
 export interface An5AdapterConfig {
     connectionString?: string;
+    /**
+     * NBase (Neural Vector Database) endpoint, written as a connection string,
+     * e.g. `nbase://localhost:1307`. Attach it here when vector search should
+     * run in NBase while the rows stay in `connectionString`'s database.
+     */
+    nbase?: string;
     engine?: QueryEngine;
     db?: any;
     driver?: any;