@memberjunction/ai-vectordb 5.38.0 → 5.39.0

package/dist/generic/VectorDBBase.d.ts

@@ -2,6 +2,7 @@ import { UserInfo } from '@memberjunction/core';
 import { BaseRequestParams, BaseResponse, CreateIndexParams, EditIndexParams, IndexList, ListVectorIDsParams, ListVectorIDsResult, UpdateOptions, VectorRecord } from "./record.js";
 import { HybridQueryOptions, QueryOptions } from './query.types.js';
 import { SharedIndexFilterOptions } from './MetadataFilter.js';
+import { ColocatedQueryOptions, ColocatedQueryResult, IColocatedVectorHost } from './colocated.types.js';
 export declare abstract class VectorDBBase {
     private _apiKey;
     /**
@@ -9,6 +10,17 @@ export declare abstract class VectorDBBase {
      */
     protected get ApiKey(): string;
     constructor(apiKey: string);
+    /**
+     * True when this driver does not accept ingestion via `CreateRecord(s)` /
+     * `UpdateRecord(s)` — implies vectors are managed out-of-band (e.g.
+     * `SimpleVectorServiceProvider` reads embeddings directly from
+     * `MJ: Entity Record Documents.VectorJSON`). Pipelines that would
+     * otherwise call ingestion APIs should short-circuit when this is true
+     * to avoid spurious "unsupported" error logs.
+     *
+     * Subclasses that genuinely support ingestion leave the default `false`.
+     */
+    get IsReadOnly(): boolean;
     abstract ListIndexes(): IndexList | Promise<IndexList>;
     abstract GetIndex(params: BaseRequestParams): BaseResponse | Promise<BaseResponse>;
     abstract CreateIndex(params: CreateIndexParams): BaseResponse | Promise<BaseResponse>;
@@ -84,5 +96,55 @@ export declare abstract class VectorDBBase {
      * @returns A native filter object, or undefined if no filters
      */
     BuildMetadataFilter(options: SharedIndexFilterOptions): object | undefined;
+    /**
+     * The host relational connection a colocated provider borrows to store and query
+     * vectors in the same database as the application's entity data. `undefined` until
+     * {@link SetColocatedHost} (or {@link TryWireColocatedHost}) is called.
+     */
+    protected ColocatedHost: IColocatedVectorHost | undefined;
+    /**
+     * Whether this provider stores vectors inside the application's relational database and
+     * can resolve query results to entity records without an external mapping hop. Override
+     * and return `true` in colocated providers (e.g. `PgVectorColocated`, `SQLServerVectorDatabase`).
+     */
+    get SupportsColocatedQuery(): boolean;
+    /**
+     * Wire in the host relational connection so this provider reuses it for colocated
+     * storage and queries instead of opening its own pool. No-op semantics for providers
+     * that ignore it; colocated providers require it before any operation.
+     */
+    SetColocatedHost(host: IColocatedVectorHost): void;
+    /**
+     * Convenience used by callers that hold an opaque provider reference (the active MJ data
+     * provider). If `host` implements {@link IColocatedVectorHost} *and* this provider supports
+     * colocated queries, wire it in.
+     *
+     * @returns `true` if the host was wired in, `false` otherwise.
+     */
+    TryWireColocatedHost(host: unknown): boolean;
+    /**
+     * Run a colocated query that fuses a vector component with an optional keyword component
+     * in a single server-side statement, applying an optional metadata filter. Only meaningful
+     * when {@link SupportsColocatedQuery} is `true`; the default implementation throws to surface
+     * misuse on providers that don't support it.
+     */
+    ColocatedQuery(_params: ColocatedQueryOptions, _contextUser?: UserInfo): Promise<ColocatedQueryResult>;
+    /**
+     * Build a standard SUCCESS {@link BaseResponse}. Shared across all drivers so every
+     * provider reports results in a uniform shape.
+     *
+     * @param data - The provider-specific payload to attach to the response.
+     */
+    protected wrapSuccessResponse(data: unknown): BaseResponse;
+    /**
+     * Build a standard FAILURE {@link BaseResponse}.
+     *
+     * **Always** return this (never a success response) from a `catch` block — returning a
+     * success response on error silently swallows real failures and makes callers, and the
+     * vectorization pipeline, believe an operation worked when it did not.
+     *
+     * @param message - Optional human-readable error detail; falls back to a generic message.
+     */
+    protected wrapFailureResponse(message?: string): BaseResponse;
 }
 //# sourceMappingURL=VectorDBBase.d.ts.map

package/dist/generic/VectorDBBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VectorDBBase.d.ts","sourceRoot":"","sources":["../../src/generic/VectorDBBase.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"VectorDBBase.d.ts","sourceRoot":"","sources":["../../src/generic/VectorDBBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,iBAAiB,EACnD,eAAe,EAAE,SAAS,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,aAAa,EACnF,YAAY,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAwB,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAyB,MAAM,mBAAmB,CAAC;AAE7H,8BAAsB,YAAY;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB;;OAEG;IACH,SAAS,KAAK,MAAM,IAAI,MAAM,CAE7B;gBAEY,MAAM,EAAE,MAAM;IAO3B;;;;;;;;;OASG;IACH,IAAW,UAAU,IAAI,OAAO,CAE/B;IAGD,QAAQ,CAAC,WAAW,IAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACtD,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAClF,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IAClF;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,WAAW,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAEvG,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACrG,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IAC1G,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACnF,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACnF,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACrF,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IACtG,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAI,OAAO,CAAC,YAAY,CAAC;IAE1G;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAEtG;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAEjF;;;OAGG;IACH,IAAW,oBAAoB,IAAI,OAAO,CAEzC;IAED;;;;OAIG;IACI,WAAW,CAAC,MAAM,EAAE,kBAAkB,EAAE,WAAW,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAK5G;;;;;;;;;OASG;IACI,qBAAqB,CACxB,MAAM,EAAE,YAAY,GAAG;QAAE,cAAc,EAAE,wBAAwB,CAAA;KAAE,EACnE,WAAW,CAAC,EAAE,QAAQ,GACvB,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAWvC;;;;;;;;OAQG;IACI,mBAAmB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,GAAG,SAAS;IAQjF;;;;OAIG;IACH,SAAS,CAAC,aAAa,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAE1D;;;;OAIG;IACH,IAAW,sBAAsB,IAAI,OAAO,CAE3C;IAED;;;;OAIG;IACI,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAIzD;;;;;;OAMG;IACI,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;IAQnD;;;;;OAKG;IACI,cAAc,CAAC,OAAO,EAAE,qBAAqB,EAAE,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI7G;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY;IAQ1D;;;;;;;;OAQG;IACH,SAAS,CAAC,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY;CAOhE"}

package/dist/generic/VectorDBBase.js

@@ -1,4 +1,5 @@
 import { VectorMetadataFilter } from './MetadataFilter.js';
+import { IsColocatedVectorHost } from './colocated.types.js';
 export class VectorDBBase {
     /**
      * Only sub-classes can access the API key
@@ -11,6 +12,19 @@ export class VectorDBBase {
             throw new Error('API key cannot be empty');
         this._apiKey = apiKey;
     }
+    /**
+     * True when this driver does not accept ingestion via `CreateRecord(s)` /
+     * `UpdateRecord(s)` — implies vectors are managed out-of-band (e.g.
+     * `SimpleVectorServiceProvider` reads embeddings directly from
+     * `MJ: Entity Record Documents.VectorJSON`). Pipelines that would
+     * otherwise call ingestion APIs should short-circuit when this is true
+     * to avoid spurious "unsupported" error logs.
+     *
+     * Subclasses that genuinely support ingestion leave the default `false`.
+     */
+    get IsReadOnly() {
+        return false;
+    }
     /**
      * Whether this provider supports hybrid (vector + keyword) search.
      * Override and return true in providers that implement HybridQuery().
@@ -59,5 +73,73 @@ export class VectorDBBase {
     BuildMetadataFilter(options) {
         return VectorMetadataFilter.FromOptions(options);
     }
+    /**
+     * Whether this provider stores vectors inside the application's relational database and
+     * can resolve query results to entity records without an external mapping hop. Override
+     * and return `true` in colocated providers (e.g. `PgVectorColocated`, `SQLServerVectorDatabase`).
+     */
+    get SupportsColocatedQuery() {
+        return false;
+    }
+    /**
+     * Wire in the host relational connection so this provider reuses it for colocated
+     * storage and queries instead of opening its own pool. No-op semantics for providers
+     * that ignore it; colocated providers require it before any operation.
+     */
+    SetColocatedHost(host) {
+        this.ColocatedHost = host;
+    }
+    /**
+     * Convenience used by callers that hold an opaque provider reference (the active MJ data
+     * provider). If `host` implements {@link IColocatedVectorHost} *and* this provider supports
+     * colocated queries, wire it in.
+     *
+     * @returns `true` if the host was wired in, `false` otherwise.
+     */
+    TryWireColocatedHost(host) {
+        if (this.SupportsColocatedQuery && IsColocatedVectorHost(host)) {
+            this.SetColocatedHost(host);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Run a colocated query that fuses a vector component with an optional keyword component
+     * in a single server-side statement, applying an optional metadata filter. Only meaningful
+     * when {@link SupportsColocatedQuery} is `true`; the default implementation throws to surface
+     * misuse on providers that don't support it.
+     */
+    ColocatedQuery(_params, _contextUser) {
+        return Promise.reject(new Error('ColocatedQuery is not supported by this provider (SupportsColocatedQuery is false)'));
+    }
+    /**
+     * Build a standard SUCCESS {@link BaseResponse}. Shared across all drivers so every
+     * provider reports results in a uniform shape.
+     *
+     * @param data - The provider-specific payload to attach to the response.
+     */
+    wrapSuccessResponse(data) {
+        return {
+            success: true,
+            message: '',
+            data,
+        };
+    }
+    /**
+     * Build a standard FAILURE {@link BaseResponse}.
+     *
+     * **Always** return this (never a success response) from a `catch` block — returning a
+     * success response on error silently swallows real failures and makes callers, and the
+     * vectorization pipeline, believe an operation worked when it did not.
+     *
+     * @param message - Optional human-readable error detail; falls back to a generic message.
+     */
+    wrapFailureResponse(message) {
+        return {
+            success: false,
+            message: message || 'An error occurred',
+            data: null,
+        };
+    }
 }
 //# sourceMappingURL=VectorDBBase.js.map

package/dist/generic/VectorDBBase.js.map

@@ -1 +1 @@
-{"version":3,"file":"VectorDBBase.js","sourceRoot":"","sources":["../../src/generic/VectorDBBase.ts"],"names":[],"mappings":"AAKA,OAAO,EAA4B,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAElF,MAAM,OAAgB,YAAY;IAE9B;;OAEG;IACH,IAAc,MAAM;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,YAAa,MAAc;QACvB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAE/C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IAC1B,CAAC;IAgDD;;;OAGG;IACH,IAAW,oBAAoB;QAC3B,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACI,WAAW,CAAC,MAA0B,EAAE,WAAsB;QACjE,oEAAoE;QACpE,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC;IAC3L,CAAC;IAED;;;;;;;;;OASG;IACI,qBAAqB,CACxB,MAAmE,EACnE,WAAsB;QAEtB,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QACrE,MAAM,WAAW,GAAiB;YAC9B,GAAG,MAAM;YACT,MAAM,EAAE,YAAY,IAAI,MAAM,CAAC,MAAM;SACxC,CAAC;QACF,yDAAyD;QACzD,OAAQ,WAAuC,CAAC,gBAAgB,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;OAQG;IACI,mBAAmB,CAAC,OAAiC;QACxD,OAAO,oBAAoB,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC;CACJ"}
+{"version":3,"file":"VectorDBBase.js","sourceRoot":"","sources":["../../src/generic/VectorDBBase.ts"],"names":[],"mappings":"AAKA,OAAO,EAA4B,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAqE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE7H,MAAM,OAAgB,YAAY;IAE9B;;OAEG;IACH,IAAc,MAAM;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,YAAa,MAAc;QACvB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAE/C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IAC1B,CAAC;IAED;;;;;;;;;OASG;IACH,IAAW,UAAU;QACjB,OAAO,KAAK,CAAC;IACjB,CAAC;IAgDD;;;OAGG;IACH,IAAW,oBAAoB;QAC3B,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACI,WAAW,CAAC,MAA0B,EAAE,WAAsB;QACjE,oEAAoE;QACpE,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC;IAC3L,CAAC;IAED;;;;;;;;;OASG;IACI,qBAAqB,CACxB,MAAmE,EACnE,WAAsB;QAEtB,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QACrE,MAAM,WAAW,GAAiB;YAC9B,GAAG,MAAM;YACT,MAAM,EAAE,YAAY,IAAI,MAAM,CAAC,MAAM;SACxC,CAAC;QACF,yDAAyD;QACzD,OAAQ,WAAuC,CAAC,gBAAgB,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;OAQG;IACI,mBAAmB,CAAC,OAAiC;QACxD,OAAO,oBAAoB,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC;IAaD;;;;OAIG;IACH,IAAW,sBAAsB;QAC7B,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACI,gBAAgB,CAAC,IAA0B;QAC9C,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACI,oBAAoB,CAAC,IAAa;QACrC,IAAI,IAAI,CAAC,sBAAsB,IAAI,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7D,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAC5B,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACI,cAAc,CAAC,OAA8B,EAAE,YAAuB;QACzE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,oFAAoF,CAAC,CAAC,CAAC;IAC3H,CAAC;IAED;;;;;OAKG;IACO,mBAAmB,CAAC,IAAa;QACvC,OAAO;YACH,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,EAAE;YACX,IAAI;SACP,CAAC;IACN,CAAC;IAED;;;;;;;;OAQG;IACO,mBAAmB,CAAC,OAAgB;QAC1C,OAAO;YACH,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,OAAO,IAAI,mBAAmB;YACvC,IAAI,EAAE,IAAI;SACb,CAAC;IACN,CAAC;CACJ"}

package/dist/generic/colocated.types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Types and contracts for **colocated** vector search — the case where the
+ * application's relational database is *also* the vector store (PostgreSQL + pgvector, or
+ * SQL Server 2025 native vectors), rather than a separate remote service (Pinecone, Qdrant).
+ *
+ * A colocated provider borrows the host data provider's connection via {@link IColocatedVectorHost}
+ * instead of opening its own pool. This gives three properties a foreign store cannot:
+ *   1. one connection / one credential, and the same transaction as the entity write;
+ *   2. results resolve to entity records without a second round-trip;
+ *   3. true hybrid search (vector + keyword + filter) fused server-side in a single query.
+ *
+ * @module @memberjunction/ai-vectordb
+ */
+import type { DatabasePlatform } from '@memberjunction/sql-dialect';
+/**
+ * Validate that `name` is a safe SQL identifier (schema, table, column) and return it unchanged.
+ * Throws otherwise. Colocated providers build raw SQL with these identifiers interpolated (they
+ * bypass the data providers' auto-quoting), and the values can originate from admin-supplied
+ * `MJVectorIndex.ProviderConfig` — so every interpolated identifier is validated against an
+ * allow-list rather than "cleaned", which would silently alter it and still miss escape vectors.
+ */
+export declare function ValidateSqlIdentifier(name: string, kind?: string): string;
+/**
+ * Contract a relational data provider implements so a colocated vector provider can borrow
+ * its connection — running vector DDL/DML in the SAME database (and, when a transaction is
+ * open, the same transaction) as the application's entity data.
+ *
+ * Implemented by `SQLServerDataProvider` / `PostgreSQLDataProvider`. When a host is wired in,
+ * the vector provider never opens its own pool.
+ */
+export interface IColocatedVectorHost {
+    /** Which SQL platform this host speaks — selects the colocated provider's SQL/placeholder syntax.
+     *  Reuses the canonical {@link DatabasePlatform} from `@memberjunction/sql-dialect`. */
+    readonly ColocatedDialect: DatabasePlatform;
+    /** Default schema where MJ entity tables/views live (e.g. `"__mj"`). */
+    readonly ColocatedSchema: string;
+    /**
+     * Execute a parameterized statement against the host connection and return result rows.
+     * Placeholders use the host dialect's native convention: `$1..$n` (PostgreSQL) or
+     * `@p0..@pN` (SQL Server). Params are positional; index `i` maps to `$${i+1}` / `@p${i}`.
+     */
+    RunColocatedSQL<T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>): Promise<T[]>;
+}
+/**
+ * Runtime type guard for {@link IColocatedVectorHost}. Structural so a data provider can
+ * satisfy the contract without `ai-vectordb` having to import the data-provider package.
+ */
+export declare function IsColocatedVectorHost(obj: unknown): obj is IColocatedVectorHost;
+/** How a colocated provider fuses the vector and keyword result lists in a hybrid query. */
+export type ColocatedFusion = 'rrf' | 'vector-only' | 'keyword-only';
+/**
+ * Options for a colocated query — a vector component, an optional keyword component, fused
+ * together, with an optional metadata filter. Distinct from {@link QueryOptions} because it
+ * carries the keyword + fusion controls and is answered in a single server-side statement.
+ */
+export interface ColocatedQueryOptions {
+    /** Index (table) name. */
+    indexName: string;
+    /** Query embedding. Optional only when {@link keyword} is supplied (keyword-only search). */
+    vector?: number[];
+    /** Keyword string for the full-text component of a hybrid query. */
+    keyword?: string;
+    /** Maximum results to return. */
+    topK: number;
+    /** Metadata filter — same shape accepted by `QueryOptions.filter`. */
+    filter?: object;
+    /**
+     * Fusion strategy. Defaults to `'rrf'` when both a vector and a keyword are present,
+     * otherwise the single available component is used.
+     */
+    fusion?: ColocatedFusion;
+    /** Include raw embedding values with each match (default false). */
+    includeValues?: boolean;
+    /** Include stored metadata with each match (default true). */
+    includeMetadata?: boolean;
+}
+/** A single match from a colocated query. */
+export interface ColocatedMatch {
+    /** Vector record id, stored in `CompositeKey` URL format to mirror the external providers. */
+    id: string;
+    /** Fused relevance score; higher is more relevant regardless of the underlying metric. */
+    score: number;
+    /** Stored metadata, present when `includeMetadata` is true. */
+    metadata?: Record<string, string | number | boolean | string[]>;
+    /** Embedding values, present when `includeValues` is true. */
+    values?: number[];
+}
+/** Result of a colocated query. */
+export interface ColocatedQueryResult {
+    matches: ColocatedMatch[];
+}
+//# sourceMappingURL=colocated.types.d.ts.map

package/dist/generic/colocated.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colocated.types.d.ts","sourceRoot":"","sources":["../../src/generic/colocated.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAKpE;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAe,GAAG,MAAM,CAK/E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACjC;4FACwF;IACxF,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,eAAe,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CAC5G;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,oBAAoB,CAU/E;AAED,4FAA4F;AAC5F,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,aAAa,GAAG,cAAc,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IAClC,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,oEAAoE;IACpE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC3B,8FAA8F;IAC9F,EAAE,EAAE,MAAM,CAAC;IACX,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAC;IAChE,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,mCAAmC;AACnC,MAAM,WAAW,oBAAoB;IACjC,OAAO,EAAE,cAAc,EAAE,CAAC;CAC7B"}

package/dist/generic/colocated.types.js

@@ -0,0 +1,31 @@
+/** Matches a safe, unquoted SQL identifier: a letter/underscore followed by word characters. */
+const SQL_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Validate that `name` is a safe SQL identifier (schema, table, column) and return it unchanged.
+ * Throws otherwise. Colocated providers build raw SQL with these identifiers interpolated (they
+ * bypass the data providers' auto-quoting), and the values can originate from admin-supplied
+ * `MJVectorIndex.ProviderConfig` — so every interpolated identifier is validated against an
+ * allow-list rather than "cleaned", which would silently alter it and still miss escape vectors.
+ */
+export function ValidateSqlIdentifier(name, kind = 'identifier') {
+    if (typeof name !== 'string' || !SQL_IDENTIFIER_PATTERN.test(name)) {
+        throw new Error(`Invalid SQL ${kind}: ${JSON.stringify(name)} (must match ${SQL_IDENTIFIER_PATTERN}).`);
+    }
+    return name;
+}
+/**
+ * Runtime type guard for {@link IColocatedVectorHost}. Structural so a data provider can
+ * satisfy the contract without `ai-vectordb` having to import the data-provider package.
+ */
+export function IsColocatedVectorHost(obj) {
+    if (!obj || typeof obj !== 'object') {
+        return false;
+    }
+    const o = obj;
+    // Structural check only — don't enumerate specific platforms, so this stays correct as
+    // DatabasePlatform grows. The compile-time type enforces the valid platform set.
+    return typeof o['ColocatedDialect'] === 'string'
+        && typeof o['ColocatedSchema'] === 'string'
+        && typeof o['RunColocatedSQL'] === 'function';
+}
+//# sourceMappingURL=colocated.types.js.map

package/dist/generic/colocated.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colocated.types.js","sourceRoot":"","sources":["../../src/generic/colocated.types.ts"],"names":[],"mappings":"AAeA,gGAAgG;AAChG,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,IAAI,GAAG,YAAY;IACnE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,gBAAgB,sBAAsB,IAAI,CAAC,CAAC;IAC5G,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAwBD;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAC9C,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,uFAAuF;IACvF,iFAAiF;IACjF,OAAO,OAAO,CAAC,CAAC,kBAAkB,CAAC,KAAK,QAAQ;WACzC,OAAO,CAAC,CAAC,iBAAiB,CAAC,KAAK,QAAQ;WACxC,OAAO,CAAC,CAAC,iBAAiB,CAAC,KAAK,UAAU,CAAC;AACtD,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './generic/record.js';
 export * from './generic/VectorDBBase.js';
 export * from './generic/query.types.js';
+export * from './generic/colocated.types.js';
 export * from './generic/MetadataFilter.js';
 export * from './generic/configuration.types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './generic/record.js';
 export * from './generic/VectorDBBase.js';
 export * from './generic/query.types.js';
+export * from './generic/colocated.types.js';
 export * from './generic/MetadataFilter.js';
 export * from './generic/configuration.types.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/ai-vectordb",
   "type": "module",
-  "version": "5.38.0",
+  "version": "5.39.0",
   "description": "MemberJunction: AI Vector Database Module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,8 +17,9 @@
   "author": "MemberJunction.com",
   "license": "ISC",
   "dependencies": {
-    "@memberjunction/core": "5.38.0",
-    "@memberjunction/global": "5.38.0",
+    "@memberjunction/core": "5.39.0",
+    "@memberjunction/global": "5.39.0",
+    "@memberjunction/sql-dialect": "5.39.0",
     "dotenv": "^17.2.4"
   },
   "devDependencies": {