@zepdb/zeppelin-embed 0.1.0 → 0.2.0

package/README.md

@@ -26,6 +26,31 @@ Applications supply document and query vectors. Document IDs are unsigned
 native finalizer also closes an open handle if the JavaScript object is
 collected.
 
+Namespaces add typed records without changing the existing vector API:
+
+```js
+const { openNamespace, listNamespaces } = require('@zepdb/zeppelin-embed');
+
+const store = openNamespace('my-database', 'documents', {
+  attributes: [{ id: 1, name: 'category', type: 'dictionaryString' }],
+  vectorSpace: { dimensions: 2 },
+});
+store.upsert([{
+  id: 1n,
+  vector: new Float32Array([0.9, 0.1]),
+  text: 'stored text',
+  attributes: [{ id: 1, type: 'string', value: 'example' }],
+}]);
+console.log(store.get([1n]));
+console.log(store.scan({ limit: 100 }));
+console.log(listNamespaces('my-database'));
+store.close();
+```
+
+Omit `vectorSpace` for a record-only namespace. Scan cursors are opaque and
+must be passed back unchanged; a cursor invalidated by a write throws
+`ZE_ERR_SCAN_STALE`.
+
 The initial package supports Node.js 18 or newer on macOS arm64. Unsupported
 platforms fail during installation and report a clear error if the package is
 loaded directly.

package/index.d.ts

@@ -19,12 +19,146 @@ export interface MutationReport {
   readonly generation: bigint;
 }
 
+export type DocumentId = bigint;
+
+export type AttributeType =
+  | 'u64'
+  | 'i64'
+  | 'f64'
+  | 'bool'
+  | 'dictionaryString'
+  | 'rawString';
+
+export interface AttributeDefinition {
+  readonly id: number;
+  readonly name: string;
+  readonly type: AttributeType;
+  readonly nullable?: boolean;
+}
+
+export type AttributeValue =
+  | { readonly id: number; readonly type: 'null'; readonly value: null }
+  | { readonly id: number; readonly type: 'u64'; readonly value: bigint }
+  | { readonly id: number; readonly type: 'i64'; readonly value: bigint }
+  | { readonly id: number; readonly type: 'f64'; readonly value: number }
+  | { readonly id: number; readonly type: 'bool'; readonly value: boolean }
+  | { readonly id: number; readonly type: 'string'; readonly value: string };
+
+export interface VectorSpace {
+  readonly dimensions: number;
+  readonly normalization?: 'none' | 'unitL2';
+}
+
+export interface NamespaceSpec {
+  readonly attributes?: readonly AttributeDefinition[];
+  readonly vectorSpace?: VectorSpace;
+}
+
+export interface UpsertDocument {
+  readonly id: DocumentId;
+  readonly revision?: bigint;
+  readonly timestamp?: bigint;
+  readonly vector?: Float32Array;
+  readonly text?: string;
+  readonly metadata?: Uint8Array;
+  readonly attributes?: readonly AttributeValue[];
+}
+
+export interface DocumentFields {
+  readonly vector?: boolean;
+  readonly text?: boolean;
+  readonly metadata?: boolean;
+  readonly attributes?: boolean;
+}
+
+export interface StoredDocument {
+  readonly id: DocumentId;
+  readonly revision: bigint;
+  readonly timestamp: bigint;
+  readonly vector?: Float32Array;
+  readonly text?: string;
+  readonly metadata?: Uint8Array;
+  readonly attributes?: AttributeValue[];
+}
+
+export interface GetResult {
+  readonly documents: Array<StoredDocument | null>;
+  readonly missingCount: number;
+  readonly generation: bigint;
+}
+
+declare const scanCursorBrand: unique symbol;
+
+export interface ScanCursor {
+  readonly [scanCursorBrand]: never;
+}
+
+export type Filter =
+  | {
+      readonly op: 'eq' | 'notEq' | 'in' | 'notIn';
+      readonly attributeId: number;
+      readonly values: readonly AttributeValue[];
+    }
+  | {
+      readonly op: 'range';
+      readonly attributeId: number;
+      readonly lower?: AttributeValue;
+      readonly lowerInclusive?: boolean;
+      readonly upper?: AttributeValue;
+      readonly upperInclusive?: boolean;
+    }
+  | { readonly op: 'exists' | 'isNull'; readonly attributeId: number }
+  | { readonly op: 'and' | 'or'; readonly children: readonly Filter[] }
+  | { readonly op: 'not'; readonly children: readonly [Filter] };
+
+export interface TimestampRange {
+  readonly start: bigint;
+  readonly end: bigint;
+}
+
+export interface ScanRequest {
+  readonly cursor?: ScanCursor;
+  readonly limit?: number;
+  readonly order?: 'storage' | 'timestampAscending' | 'timestampDescending';
+  readonly fields?: DocumentFields;
+  readonly timestampRange?: TimestampRange;
+  readonly filter?: Filter;
+}
+
+export interface ScanPage {
+  readonly documents: StoredDocument[];
+  readonly generation: bigint;
+  readonly cursor: ScanCursor | null;
+}
+
+export interface CountRequest {
+  readonly filter?: Filter;
+  readonly timestampRange?: TimestampRange;
+}
+
+export interface CountResult {
+  readonly count: bigint;
+  readonly generation: bigint;
+}
+
+export interface SearchOptions {
+  readonly k?: number;
+  readonly threadBudget?: number;
+  readonly tier?: 'auto' | 'exact' | 'scan' | 'graph';
+  readonly graphProfile?: 'sift' | 'angular';
+  readonly graphEf?: number;
+  readonly graphSeed?: bigint;
+  readonly deadlineNs?: bigint;
+}
+
 export interface SearchHit {
   readonly id: bigint;
   readonly revision: bigint;
   readonly score: number;
 }
 
