@nhtio/adk 1.20260604.0 → 1.20260607.0

package/batteries/vector/chroma.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chroma.mjs","names":["#opts","#client","#collectionCache"],"sources":["../../../src/batteries/vector/chroma/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/chroma\n */\n\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isFilterCondition, isRawFilter, isFilterGroup } from '../filters'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR,\n} from '../exceptions'\nimport type { VectorFilter } from '../filters'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorMetadata,\n  BaseVectorStoreOptions,\n  VectorStoreCapabilities,\n} from '../types'\n\nexport interface ChromaVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: { url?: string; host?: string; port?: number; ssl?: boolean }\n}\n\nconst getChromaClient = async () => {\n  try {\n    const mod = await import('chromadb')\n    return mod.ChromaClient\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['chromadb'])\n  }\n}\n\nconst getSpace = (metric: string): string => {\n  if (metric === 'cosine') return 'cosine'\n  if (metric === 'euclidean') return 'l2'\n  if (metric === 'dot') return 'ip'\n  return 'cosine'\n}\n\nexport const translateChromaWhere = (\n  filter?: VectorFilter\n): Record<string, unknown> | undefined => {\n  if (!filter) return undefined\n  if (isRawFilter(filter)) {\n    if (filter.$dialect === 'chroma') {\n      return filter.$raw as Record<string, unknown>\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', String(filter.$dialect)])\n  }\n  if (isFilterCondition(filter)) {\n    const { field, op, value } = filter\n    if (value === undefined) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    if (op === 'eq') {\n      return { [field]: { $eq: value } }\n    }\n    if (op === 'ne') {\n      return { [field]: { $ne: value } }\n    }\n    if (op === 'gt') {\n      return { [field]: { $gt: value } }\n    }\n    if (op === 'gte') {\n      return { [field]: { $gte: value } }\n    }\n    if (op === 'lt') {\n      return { [field]: { $lt: value } }\n    }\n    if (op === 'lte') {\n      return { [field]: { $lte: value } }\n    }\n    if (op === 'in') {\n      return { [field]: { $in: value } }\n    }\n    if (op === 'nin') {\n      return { [field]: { $nin: value } }\n    }\n    if (op === 'exists' || op === 'contains') {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n  }\n  if (isFilterGroup(filter)) {\n    const { and, or, not } = filter\n    if (and) {\n      const children = and\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $and: children }\n    }\n    if (or) {\n      const children = or\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $or: children }\n    }\n    if (not) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', 'not'])\n    }\n    return undefined\n  }\n  return undefined\n}\n\nexport class ChromaVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // Strongly consistent on resolve; the option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n  #client: any | null = null\n  #collectionCache: Map<string, any> = new Map()\n  get #opts() {\n    return this.options as ChromaVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const ChromaClient = await getChromaClient()\n    const c = this.#opts.connection || {}\n    let host: string | undefined\n    let port: number | undefined\n    let ssl: boolean = false\n\n    if (c.url) {\n      const url = new URL(c.url)\n      host = url.hostname\n      port = url.port ? Number.parseInt(url.port, 10) : url.protocol === 'https:' ? 443 : 80\n      ssl = url.protocol === 'https:'\n    } else {\n      host = c.host\n      port = c.port\n      ssl = c.ssl || false\n    }\n\n    const path =\n      host && port !== undefined\n        ? `${ssl ? 'https://' : 'http://'}${host}${port === 80 || port === 443 ? '' : ':' + port}`\n        : undefined\n\n    try {\n      this.#client = new ChromaClient({ path })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#client = null\n    this.#collectionCache.clear()\n  }\n\n  async getCollection(name: string): Promise<any> {\n    let collection = this.#collectionCache.get(name)\n    if (collection) return collection\n    if (!this.#client) await this.connect()\n    const metric = this.#opts.metric ?? 'cosine'\n    collection = await this.#client.getOrCreateCollection({\n      name,\n      metadata: { 'hnsw:space': getSpace(metric) },\n    })\n    this.#collectionCache.set(name, collection)\n    return collection\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const name = spec.collection\n    if (ifNotExists && (await this.hasCollection(name))) return\n    if (await this.hasCollection(name)) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['create', 'exists'])\n    }\n    try {\n      await this.connect()\n      const metric = spec.vector.metric ?? 'cosine'\n      await this.#client!.getOrCreateCollection({\n        name,\n        metadata: { 'hnsw:space': getSpace(metric) },\n      })\n      this.#collectionCache.set(name, null)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await this.connect()\n      await this.#client!.deleteCollection({ name: collection })\n      this.#collectionCache.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    if (!this.#client) await this.connect()\n    try {\n      const collections = await this.#client!.listCollections()\n      for (const c of collections) {\n        if (typeof c === 'object' ? c.name === collection : c === collection) {\n          return true\n        }\n      }\n      return false\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    try {\n      const collection = await this.getCollection(from)\n      await collection.modify({ name: to })\n      const cached = this.#collectionCache.get(from)\n      this.#collectionCache.delete(from)\n      if (cached) {\n        this.#collectionCache.set(to, cached)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const collection = await this.getCollection(plan.collection)\n    const expected = this.#opts.dimensions\n    const ids: string[] = []\n    const embeddings: number[][] = []\n    const documents: string[] = []\n    const metadatas: VectorMetadata[] = []\n\n    for (const r of plan.records) {\n      let vector = r.vector\n      if (!vector && r.document) {\n        const [v] = await this.encode([r.document], 'document')\n        vector = v\n      }\n      if (!vector) {\n        throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n      }\n      if (expected !== undefined && vector.length !== expected) {\n        throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n      }\n      ids.push(r.id)\n      embeddings.push(vector)\n      documents.push(r.document ?? '')\n      const md = { ...(r.metadata ?? {}), internalId: r.id }\n      metadatas.push(md)\n    }\n\n    try {\n      await collection.upsert({ ids, embeddings, documents, metadatas })\n    } catch (err) {\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const collection = await this.getCollection(plan.collection)\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const res = await collection.get({ ids: [plan.near.id], include: ['embeddings'] })\n        if (!res.ids || res.ids.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        const embeddings = res.embeddings || []\n        if (!embeddings || embeddings.length === 0 || !embeddings[0]) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id has no vector: ' + plan.near.id])\n        }\n        queryVector = embeddings[0]\n      }\n    }\n\n    const where = translateChromaWhere(plan.filter)\n\n    let results: any\n    if (queryVector) {\n      try {\n        results = await collection.query({\n          queryEmbeddings: [queryVector],\n          nResults: plan.topK,\n          where,\n          include: ['documents', 'metadatas', 'distances', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    } else {\n      try {\n        results = await collection.get({\n          where,\n          limit: plan.topK,\n          include: ['documents', 'metadatas', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    }\n\n    const proj = plan.projection\n    const out: VectorMatch[] = []\n    // `query()` returns per-query nested arrays (`ids: [[...]]`); `get()` (the filter-scan path)\n    // returns flat arrays (`ids: [...]`). Unwrap one level only for the query path.\n    const unwrap = (col: any): any[] => {\n      if (!col) return []\n      return queryVector ? (col[0] ?? []) : col\n    }\n    const ids = unwrap(results.ids)\n    const documents = unwrap(results.documents)\n    const metadatas = unwrap(results.metadatas)\n    const embeddings = unwrap(results.embeddings)\n    const distances = unwrap(results.distances)\n\n    const start = plan.offset || 0\n    const limit = plan.topK\n\n    for (let i = start; i < Math.min(ids.length, start + limit); i++) {\n      const match: VectorMatch = {}\n      if (proj.id) {\n        match.id = ids[i]\n      }\n      if (proj.vector && embeddings[i]) {\n        match.vector = embeddings[i]\n      }\n      if (proj.document) {\n        match.document = documents[i] ?? undefined\n      }\n      if (proj.metadata && metadatas[i]) {\n        const rawMeta = metadatas[i] as VectorMetadata\n        const { internalId, ...rest } = rawMeta\n        match.metadata = rest\n      }\n      if (queryVector && distances && distances[i] !== undefined) {\n        match.score = normalizeScore(distances[i], metric, 'distance')\n      }\n      out.push(match)\n    }\n\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const collection = await this.getCollection(plan.collection)\n    try {\n      if (plan.ids) {\n        await collection.delete({ ids: plan.ids })\n      } else if (plan.filter) {\n        const where = translateChromaWhere(plan.filter)\n        if (where) {\n          await collection.delete({ where })\n        } else {\n          await collection.delete({ where: {} })\n        }\n      } else {\n        await collection.delete({ where: {} })\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/clickhouse/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @module @nhtio/adk/batteries/vector/clickhouse
+ *
+ * ClickHouse adapter. Vectors live in an `Array(Float32)` column; KNN uses ClickHouse's
+ * `cosineDistance` / `L2Distance` / negative-inner-product expressions ordered ascending.
+ * Metadata is a JSON `String` column, filtered with the neutral filter tree's JS reference
+ * evaluator for exact cross-adapter parity. Each collection is a MergeTree table.
+ *
+ * MergeTree allows duplicate keys, so upsert is delete-then-insert; writes are made
+ * read-after-write consistent with `mutations_sync = 2` on deletes.
+ *
+ * Driver: `@clickhouse/client` (HTTP).
+ */
+import { BaseVectorStore } from "../contract";
+import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
+import type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from "../types";
+export interface ClickHouseVectorStoreOptions extends BaseVectorStoreOptions {
+    connection?: {
+        url?: string;
+        username?: string;
+        password?: string;
+        database?: string;
+    };
+}
+export declare class ClickHouseVectorStore extends BaseVectorStore {
+    #private;
+    readonly capabilities: VectorStoreCapabilities;
+    static isAvailable(): boolean;
+    isAvailable(): boolean;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void>;
+    dropCollection(collection: string, ifExists: boolean): Promise<void>;
+    hasCollection(collection: string): Promise<boolean>;
+    renameCollection(from: string, to: string): Promise<void>;
+    executeUpsert(plan: UpsertPlan): Promise<void>;
+    executeSearch(plan: SearchPlan): Promise<VectorMatch[]>;
+    executeDelete(plan: DeletePlan): Promise<void>;
+}

