@an5/adapters 0.2.6 → 0.2.9

package/typescript/src/an5Adapter.ts

@@ -7,6 +7,25 @@ import {
 } from './googlesheets';
 import { parseSheetsConnectionString } from './googlesheets/parseConnectionString';
 import type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from './base/types';
+
+/**
+ * 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'];
+import {
+  NBaseError,
+  buildVectorId,
+  parseVectorId,
+  isNBaseConnectionString,
+  parseNBaseConnectionString,
+  createNBaseVectorClient,
+  type NBaseAdapterConfig,
+  type NBaseVectorClient,
+} from './nbase';
 import { buildOrderBy, parseWhere, quote } from './base/sql';
 import {
   createAdapterProxy,
@@ -204,6 +223,34 @@ export class An5Adapter {
   private _engineType: 'postgres' | 'mysql' | 'sqlite' | 'mssql' | null = null;
   private _engineConfig: An5AdapterConfig | null = null;
   sheetsAdapter: An5SheetsAdapter | null = null;
+  private _nbase: NBaseVectorClient | null = null;
+  private _nbaseConfig: NBaseAdapterConfig | null = null;
+  private _nbaseOnly = false;
+
+  /**
+   * 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 {
+    if (this._nbase && this._nbaseConfig) return { client: this._nbase, config: this._nbaseConfig };
+
+    if (!this._nbaseConfig) return null;
+    const config = this._nbaseConfig;
+
+    const client: NBaseVectorClient = 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(): boolean {
+    return this._nbaseOnly === true;
+  }
 
   get dialect(): Dialect {
     if (this.sheetsAdapter) return 'googlesheets';
@@ -220,6 +267,25 @@ export class An5Adapter {
       return 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 as An5AdapterConfig;
+
+    // `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 (isNBaseConnectionString(rawConnectionString)) {
+      this._nbaseConfig = parseNBaseConnectionString(rawConnectionString);
+      this._nbaseOnly = true;
+      return createAdapterProxy(this, (name) => this.table(name));
+    }
+    const attached = this._engineConfig.nbase;
+    if (attached && isNBaseConnectionString(attached)) {
+      this._nbaseConfig = parseNBaseConnectionString(attached);
+    }
+
     if ((adapterConfig as any).engine) {
       this._engine = (adapterConfig as any).engine;
       this._engineType = (this._engine?.dialect as any) || 'sqlite';
@@ -233,18 +299,27 @@ export class An5Adapter {
       return 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 An5SheetsAdapter(parseSheetsConnectionString(cs));
       return 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.startsWith('sqlite://')
+      || SQLITE_FILE_SUFFIXES.some((suffix) => forDialect.endsWith(suffix))
+    ) {
       this._engineType = 'sqlite';
     } else {
       this._engineType = 'mssql';
@@ -336,9 +411,35 @@ export class An5Adapter {
 
   async $connect(): Promise<void> {
     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(): Promise<{ connected: boolean; endpoint?: string; error?: string }> {
+    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(): Promise<void> {
     if (this.sheetsAdapter) return this.sheetsAdapter.$disconnect();
     await (await this.requireEngine()).disconnect();
@@ -1059,6 +1160,181 @@ export class AdapterTableClient<T = any> {
     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.
+   */
+  private async searchViaNBase(
+    nbase: { client: NBaseVectorClient; config: NBaseAdapterConfig },
+    args: { vector: number[]; take?: number; where?: any },
+    metric: 'cosine' | 'euclidean' | 'dot',
+    take: number,
+  ): Promise<(T & { distance: number })[]> {
+    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: string[] = [];
+    const distances = new Map<string, number>();
+    for (const hit of results) {
+      const fromMetadata = hit.metadata?.[idField];
+      const rawId = fromMetadata !== undefined && fromMetadata !== null
+        ? String(fromMetadata)
+        : parseVectorId(hit.id).id;
+      if (!rawId) continue;
+      const model = hit.metadata?.[modelField] ?? parseVectorId(hit.id).model;
+      ids.push(model === this.modelName ? rawId : `${model}:${rawId}`);
+      distances.set(ids[ids.length - 1] as string, hit.dist);
+    }
+    if (ids.length === 0) return [];
+
+    const pk = this.primaryKeyColumn();
+    const inList = ids.map((_, i) => `@nbase_id_${i}`).join(', ');
+    const idParams: Record<string, any> = {};
+    ids.forEach((id, i) => { idParams[`nbase_id_${i}`] = id; });
+    idParams.take = take;
+
+    const selectColumns = this.modelFields().map((f) => quote(f, this.dialect)).join(', ');
+    const columns = selectColumns ? `${selectColumns}, ${quote(pk, this.dialect)} AS __an5_nbase_key` : `${quote(pk, this.dialect)} AS __an5_nbase_key`;
+    const query = `SELECT ${columns} FROM ${this.tableName} WHERE ${quote(pk, this.dialect)} IN (${inList})`;
+
+    const rows = await this.adapter.exec<Record<string, any>>(query, idParams);
+    const byKey = new Map<string, Record<string, any>>();
+    for (const row of rows ?? []) {
+      byKey.set(String(row.__an5_nbase_key), row);
+    }
+
+    const hydrated: (T & { distance: number })[] = [];
+    for (const id of ids) {
+      const row = byKey.get(id);
+      if (!row) continue;
+      const { __an5_nbase_key, ...rest } = row;
+      hydrated.push({ ...(rest as T), distance: distances.get(id) ?? 0 } as T & { distance: number });
+      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.
+   */
+  private async searchViaNBaseOnly(
+    nbase: { client: NBaseVectorClient; config: NBaseAdapterConfig },
+    args: { vector: number[]; take?: number },
+    metric: 'cosine' | 'euclidean' | 'dot',
+    take: number,
+  ): Promise<Array<Record<string, unknown> & { distance: number }>> {
+    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 = 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`. */
+  private primaryKeyColumn(): string {
+    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. */
+  private modelFields(): string[] {
+    const fields = getFieldsForModel(this.modelName);
+    if (fields && typeof fields === 'object' && !Array.isArray(fields)) {
+      return Object.keys(fields as Record<string, unknown>);
+    }
+    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: {
+    vectorField?: string;
+    where?: any;
+    take?: number;
+    batchSize?: number;
+  } = {}): Promise<{ indexed: number }> {
+    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 as Record<string, unknown>)[vectorField];
+          if (raw === undefined || raw === null) return null;
+          let vector: number[];
+          try {
+            vector = typeof raw === 'string' ? JSON.parse(raw) : (raw as number[]);
+          } catch {
+            return null;
+          }
+          if (!Array.isArray(vector) || vector.length === 0) return null;
+          return {
+            id: buildVectorId(this.modelName, String((row as Record<string, unknown>)[pk])),
+            vector,
+            metadata: {
+              [nbase.config.idField ?? 'an5Id']: String((row as Record<string, unknown>)[pk]),
+              [nbase.config.modelField ?? 'an5Model']: this.modelName,
+            },
+          };
+        })
+        .filter((v): v is NonNullable<typeof v> => v !== null);
+
+      if (vectors.length === 0) continue;
+      const result = await nbase.client.addVectors(vectors);
+      indexed += result.count;
+    }
+    return { indexed };
+  }
+
   async vectorSearch(args: {
     vector: number[];
     take?: number;
@@ -1078,6 +1354,25 @@ export class AdapterTableClient<T = any> {
     const col = quote(vectorField, this.dialect);
     const params: Record<string, any> = { 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)) as (T & { distance: number })[];
+        }
+        return await this.searchViaNBase(nbase, args, metric, take);
+      } catch (err) {
+        if (!(err instanceof 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/typescript/src/base/types.ts

@@ -2,6 +2,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;

package/typescript/src/index.ts

@@ -7,6 +7,23 @@ export {
   setAdapterMetadata,
 } from './an5Adapter';
 export { parseWhere, buildOrderBy, quote } from './base/sql';
+export {
+  NBaseVectorClient,
+  NBaseError,
+  createNBaseVectorClient,
+  createNBaseClient,
+  parseNBaseConnectionString,
+  buildVectorId,
+  parseVectorId,
+} from './nbase';
+export type {
+  NBaseAdapterConfig,
+  NBaseClientConfig,
+  NBaseVector,
+  NBaseSearchOptions,
+  NBaseSearchResult,
+  NBaseStats,
+} from './nbase';
 export type {
   An5AdapterConfig,
   AdapterMetadata,

package/typescript/src/nbase/client.ts

@@ -0,0 +1,214 @@
+/**
+ * NBase — Neural Vector Database client.
+ *
+ * NBase is a vector database with HNSW/LSH/KNN indexing exposed over a REST
+ * API. an5 uses it to move similarity search out of the database process: the
+ * vectors live in NBase, the rows stay in the relational table, and the search
+ * results are hydrated from the table by the id kept in vector metadata.
+ *
+ * The client only uses the global `fetch`, so it works in Node 18+ and in the
+ * browser without pulling in a dependency.
+ */
+
+export interface NBaseVector {
+  id: string | number;
+  vector: number[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface NBaseSearchOptions {
+  /** Number of neighbours to return. */
+  k?: number;
+  /** Distance metric; NBase accepts `cosine` and `euclidean`. */
+  distanceMetric?: 'cosine' | 'euclidean';
+  /** `hnsw` uses the graph index, anything else uses the clustered path. */
+  method?: 'hnsw' | 'clustered';
+  efSearch?: number;
+  filters?: Record<string, unknown> | Array<Record<string, unknown>>;
+  includeMetadata?: boolean;
+  includeVectors?: boolean;
+  skipCache?: boolean;
+  searchTimeoutMs?: number;
+  rerank?: boolean;
+  rerankingMethod?: string;
+  rerankLambda?: number;
+  partitionIds?: string[];
+}
+
+export interface NBaseSearchResult {
+  id: string | number;
+  /** Distance from the query vector. Lower is more similar. */
+  dist: number;
+  metadata?: Record<string, unknown>;
+  vector?: number[];
+  dimension?: number;
+}
+
+export interface NBaseClientConfig {
+  /** Base URL, e.g. `http://localhost:1307`. */
+  url: string;
+  /** Optional bearer token, for deployments behind an auth proxy. */
+  token?: string;
+  /** Per-request timeout in milliseconds. */
+  timeoutMs?: number;
+  /** Injectable for tests and for runtimes without a global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface NBaseStats {
+  vectorCount?: number;
+  metadataCount?: number;
+  memoryUsage?: number;
+  [key: string]: unknown;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export class NBaseError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly body?: unknown,
+  ) {
+    super(message);
+    this.name = 'NBaseError';
+  }
+}
+
+export class NBaseVectorClient {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly timeoutMs: number;
+
+  constructor(private readonly config: NBaseClientConfig) {
+    this.baseUrl = String(config.url).replace(/\/+$/, '');
+    const impl = config.fetchImpl ?? (globalThis as { fetch?: typeof fetch }).fetch;
+    if (!impl) {
+      throw new NBaseError('No fetch implementation available. Node 18+ or a fetch polyfill is required.');
+    }
+    this.fetchImpl = impl;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  private async request<T>(path: string, init?: RequestInit): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        ...init,
+        signal: controller.signal,
+        headers: {
+          'content-type': 'application/json',
+          ...(this.config.token ? { authorization: `Bearer ${this.config.token}` } : {}),
+          ...(init?.headers as Record<string, string> | undefined),
+        },
+      });
+
+      const text = await response.text();
+      let body: unknown;
+      try {
+        body = text ? JSON.parse(text) : undefined;
+      } catch {
+        body = text;
+      }
+
+      if (!response.ok) {
+        const message =
+          (body && typeof body === 'object' && 'error' in (body as Record<string, unknown>)
+            ? String((body as Record<string, unknown>).error)
+            : undefined) ?? `HTTP ${response.status}`;
+        throw new NBaseError(`NBase request ${path} failed: ${message}`, response.status, body);
+      }
+      return body as T;
+    } catch (err) {
+      if (err instanceof NBaseError) throw err;
+      if ((err as { name?: string })?.name === 'AbortError') {
+        throw new NBaseError(`NBase request ${path} timed out after ${this.timeoutMs}ms`);
+      }
+      throw new NBaseError(
+        `Could not reach NBase at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Liveness probe. NBase mounts its status routes at the server root. */
+  async health(): Promise<{ status: string; version?: string }> {
+    return this.request<{ status: string; version?: string }>('/health');
+  }
+
+  /** Vector count, memory use and other database statistics. */
+  async stats(): Promise<NBaseStats> {
+    return this.request<NBaseStats>('/stats');
+  }
+
+  /** Adds or replaces vectors. NBase accepts a single vector or a bulk array. */
+  async addVectors(vectors: NBaseVector[]): Promise<{ count: number; ids?: Array<string | number> }> {
+    if (vectors.length === 0) return { count: 0 };
+    const result = await this.request<{ count: number; addedIds?: Array<string | number> }>(
+      '/api/vectors',
+      { method: 'POST', body: JSON.stringify({ vectors: vectors.length === 1 ? vectors[0] : vectors }) },
+    );
+    return { count: result.count ?? vectors.length, ...(result.addedIds ? { ids: result.addedIds } : {}) };
+  }
+
+  /** Nearest-neighbour search. Results are ordered by ascending `dist`. */
+  async search(vector: number[], options: NBaseSearchOptions = {}): Promise<NBaseSearchResult[]> {
+    const body = await this.request<{ results?: NBaseSearchResult[] }>('/api/search', {
+      method: 'POST',
+      body: JSON.stringify({
+        query: vector,
+        k: options.k ?? 10,
+        ...(options.distanceMetric ? { distanceMetric: options.distanceMetric } : {}),
+        ...(options.method ? { method: options.method } : {}),
+        ...(options.efSearch !== undefined ? { efSearch: options.efSearch } : {}),
+        ...(options.filters ? { filters: options.filters } : {}),
+        ...(options.includeMetadata !== undefined ? { includeMetadata: options.includeMetadata } : {}),
+        ...(options.includeVectors !== undefined ? { includeVectors: options.includeVectors } : {}),
+        ...(options.skipCache !== undefined ? { skipCache: options.skipCache } : {}),
+        ...(options.searchTimeoutMs !== undefined ? { searchTimeoutMs: options.searchTimeoutMs } : {}),
+        ...(options.rerank !== undefined ? { rerank: options.rerank } : {}),
+        ...(options.rerankingMethod ? { rerankingMethod: options.rerankingMethod } : {}),
+        ...(options.rerankLambda !== undefined ? { rerankLambda: options.rerankLambda } : {}),
+        ...(options.partitionIds ? { partitionIds: options.partitionIds } : {}),
+      }),
+    });
+    return body.results ?? [];
+  }
+
+  /** Reads a single vector. Returns undefined when the id is unknown. */
+  async get(id: string | number): Promise<NBaseSearchResult | undefined> {
+    try {
+      return await this.request<NBaseSearchResult>(`/api/vectors/${encodeURIComponent(String(id))}`);
+    } catch (err) {
+      if (err instanceof NBaseError && err.status === 404) return undefined;
+      throw err;
+    }
+  }
+
+  async exists(id: string | number): Promise<boolean> {
+    const result = await this.request<{ exists?: boolean }>(
+      `/api/vectors/${encodeURIComponent(String(id))}/exists`,
+    );
+    return result.exists === true;
+  }
+
+  async delete(id: string | number): Promise<boolean> {
+    await this.request(`/api/vectors/${encodeURIComponent(String(id))}`, { method: 'DELETE' });
+    return true;
+  }
+
+  async updateMetadata(id: string | number, metadata: Record<string, unknown>): Promise<boolean> {
+    await this.request(`/api/vectors/${encodeURIComponent(String(id))}/metadata`, {
+      method: 'PATCH',
+      body: JSON.stringify(metadata),
+    });
+    return true;
+  }
+}
+
+/** Creates an NBase vector client. */
+export function createNBaseVectorClient(config: NBaseClientConfig): NBaseVectorClient {
+  return new NBaseVectorClient(config);
+}