+export type SearchResult = SearchHit[];
+
 export declare class ZeppelinError extends Error {
   constructor(message: string, code: string, errorCode: number);
   readonly code: string;
@@ -39,8 +173,27 @@ export declare class UnsupportedPlatformError extends Error {
 export declare class Store {
   constructor(path: string, options?: OpenOptions);
   ingest(documents: readonly Document[], dimension: number): MutationReport;
+  upsert(documents: readonly UpsertDocument[]): MutationReport;
+  get(ids: readonly DocumentId[], fields?: DocumentFields): GetResult;
+  delete(ids: readonly DocumentId[]): MutationReport;
+  scan(request?: ScanRequest): ScanPage;
+  count(request?: CountRequest): CountResult;
+  searchFiltered(
+    vector: Float32Array,
+    filter: Filter,
+    options?: SearchOptions,
+  ): SearchResult;
   search(vector: Float32Array, k: number): SearchHit[];
   close(): void;
 }
 
 export declare const ABI_VERSION: number;
+
+export declare function openNamespace(
+  root: string,
+  name: string,
+  spec: NamespaceSpec,
+  options?: OpenOptions,
+): Store;
+
+export declare function listNamespaces(root: string): string[];

package/index.js

@@ -58,6 +58,30 @@ class Store {
     return callNative(() => this._native.ingest(documents, dimension));
   }
 
+  upsert(documents) {
+    return callNative(() => this._native.upsert(documents));
+  }
+
+  get(ids, fields) {
+    return callNative(() => this._native.get(ids, fields));
+  }
+
+  delete(ids) {
+    return callNative(() => this._native.delete(ids));
+  }
+
+  scan(request) {
+    return callNative(() => this._native.scan(request));
+  }
+
+  count(request) {
+    return callNative(() => this._native.count(request));
+  }
+
+  searchFiltered(vector, filter, options) {
+    return callNative(() => this._native.searchFiltered(vector, filter, options));
+  }
+
   search(vector, k) {
     return callNative(() => this._native.search(vector, k));
   }
@@ -67,9 +91,23 @@ class Store {
   }
 }
 
+function openNamespace(root, name, spec, options = {}) {
+  return callNative(() => {
+    const store = Object.create(Store.prototype);
+    store._native = new binding.NativeStore(root, options, name, spec);
+    return store;
+  });
+}
+
+function listNamespaces(root) {
+  return callNative(() => binding.listNamespaces(root));
+}
+
 module.exports = {
   ABI_VERSION: binding.abiVersion,
   Store,
   UnsupportedPlatformError,
   ZeppelinError,
+  listNamespaces,
+  openNamespace,
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@zepdb/zeppelin-embed",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "In-process vector search for macOS and Apple silicon",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zepdb/zeppelin-embed.git",
-    "directory": "node"
+    "directory": "bindings/node"
   },
   "homepage": "https://github.com/zepdb/zeppelin-embed#readme",
   "bugs": "https://github.com/zepdb/zeppelin-embed/issues",