package/batteries/vector/clickhouse.cjs

@@ -0,0 +1,246 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../tool_registry-DYUYqXvo.js");
+require("../../guards.cjs");
+const require_batteries_vector_filters = require("./filters.cjs");
+const require_batteries_vector_helpers = require("./helpers.cjs");
+const require_batteries_vector_exceptions = require("./exceptions.cjs");
+const require_batteries_vector_contract = require("./contract.cjs");
+const require_batteries_vector_validation = require("./validation.cjs");
+//#region src/batteries/vector/clickhouse/index.ts
+/**
+* @module @nhtio/adk/batteries/vector/clickhouse
+*
+* ClickHouse adapter. Vectors live in an `Array(Float32)` column; KNN uses ClickHouse's
+* `cosineDistance` / `L2Distance` / negative-inner-product expressions ordered ascending.
+* Metadata is a JSON `String` column, filtered with the neutral filter tree's JS reference
+* evaluator for exact cross-adapter parity. Each collection is a MergeTree table.
+*
+* MergeTree allows duplicate keys, so upsert is delete-then-insert; writes are made
+* read-after-write consistent with `mutations_sync = 2` on deletes.
+*
+* Driver: `@clickhouse/client` (HTTP).
+*/
+var getClickHouseClient = async () => {
+	try {
+		return (await import("@clickhouse/client")).createClient;
+	} catch {
+		throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DRIVER_UNAVAILABLE(["@clickhouse/client"]);
+	}
+};
+var distanceExpr = (metric, vecLit) => metric === "euclidean" ? `L2Distance(vec, ${vecLit})` : metric === "dot" ? `-arraySum(arrayMap((a, b) -> a * b, vec, ${vecLit}))` : `cosineDistance(vec, ${vecLit})`;
+var ident = (name) => "`" + name.replace(/`/g, "``") + "`";
+var lit = (value) => `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+var vectorLiteral = (vector) => `[${vector.map((n) => Number.isFinite(n) ? String(n) : "0").join(", ")}]`;
+var ClickHouseVectorStore = class extends require_batteries_vector_contract.BaseVectorStore {
+	capabilities = {
+		transactions: false,
+		namedVectors: false,
+		rename: true,
+		rawSql: true,
+		builtInEncoding: false,
+		consistency: {
+			configurable: false,
+			default: "strong",
+			modes: ["strong"]
+		}
+	};
+	#client = null;
+	#dims = /* @__PURE__ */ new Map();
+	get #opts() {
+		return this.options;
+	}
+	static isAvailable() {
+		return typeof process !== "undefined";
+	}
+	isAvailable() {
+		return typeof process !== "undefined";
+	}
+	async connect() {
+		if (this.#client) return;
+		const createClient = await getClickHouseClient();
+		const c = this.#opts.connection || {};
+		try {
+			this.#client = createClient({
+				url: c.url ?? "http://localhost:8123",
+				username: c.username ?? "default",
+				password: c.password ?? "",
+				database: c.database ?? "default"
+			});
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_CONNECTION_FAILED([String(err)]);
+		}
+	}
+	async close() {
+		if (this.#client) {
+			await this.#client.close();
+			this.#client = null;
+		}
+	}
+	async #ensure() {
+		if (!this.#client) await this.connect();
+		return this.#client;
+	}
+	async #json(sql) {
+		return await (await (await this.#ensure()).query({
+			query: sql,
+			format: "JSONEachRow"
+		})).json();
+	}
+	async createCollection(spec, ifNotExists) {
+		const client = await this.#ensure();
+		this.#dims.set(spec.collection, spec.vector.dimensions);
+		const ine = ifNotExists ? "IF NOT EXISTS " : "";
+		try {
+			await client.command({ query: `CREATE TABLE ${ine}${ident(spec.collection)} (id String, vec Array(Float32), document String, metadata String) ENGINE = MergeTree() ORDER BY id` });
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["createCollection", String(err)]);
+		}
+	}
+	async dropCollection(collection, ifExists) {
+		const client = await this.#ensure();
+		const ie = ifExists ? "IF EXISTS " : "";
+		try {
+			await client.command({ query: `DROP TABLE ${ie}${ident(collection)}` });
+			this.#dims.delete(collection);
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["dropCollection", String(err)]);
+		}
+	}
+	async hasCollection(collection) {
+		const rows = await this.#json(`EXISTS TABLE ${ident(collection)}`);
+		return rows.length > 0 && (rows[0].result === 1 || rows[0].result === "1");
+	}
+	async renameCollection(from, to) {
+		const client = await this.#ensure();
+		try {
+			await client.command({ query: `RENAME TABLE ${ident(from)} TO ${ident(to)}` });
+			const d = this.#dims.get(from);
+			if (d !== void 0) {
+				this.#dims.set(to, d);
+				this.#dims.delete(from);
+			}
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UNSUPPORTED_OPERATION(["renameCollection", String(err)]);
+		}
+	}
+	async executeUpsert(plan) {
+		if (plan.records.length === 0) return;
+		require_batteries_vector_validation.validateRecords(plan.records);
+		const client = await this.#ensure();
+		const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection);
+		const values = [];
+		const ids = [];
+		try {
+			for (const r of plan.records) {
+				let vector = r.vector;
+				if (!vector && r.document) {
+					const [v] = await this.encode([r.document], "document");
+					vector = v;
+				}
+				if (!vector) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UPSERT_FAILED(["Record missing vector and document"]);
+				if (expected !== void 0 && vector.length !== expected) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length]);
+				ids.push(r.id);
+				values.push({
+					id: r.id,
+					vec: vector,
+					document: r.document ?? "",
+					metadata: r.metadata ? JSON.stringify(r.metadata) : "{}"
+				});
+			}
+			const idList = ids.map((id) => lit(id)).join(", ");
+			await client.command({
+				query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${idList})`,
+				clickhouse_settings: { mutations_sync: "2" }
+			});
+			await client.insert({
+				table: plan.collection,
+				values,
+				format: "JSONEachRow"
+			});
+		} catch (err) {
+			if (require_tool_registry.isInstanceOf(err, "E_VECTOR_STORE_DIMENSION_MISMATCH", require_batteries_vector_exceptions.E_VECTOR_STORE_DIMENSION_MISMATCH) || require_tool_registry.isInstanceOf(err, "E_VECTOR_STORE_UPSERT_FAILED", require_batteries_vector_exceptions.E_VECTOR_STORE_UPSERT_FAILED)) throw err;
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UPSERT_FAILED([String(err)]);
+		}
+	}
+	async executeSearch(plan) {
+		const metric = this.#opts.metric ?? "cosine";
+		let queryVector;
+		if (plan.near) {
+			if ("vector" in plan.near) queryVector = plan.near.vector;
+			else if ("serverText" in plan.near) {
+				const [v] = await this.encode([plan.near.serverText], "query");
+				queryVector = v;
+			} else if ("id" in plan.near) {
+				const rows = await this.#json(`SELECT vec FROM ${ident(plan.collection)} WHERE id = ${lit(plan.near.id)} LIMIT 1`);
+				if (rows.length === 0) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_SEARCH_FAILED(["Referenced id not found: " + plan.near.id]);
+				queryVector = rows[0].vec;
+			}
+		}
+		const offset = plan.offset ?? 0;
+		try {
+			if (queryVector) {
+				const distExpr = distanceExpr(metric, vectorLiteral(queryVector));
+				const rows = await this.#json(`SELECT id, vec, document, metadata, ${distExpr} AS __dist FROM ${ident(plan.collection)}`);
+				const filtered = plan.filter ? rows.filter((row) => require_batteries_vector_filters.evaluateFilter(plan.filter, this.#parseMeta(row.metadata))) : rows;
+				filtered.sort((a, b) => Number(a.__dist) - Number(b.__dist));
+				return filtered.slice(offset, offset + plan.topK).map((row) => this.#project(row, plan, metric, true));
+			} else {
+				const rows = await this.#json(`SELECT id, vec, document, metadata FROM ${ident(plan.collection)}`);
+				return (plan.filter ? rows.filter((row) => require_batteries_vector_filters.evaluateFilter(plan.filter, this.#parseMeta(row.metadata))) : rows).slice(offset, offset + plan.topK).map((row) => this.#project(row, plan, metric, false));
+			}
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_SEARCH_FAILED([String(err)]);
+		}
+	}
+	#parseMeta(val) {
+		if (typeof val === "string") try {
+			return JSON.parse(val);
+		} catch {
+			return {};
+		}
+		if (val && typeof val === "object") return val;
+		return {};
+	}
+	#project(row, plan, metric, isKnn) {
+		const proj = plan.projection;
+		const out = {};
+		if (proj.id) out.id = row.id;
+		if (proj.vector) out.vector = row.vec.map((n) => Number(n));
+		if (proj.document) out.document = row.document ?? void 0;
+		if (proj.metadata) out.metadata = this.#parseMeta(row.metadata);
+		if (isKnn && row.__dist !== void 0 && row.__dist !== null) out.score = require_batteries_vector_helpers.normalizeScore(Number(row.__dist), metric, "distance");
+		return out;
+	}
+	async executeDelete(plan) {
+		const client = await this.#ensure();
+		const sync = { mutations_sync: "2" };
+		try {
+			if (plan.ids && plan.ids.length > 0) {
+				const list = plan.ids.map((id) => lit(id)).join(", ");
+				await client.command({
+					query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,
+					clickhouse_settings: sync
+				});
+			} else if (plan.filter) {
+				const targets = (await this.#json(`SELECT id, metadata FROM ${ident(plan.collection)}`)).filter((row) => require_batteries_vector_filters.evaluateFilter(plan.filter, this.#parseMeta(row.metadata))).map((row) => row.id);
+				if (targets.length > 0) {
+					const list = targets.map((id) => lit(id)).join(", ");
+					await client.command({
+						query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,
+						clickhouse_settings: sync
+					});
+				}
+			} else await client.command({
+				query: `DELETE FROM ${ident(plan.collection)} WHERE 1 = 1`,
+				clickhouse_settings: sync
+			});
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DELETE_FAILED([String(err)]);
+		}
+	}
+};
+//#endregion
+exports.ClickHouseVectorStore = ClickHouseVectorStore;
+
+//# sourceMappingURL=clickhouse.cjs.map

package/batteries/vector/clickhouse.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse.cjs","names":["#opts","#client","#ensure","#json","#dims","#parseMeta","#project"],"sources":["../../../src/batteries/vector/clickhouse/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/clickhouse\n *\n * ClickHouse adapter. Vectors live in an `Array(Float32)` column; KNN uses ClickHouse's\n * `cosineDistance` / `L2Distance` / negative-inner-product expressions ordered ascending.\n * Metadata is a JSON `String` column, filtered with the neutral filter tree's JS reference\n * evaluator for exact cross-adapter parity. Each collection is a MergeTree table.\n *\n * MergeTree allows duplicate keys, so upsert is delete-then-insert; writes are made\n * read-after-write consistent with `mutations_sync = 2` on deletes.\n *\n * Driver: `@clickhouse/client` (HTTP).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface ClickHouseVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: { url?: string; username?: string; password?: string; database?: string }\n}\n\nconst getClickHouseClient = async () => {\n  try {\n    const mod = await import('@clickhouse/client')\n    return mod.createClient\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@clickhouse/client'])\n  }\n}\n\n// ClickHouse distance expression per metric (all \"lower is closer\" once negated for dot).\nconst distanceExpr = (metric: DistanceMetric, vecLit: string): string =>\n  metric === 'euclidean'\n    ? `L2Distance(vec, ${vecLit})`\n    : metric === 'dot'\n      ? `-arraySum(arrayMap((a, b) -> a * b, vec, ${vecLit}))`\n      : `cosineDistance(vec, ${vecLit})`\n\n// Backtick-quote an identifier, escaping embedded backticks.\nconst ident = (name: string): string => '`' + name.replace(/`/g, '``') + '`'\n\n// Single-quoted ClickHouse string literal.\nconst lit = (value: string): string => `'${value.replace(/\\\\/g, '\\\\\\\\').replace(/'/g, \"\\\\'\")}'`\n\n// number[] → ClickHouse array literal [1, 2, 3].\nconst vectorLiteral = (vector: number[]): string =>\n  `[${vector.map((n) => (Number.isFinite(n) ? String(n) : '0')).join(', ')}]`\n\nexport class ClickHouseVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: true,\n    builtInEncoding: false,\n    // Made strongly consistent via mutations_sync=2 on deletes; writes visible on resolve.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #client: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): ClickHouseVectorStoreOptions {\n    return this.options as ClickHouseVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const createClient = await getClickHouseClient()\n    const c = this.#opts.connection || {}\n    try {\n      this.#client = createClient({\n        url: c.url ?? 'http://localhost:8123',\n        username: c.username ?? 'default',\n        password: c.password ?? '',\n        database: c.database ?? 'default',\n      })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    if (this.#client) {\n      await this.#client.close()\n      this.#client = null\n    }\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#client) await this.connect()\n    return this.#client!\n  }\n\n  async #json(sql: string): Promise<any[]> {\n    const client = await this.#ensure()\n    const rs = await client.query({ query: sql, format: 'JSONEachRow' })\n    return (await rs.json()) as any[]\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    const ine = ifNotExists ? 'IF NOT EXISTS ' : ''\n    try {\n      await client.command({\n        query:\n          `CREATE TABLE ${ine}${ident(spec.collection)} (` +\n          `id String, vec Array(Float32), document String, metadata String` +\n          `) ENGINE = MergeTree() ORDER BY id`,\n      })\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    const ie = ifExists ? 'IF EXISTS ' : ''\n    try {\n      await client.command({ query: `DROP TABLE ${ie}${ident(collection)}` })\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const rows = await this.#json(`EXISTS TABLE ${ident(collection)}`)\n    return rows.length > 0 && (rows[0].result === 1 || rows[0].result === '1')\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    const client = await this.#ensure()\n    try {\n      await client.command({ query: `RENAME TABLE ${ident(from)} TO ${ident(to)}` })\n      const d = this.#dims.get(from)\n      if (d !== undefined) {\n        this.#dims.set(to, d)\n        this.#dims.delete(from)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const client = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    const values: any[] = []\n    const ids: string[] = []\n    try {\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        ids.push(r.id)\n        values.push({\n          id: r.id,\n          vec: vector,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n        })\n      }\n      // MergeTree allows dupes — delete the ids first (synchronously) so upsert replaces.\n      const idList = ids.map((id) => lit(id)).join(', ')\n      await client.command({\n        query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${idList})`,\n        clickhouse_settings: { mutations_sync: '2' },\n      })\n      await client.insert({\n        table: plan.collection,\n        values,\n        format: 'JSONEachRow',\n      })\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const rows = await this.#json(\n          `SELECT vec FROM ${ident(plan.collection)} WHERE id = ${lit(plan.near.id)} LIMIT 1`\n        )\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = rows[0].vec as number[]\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        const distExpr = distanceExpr(metric, vectorLiteral(queryVector))\n        const rows = await this.#json(\n          `SELECT id, vec, document, metadata, ${distExpr} AS __dist FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        filtered.sort((a, b) => Number(a.__dist) - Number(b.__dist))\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, true))\n      } else {\n        const rows = await this.#json(\n          `SELECT id, vec, document, metadata FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any, plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = row.id as string\n    if (proj.vector) out.vector = (row.vec as number[]).map((n) => Number(n))\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (isKnn && row.__dist !== undefined && row.__dist !== null) {\n      out.score = normalizeScore(Number(row.__dist), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const client = await this.#ensure()\n    const sync = { mutations_sync: '2' as const }\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        const list = plan.ids.map((id) => lit(id)).join(', ')\n        await client.command({\n          query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,\n          clickhouse_settings: sync,\n        })\n      } else if (plan.filter) {\n        const rows = await this.#json(`SELECT id, metadata FROM ${ident(plan.collection)}`)\n        const targets = rows\n          .filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row) => row.id as string)\n        if (targets.length > 0) {\n          const list = targets.map((id) => lit(id)).join(', ')\n          await client.command({\n            query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,\n            clickhouse_settings: sync,\n          })\n        }\n      } else {\n        await client.command({\n          query: `DELETE FROM ${ident(plan.collection)} WHERE 1 = 1`,\n          clickhouse_settings: sync,\n        })\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/clickhouse.mjs

@@ -0,0 +1,244 @@
+import { s as isInstanceOf } from "../../tool_registry-D1pSSlsd.mjs";
+import "../../guards.mjs";
+import { evaluateFilter } from "./filters.mjs";
+import { normalizeScore } from "./helpers.mjs";
+import { E_VECTOR_STORE_COLLECTION_FAILED, E_VECTOR_STORE_CONNECTION_FAILED, E_VECTOR_STORE_DELETE_FAILED, E_VECTOR_STORE_DIMENSION_MISMATCH, E_VECTOR_STORE_DRIVER_UNAVAILABLE, E_VECTOR_STORE_SEARCH_FAILED, E_VECTOR_STORE_UNSUPPORTED_OPERATION, E_VECTOR_STORE_UPSERT_FAILED } from "./exceptions.mjs";
+import { BaseVectorStore } from "./contract.mjs";
+import { validateRecords } from "./validation.mjs";
+//#region src/batteries/vector/clickhouse/index.ts
+/**
+* @module @nhtio/adk/batteries/vector/clickhouse
+*
+* ClickHouse adapter. Vectors live in an `Array(Float32)` column; KNN uses ClickHouse's
+* `cosineDistance` / `L2Distance` / negative-inner-product expressions ordered ascending.
+* Metadata is a JSON `String` column, filtered with the neutral filter tree's JS reference
+* evaluator for exact cross-adapter parity. Each collection is a MergeTree table.
+*
+* MergeTree allows duplicate keys, so upsert is delete-then-insert; writes are made
+* read-after-write consistent with `mutations_sync = 2` on deletes.
+*
+* Driver: `@clickhouse/client` (HTTP).
+*/
+var getClickHouseClient = async () => {
+	try {
+		return (await import("@clickhouse/client")).createClient;
+	} catch {
+		throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(["@clickhouse/client"]);
+	}
+};
+var distanceExpr = (metric, vecLit) => metric === "euclidean" ? `L2Distance(vec, ${vecLit})` : metric === "dot" ? `-arraySum(arrayMap((a, b) -> a * b, vec, ${vecLit}))` : `cosineDistance(vec, ${vecLit})`;
+var ident = (name) => "`" + name.replace(/`/g, "``") + "`";
+var lit = (value) => `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+var vectorLiteral = (vector) => `[${vector.map((n) => Number.isFinite(n) ? String(n) : "0").join(", ")}]`;
+var ClickHouseVectorStore = class extends BaseVectorStore {
+	capabilities = {
+		transactions: false,
+		namedVectors: false,
+		rename: true,
+		rawSql: true,
+		builtInEncoding: false,
+		consistency: {
+			configurable: false,
+			default: "strong",
+			modes: ["strong"]
+		}
+	};
+	#client = null;
+	#dims = /* @__PURE__ */ new Map();
+	get #opts() {
+		return this.options;
+	}
+	static isAvailable() {
+		return typeof process !== "undefined";
+	}
+	isAvailable() {
+		return typeof process !== "undefined";
+	}
+	async connect() {
+		if (this.#client) return;
+		const createClient = await getClickHouseClient();
+		const c = this.#opts.connection || {};
+		try {
+			this.#client = createClient({
+				url: c.url ?? "http://localhost:8123",
+				username: c.username ?? "default",
+				password: c.password ?? "",
+				database: c.database ?? "default"
+			});
+		} catch (err) {
+			throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)]);
+		}
+	}
+	async close() {
+		if (this.#client) {
+			await this.#client.close();
+			this.#client = null;
+		}
+	}
+	async #ensure() {
+		if (!this.#client) await this.connect();
+		return this.#client;
+	}
+	async #json(sql) {
+		return await (await (await this.#ensure()).query({
+			query: sql,
+			format: "JSONEachRow"
+		})).json();
+	}
+	async createCollection(spec, ifNotExists) {
+		const client = await this.#ensure();
+		this.#dims.set(spec.collection, spec.vector.dimensions);
+		const ine = ifNotExists ? "IF NOT EXISTS " : "";
+		try {
+			await client.command({ query: `CREATE TABLE ${ine}${ident(spec.collection)} (id String, vec Array(Float32), document String, metadata String) ENGINE = MergeTree() ORDER BY id` });
+		} catch (err) {
+			throw new E_VECTOR_STORE_COLLECTION_FAILED(["createCollection", String(err)]);
+		}
+	}
+	async dropCollection(collection, ifExists) {
+		const client = await this.#ensure();
+		const ie = ifExists ? "IF EXISTS " : "";
+		try {
+			await client.command({ query: `DROP TABLE ${ie}${ident(collection)}` });
+			this.#dims.delete(collection);
+		} catch (err) {
+			throw new E_VECTOR_STORE_COLLECTION_FAILED(["dropCollection", String(err)]);
+		}
+	}
+	async hasCollection(collection) {
+		const rows = await this.#json(`EXISTS TABLE ${ident(collection)}`);
+		return rows.length > 0 && (rows[0].result === 1 || rows[0].result === "1");
+	}
+	async renameCollection(from, to) {
+		const client = await this.#ensure();
+		try {
+			await client.command({ query: `RENAME TABLE ${ident(from)} TO ${ident(to)}` });
+			const d = this.#dims.get(from);
+			if (d !== void 0) {
+				this.#dims.set(to, d);
+				this.#dims.delete(from);
+			}
+		} catch (err) {
+			throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(["renameCollection", String(err)]);
+		}
+	}
+	async executeUpsert(plan) {
+		if (plan.records.length === 0) return;
+		validateRecords(plan.records);
+		const client = await this.#ensure();
+		const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection);
+		const values = [];
+		const ids = [];
+		try {
+			for (const r of plan.records) {
+				let vector = r.vector;
+				if (!vector && r.document) {
+					const [v] = await this.encode([r.document], "document");
+					vector = v;
+				}
+				if (!vector) throw new E_VECTOR_STORE_UPSERT_FAILED(["Record missing vector and document"]);
+				if (expected !== void 0 && vector.length !== expected) throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length]);
+				ids.push(r.id);
+				values.push({
+					id: r.id,
+					vec: vector,
+					document: r.document ?? "",
+					metadata: r.metadata ? JSON.stringify(r.metadata) : "{}"
+				});
+			}
+			const idList = ids.map((id) => lit(id)).join(", ");
+			await client.command({
+				query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${idList})`,
+				clickhouse_settings: { mutations_sync: "2" }
+			});
+			await client.insert({
+				table: plan.collection,
+				values,
+				format: "JSONEachRow"
+			});
+		} catch (err) {
+			if (isInstanceOf(err, "E_VECTOR_STORE_DIMENSION_MISMATCH", E_VECTOR_STORE_DIMENSION_MISMATCH) || isInstanceOf(err, "E_VECTOR_STORE_UPSERT_FAILED", E_VECTOR_STORE_UPSERT_FAILED)) throw err;
+			throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)]);
+		}
+	}
+	async executeSearch(plan) {
+		const metric = this.#opts.metric ?? "cosine";
+		let queryVector;
+		if (plan.near) {
+			if ("vector" in plan.near) queryVector = plan.near.vector;
+			else if ("serverText" in plan.near) {
+				const [v] = await this.encode([plan.near.serverText], "query");
+				queryVector = v;
+			} else if ("id" in plan.near) {
+				const rows = await this.#json(`SELECT vec FROM ${ident(plan.collection)} WHERE id = ${lit(plan.near.id)} LIMIT 1`);
+				if (rows.length === 0) throw new E_VECTOR_STORE_SEARCH_FAILED(["Referenced id not found: " + plan.near.id]);
+				queryVector = rows[0].vec;
+			}
+		}
+		const offset = plan.offset ?? 0;
+		try {
+			if (queryVector) {
+				const distExpr = distanceExpr(metric, vectorLiteral(queryVector));
+				const rows = await this.#json(`SELECT id, vec, document, metadata, ${distExpr} AS __dist FROM ${ident(plan.collection)}`);
+				const filtered = plan.filter ? rows.filter((row) => evaluateFilter(plan.filter, this.#parseMeta(row.metadata))) : rows;
+				filtered.sort((a, b) => Number(a.__dist) - Number(b.__dist));
+				return filtered.slice(offset, offset + plan.topK).map((row) => this.#project(row, plan, metric, true));
+			} else {
+				const rows = await this.#json(`SELECT id, vec, document, metadata FROM ${ident(plan.collection)}`);
+				return (plan.filter ? rows.filter((row) => evaluateFilter(plan.filter, this.#parseMeta(row.metadata))) : rows).slice(offset, offset + plan.topK).map((row) => this.#project(row, plan, metric, false));
+			}
+		} catch (err) {
+			throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)]);
+		}
+	}
+	#parseMeta(val) {
+		if (typeof val === "string") try {
+			return JSON.parse(val);
+		} catch {
+			return {};
+		}
+		if (val && typeof val === "object") return val;
+		return {};
+	}
+	#project(row, plan, metric, isKnn) {
+		const proj = plan.projection;
+		const out = {};
+		if (proj.id) out.id = row.id;
+		if (proj.vector) out.vector = row.vec.map((n) => Number(n));
+		if (proj.document) out.document = row.document ?? void 0;
+		if (proj.metadata) out.metadata = this.#parseMeta(row.metadata);
+		if (isKnn && row.__dist !== void 0 && row.__dist !== null) out.score = normalizeScore(Number(row.__dist), metric, "distance");
+		return out;
+	}
+	async executeDelete(plan) {
+		const client = await this.#ensure();
+		const sync = { mutations_sync: "2" };
+		try {
+			if (plan.ids && plan.ids.length > 0) {
+				const list = plan.ids.map((id) => lit(id)).join(", ");
+				await client.command({
+					query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,
+					clickhouse_settings: sync
+				});
+			} else if (plan.filter) {
+				const targets = (await this.#json(`SELECT id, metadata FROM ${ident(plan.collection)}`)).filter((row) => evaluateFilter(plan.filter, this.#parseMeta(row.metadata))).map((row) => row.id);
+				if (targets.length > 0) {
+					const list = targets.map((id) => lit(id)).join(", ");
+					await client.command({
+						query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,
+						clickhouse_settings: sync
+					});
+				}
+			} else await client.command({
+				query: `DELETE FROM ${ident(plan.collection)} WHERE 1 = 1`,
+				clickhouse_settings: sync
+			});
+		} catch (err) {
+			throw new E_VECTOR_STORE_DELETE_FAILED([String(err)]);
+		}
+	}
+};
+//#endregion
+export { ClickHouseVectorStore };
+
+//# sourceMappingURL=clickhouse.mjs.map