vectlite 0.1.12 → 0.9.0

package/README.md

@@ -43,10 +43,12 @@ db.close()
 ### Core
 
 - **Single-file storage** -- one `.vdb` file per database, portable and easy to back up
-- **Dense vectors** -- cosine similarity with automatic HNSW indexing for large collections
+- **Distance metrics** -- cosine (default), euclidean (L2), dot product, manhattan (L1) with SIMD acceleration
+- **Dense vectors** -- automatic HNSW indexing with metric-aware distance functions
 - **Sparse vectors** -- BM25-scored inverted index for keyword retrieval
 - **Hybrid search** -- dense + sparse fusion with linear or RRF strategies
 - **Vector quantization** -- scalar (int8, 4x), binary (32x), and product quantization (PQ) with 2-stage rescoring
+- **Multi-vector / ColBERT** -- late interaction search with per-token MaxSim scoring and 2-bit quantization (~16x compression)
 - **Rich metadata** -- string, number, boolean, null, array, and nested object values
 - **Crash-safe WAL** -- writes land in a write-ahead log first, then checkpoint with `compact()`
 - **Transactions** -- atomic batched writes with `db.transaction()`
@@ -61,6 +63,7 @@ db.close()
 - **MMR diversification** -- `mmrLambda` controls relevance vs. diversity trade-off
 - **Namespaces** -- logical isolation with per-namespace or cross-namespace search
 - **Observability** -- `searchWithStats()` returns timings, BM25 term scores, ANN stats, and per-result explain payloads
+- **Payload indexes** -- keyword and numeric indexes on metadata fields accelerate filtered queries on large collections
 
 ### Data Management
 
@@ -68,14 +71,35 @@ db.close()
 - **Bulk ingestion** -- `bulkIngest()` with deferred index rebuilds for fast imports
 - **Listing & filtered counts** -- `list()` and `count({ namespace, filter })` without a vector query
 - **Delete by filter** -- `deleteByFilter()` for bulk deletion by metadata filter
+- **Partial metadata updates** -- `updateMetadata()` merges a patch without re-writing the vector or rebuilding indexes
 - **Snapshots** -- `db.snapshot(path)` creates a self-contained copy
 - **Backup / Restore** -- `db.backup(dir)` and `vectlite.restore(dir, path)` for full roundtrips
 - **Read-only mode** -- `vectlite.open(path, { readOnly: true })` for safe concurrent readers
 - **Explicit close** -- `db.close()` to release locks deterministically
 - **Lock timeouts** -- `lockTimeout` for bounded lock acquisition waits
+- **TTL / Expiry** -- `setTtl()` / `clearTtl()` or `ttl` option on insert/upsert; expired records auto-filtered from reads and GC'd on compact
+- **Cursor-based pagination** -- `listCursor()` for efficient iteration over large collections
+- **Async API** -- `searchAsync()`, `compactAsync()`, `flushAsync()`, `bulkIngestAsync()` run on the libuv threadpool
 
 ## Usage
 
+### Distance Metrics
+
+```js
+// Default is cosine similarity
+const db = vectlite.open('knowledge.vdb', { dimension: 384 })
+
+// Choose a different metric at creation time
+const db2 = vectlite.open('knowledge.vdb', { dimension: 384, metric: 'euclidean' })
+const db3 = vectlite.open('knowledge.vdb', { dimension: 384, metric: 'dotproduct' })
+const db4 = vectlite.open('knowledge.vdb', { dimension: 384, metric: 'manhattan' })
+
+// Aliases: 'l2', 'dot', 'ip', 'l1'
+console.log(db2.metric) // "euclidean"
+```
+
+The metric is persisted in the database file. Scores are always oriented so that **higher is better**.
+
 ### Hybrid Search
 
 ```js
@@ -167,6 +191,9 @@ const records = db.list({ namespace: 'docs', filter: { stale: false }, limit: 20
 const count = db.count({ namespace: 'docs', filter: { source: 'blog' } })
 const deleted = db.deleteByFilter({ stale: true }, { namespace: 'docs' })
 
+// Partial metadata update (merge patch -- only touches specified keys)
+db.updateMetadata('doc1', { status: 'reviewed', score: 0.95 })
+
 db.close()
 ```
 
@@ -184,6 +211,24 @@ console.log(outcome.stats.used_ann)     // true
 console.log(outcome.results[0].explain) // Detailed scoring breakdown
 ```
 
+### Payload Indexes
+
+Create keyword or numeric indexes on metadata fields to accelerate filtered queries on large collections. Indexes are automatically used by `search()`, `count()`, and `list()`.
+
+```js
+// Create indexes on frequently-filtered fields
+db.createIndex('source', 'keyword')   // string equality, $in
+db.createIndex('score', 'numeric')    // range queries: $gt, $gte, $lt, $lte
+
+// Filtered queries now use indexes automatically
+const count = db.count({ filter: { source: 'blog' } })
+const results = db.search(query, { k: 10, filter: { score: { $gte: 0.8 } } })
+
+// Inspect and manage indexes
+console.log(db.listIndexes())  // [{ field: 'source', type: 'keyword' }, ...]
+db.dropIndex('score')
+```
+
 ### Vector Quantization
 
 Reduce memory usage and accelerate search with quantized vectors. All methods use a 2-stage pipeline: fast quantized candidate selection followed by exact float32 rescoring.
@@ -211,6 +256,130 @@ db.disableQuantization()
 
 Quantization parameters persist across reopens in a `.vdb.quant` sidecar file. The quantized index auto-rebuilds on inserts and upserts.
 
+### Multi-Vector / ColBERT Search
+
+Store token-level embeddings (ColBERT, ColPali) and search with MaxSim late interaction scoring.
+
+```js
+// Upsert with per-token ColBERT embeddings
+db.upsertMultiVectors('doc1', denseVector,
+  JSON.stringify({ colbert: [tokenVec1, tokenVec2] }),
+  JSON.stringify({ metadata: { source: 'paper' } })
+)
+
+// MaxSim search
+const results = JSON.parse(
+  db.searchMultiVector('colbert', JSON.stringify(queryTokenVectors))
+)
+
+// Enable 2-bit quantization (~16x compression)
+db.enableMultiVectorQuantization('colbert')
+
+// Check and disable
+console.log(db.isMultiVectorQuantized('colbert'))  // true
+db.disableMultiVectorQuantization('colbert')
+```
+
+### TTL / Expiry
+
+Records can automatically expire after a time-to-live. Expired records are transparently filtered from all reads and permanently removed on `compact()`.
+
+```js
+// Set TTL on insert/upsert (seconds)
+db.upsert('session1', embedding, { user: 'alice' }, { ttl: 3600 }) // expires in 1 hour
+
+// Set/clear TTL on existing records
+db.setTtl('doc1', 86400)    // expire in 24 hours
+db.clearTtl('doc1')          // remove expiry
+
+// Expired records are invisible to get/list/count/search
+const record = db.get('session1') // null after TTL elapses
+
+// compact() garbage-collects expired records from disk
+db.compact()
+```
+
+### Cursor-Based Pagination
+
+Efficiently iterate over large collections without offset overhead.
+
+```js
+// Paginate 100 records at a time
+let cursor = null
+do {
+  const page = db.listCursor({ limit: 100, cursor })
+  for (const record of page.records) {
+    process(record)
+  }
+  cursor = page.cursor
+} while (cursor !== null)
+
+// Works with namespace and filter
+const page = db.listCursor({ namespace: 'docs', filter: { source: 'blog' }, limit: 50 })
+```
+
+### Async API
+
+Non-blocking versions of heavy operations that run on the libuv threadpool.
+
+```js
+// Async search (returns a Promise)
+const results = await db.searchAsync(queryEmbedding, { k: 10, filter: { source: 'blog' } })
+
+// Async search with stats
+const outcome = await db.searchWithStatsAsync(queryEmbedding, { k: 10 })
+
+// Async maintenance
+await db.flushAsync()
+await db.compactAsync()
+
+// Async bulk ingestion
+const count = await db.bulkIngestAsync(records, { batchSize: 5000 })
+```
+
+### OpenTelemetry Integration
+
+vectlite ships with optional OpenTelemetry tracing. When enabled, every search
+call is wrapped in a span carrying semantic DB attributes and search-specific
+metrics. `@opentelemetry/api` is loaded lazily -- it is **not** a runtime
+dependency.
+
+```js
+const vectlite = require('vectlite')
+
+// Auto-detect: resolves a tracer from @opentelemetry/api if installed
+const tracer = vectlite.configureOpenTelemetry()
+
+// Or supply your own tracer
+vectlite.configureOpenTelemetry({ tracer: myTracer })
+
+// Custom tracer name (default: 'vectlite')
+vectlite.configureOpenTelemetry({ tracerName: 'my-app' })
+
+// Disable
+vectlite.configureOpenTelemetry(false)
+```
+
+When a tracer is active, each `search` / `searchWithStats` / `searchAsync` /
+`searchWithStatsAsync` call creates a `vectlite.search` span with these
+attributes:
+
+| Attribute | Description |
+|---|---|
+| `db.system` | Always `"vectlite"` |
+| `db.operation.name` | Always `"search"` |
+| `vectlite.search.k` | Requested result count |
+| `vectlite.search.namespace` | Target namespace |
+| `vectlite.search.has_dense` | Whether a dense query vector was provided |
+| `vectlite.search.has_sparse` | Whether sparse terms were provided |
+| `vectlite.search.fusion` | Fusion strategy (`"linear"` or `"rrf"`) |
+| `vectlite.search.used_ann` | Whether HNSW was used (set after completion) |
+| `vectlite.search.result_count` | Number of results returned (set after completion) |
+| `vectlite.search.total_us` | Total search time in microseconds (set after completion) |
+
+If a search throws, the span records the exception and sets an error status
+before re-throwing.
+
 ## Database Methods Reference
 
 ### Write Methods
@@ -225,6 +394,9 @@ Quantization parameters persist across reopens in a `.vdb.quant` sidecar file. T
 | `db.delete(id, { namespace })` | Delete a single record |
 | `db.deleteMany(ids, { namespace })` | Delete multiple records by id |
 | `db.deleteByFilter(filter, { namespace })` | Delete all records matching a filter |
+| `db.updateMetadata(id, metadata, { namespace })` | Merge a metadata patch into an existing record (no vector rewrite) |
+| `db.setTtl(id, seconds, { namespace })` | Set time-to-live on a record (seconds from now) |
+| `db.clearTtl(id, { namespace })` | Remove TTL from a record |
 
 ### Read Methods
 
@@ -235,11 +407,21 @@ Quantization parameters persist across reopens in a `.vdb.quant` sidecar file. T
 | `db.searchWithStats(query, options)` | Search with detailed performance stats |
 | `db.count({ namespace, filter })` | Count records, optionally scoped by namespace/filter |
 | `db.list({ namespace, filter, limit, offset })` | List records without issuing a vector query |
+| `db.listCursor({ namespace, filter, limit, cursor })` | Cursor-based pagination for large collections |
 | `db.namespaces()` | List all namespaces |
 | `db.dimension` | Vector dimension (property) |
 | `db.path` | Database file path (property) |
+| `db.metric` | Distance metric name: `"cosine"`, `"euclidean"`, `"dotproduct"`, or `"manhattan"` (property) |
 | `db.readOnly` | Whether the database is read-only (property) |
 
+### Index Methods
+
+| Method | Description |
+|---|---|
+| `db.createIndex(field, indexType)` | Create a payload index (`'keyword'` or `'numeric'`) on a metadata field |
+| `db.dropIndex(field)` | Remove an index |
+| `db.listIndexes()` | List all active indexes as `[{ field, type }, ...]` |
+
 ### Quantization Methods
 
 | Method | Description |
@@ -260,6 +442,16 @@ Quantization parameters persist across reopens in a `.vdb.quant` sidecar file. T
 | `db.transaction()` | Begin an atomic transaction |
 | `db.close()` | Flush pending state, release the file lock, and invalidate the handle |
 
+### Async Methods
+
+| Method | Description |
+|---|---|
+| `db.searchAsync(query, options)` | Non-blocking search (returns Promise) |
+| `db.searchWithStatsAsync(query, options)` | Non-blocking search with stats (returns Promise) |
+| `db.flushAsync()` | Non-blocking flush/compact (returns Promise) |
+| `db.compactAsync()` | Non-blocking compact (returns Promise) |
+| `db.bulkIngestAsync(records, options)` | Non-blocking bulk import (returns Promise) |
+
 ## Filter Operators
 
 | Operator | Example | Description |

package/index.d.ts

@@ -21,6 +21,7 @@ export interface Record {
   vectors: NamedVectors
   sparse: SparseVector
   metadata: Metadata
+  expires_at: number | null
 }
 
 export interface SearchTimings {
@@ -41,6 +42,8 @@ export interface SearchStats {
   ann_loaded_from_disk: boolean
   wal_entries_replayed: number
   fusion: string
+  effective_dimension: number
+  matryoshka_truncated: boolean
   rerank_applied: boolean
   rerank_count: number
   timings: SearchTimings
@@ -80,6 +83,7 @@ export interface WriteOptions {
   namespace?: string | null
   sparse?: SparseVector | null
   vectors?: NamedVectors | null
+  ttl?: number | null
 }
 
 export interface CountOptions {
@@ -92,6 +96,16 @@ export interface ListOptions extends CountOptions {
   offset?: number | null
 }
 
+export interface ListCursorOptions extends CountOptions {
+  limit?: number | null
+  cursor?: string | null
+}
+
+export interface ListCursorResult {
+  records: Record[]
+  cursor: string | null
+}
+
 export interface BulkIngestOptions {
   namespace?: string | null
   batchSize?: number
@@ -110,15 +124,19 @@ export interface SearchOptions {
   vectorName?: string | null
   fusion?: 'linear' | 'rrf'
   rrfK?: number
+  truncateDim?: number | null
   explain?: boolean
   queryVectors?: { [name: string]: number[] } | null
   vectorWeights?: { [name: string]: number } | null
 }
 
+export type DistanceMetric = 'cosine' | 'euclidean' | 'dotproduct' | 'manhattan' | 'l2' | 'dot' | 'ip' | 'l1'
+
 export interface OpenOptions {
   dimension?: number | null
   readOnly?: boolean
   lockTimeout?: number | null
+  metric?: DistanceMetric | null
 }
 
 export class VectLiteError extends Error {}
@@ -139,12 +157,14 @@ export class Database {
   readonly path: string
   readonly walPath: string
   readonly dimension: number
+  readonly metric: string
   readonly readOnly: boolean
 
   count(options?: CountOptions): number
   namespaces(): string[]
   close(): void
   list(options?: ListOptions): Record[]
+  listCursor(options?: ListCursorOptions): ListCursorResult
   transaction(): Transaction
   insert(id: string, vector: number[], metadata?: Metadata | null, options?: WriteOptions): void
   upsert(id: string, vector: number[], metadata?: Metadata | null, options?: WriteOptions): void
@@ -155,12 +175,23 @@ export class Database {
   delete(id: string, options?: { namespace?: string | null }): boolean
   deleteMany(ids: string[], options?: { namespace?: string | null }): number
   deleteByFilter(filter: Filter, options?: { namespace?: string | null }): number
+  updateMetadata(id: string, metadata: Metadata, options?: { namespace?: string | null }): boolean
+  setTtl(id: string, ttl: number, options?: { namespace?: string | null }): boolean
+  clearTtl(id: string, options?: { namespace?: string | null }): boolean
+  createIndex(field: string, indexType: 'keyword' | 'numeric'): boolean
+  dropIndex(field: string): boolean
+  listIndexes(): Array<{ field: string; type: 'keyword' | 'numeric' }>
   flush(): void
   compact(): void
   snapshot(dest: string): void
   backup(dest: string): void
   search(query?: number[] | null, options?: SearchOptions): SearchResult[]
   searchWithStats(query?: number[] | null, options?: SearchOptions): SearchResponse
+  searchAsync(query?: number[] | null, options?: SearchOptions): Promise<SearchResult[]>
+  searchWithStatsAsync(query?: number[] | null, options?: SearchOptions): Promise<SearchResponse>
+  flushAsync(): Promise<void>
+  compactAsync(): Promise<void>
+  bulkIngestAsync(records: Record[], options?: BulkIngestOptions): Promise<number>
 }
 
 export class Store {
@@ -176,6 +207,30 @@ export class Store {
 export function open(path: string, options?: OpenOptions): Database
 export function openStore(root: string): Store
 export function restore(source: string, dest: string): Database
+export interface OpenTelemetryOptions {
+  /** Pass `false` or `{ enabled: false }` to disable tracing. */
+  enabled?: boolean
+  /** Supply your own OTel `Tracer` instance. */
+  tracer?: unknown
+  /** Tracer name used when auto-resolving via `@opentelemetry/api`. Defaults to `'vectlite'`. */
+  tracerName?: string
+}
+
+/**
+ * Configure optional OpenTelemetry tracing for search operations.
+ *
+ * When a tracer is active, every `search`, `searchWithStats`, `searchAsync`,
+ * and `searchWithStatsAsync` call is wrapped in a span with semantic
+ * `db.system` / `db.operation.name` attributes and search-specific metrics.
+ *
+ * `@opentelemetry/api` is loaded lazily via `require()` -- it is **not** a
+ * runtime dependency. If the package is not installed the function returns
+ * `null` and search calls remain un-instrumented.
+ *
+ * @returns The resolved tracer, or `null` if tracing could not be configured.
+ */
+export function configureOpenTelemetry(options?: OpenTelemetryOptions | false): unknown | null
+
 export function sparseTerms(text: string): SparseVector
 export function upsertText(
   db: Database,

package/index.js

@@ -63,6 +63,7 @@ function loadNative() {
 const native = loadNative()
 
 const TOKEN_RE = /[a-z0-9]+/g
+let otelTracer = null
 
 class VectLiteError extends Error {
   constructor(message, cause) {
@@ -102,6 +103,84 @@ function decode(value) {
   return value == null ? null : JSON.parse(value)
 }
 
+function configureOpenTelemetry(options = {}) {
+  if (options === false || options?.enabled === false) {
+    otelTracer = null
+    return null
+  }
+  if (options?.tracer != null) {
+    otelTracer = options.tracer
+    return otelTracer
+  }
+  try {
+    const { trace } = require('@opentelemetry/api')
+    otelTracer = trace.getTracer(options?.tracerName ?? 'vectlite')
+    return otelTracer
+  } catch {
+    otelTracer = null
+    return null
+  }
+}
+
+function searchAttributes(query, options, stats = null) {
+  const attrs = {
+    'db.system': 'vectlite',
+    'db.operation.name': 'search',
+    'vectlite.search.k': options?.k ?? 10,
+    'vectlite.search.namespace': options?.namespace ?? '',
+    'vectlite.search.all_namespaces': Boolean(options?.allNamespaces),
+    'vectlite.search.has_dense': query != null,
+    'vectlite.search.has_sparse': options?.sparse != null,
+    'vectlite.search.fusion': options?.fusion ?? 'linear',
+  }
+  if (options?.vectorName != null) attrs['vectlite.search.vector_name'] = options.vectorName
+  if (options?.truncateDim != null) attrs['vectlite.search.truncate_dim'] = options.truncateDim
+  if (stats != null) {
+    attrs['vectlite.search.used_ann'] = Boolean(stats.used_ann)
+    attrs['vectlite.search.exact_fallback'] = Boolean(stats.exact_fallback)
+    attrs['vectlite.search.considered_count'] = stats.considered_count ?? 0
+    attrs['vectlite.search.result_count'] = stats.result_count ?? 0
+    attrs['vectlite.search.effective_dimension'] = stats.effective_dimension ?? 0
+    attrs['vectlite.search.matryoshka_truncated'] = Boolean(stats.matryoshka_truncated)
+    attrs['vectlite.search.total_us'] = stats.timings?.total_us ?? 0
+  }
+  return attrs
+}
+
+function withSearchSpan(query, options, fn) {
+  if (otelTracer == null) {
+    return fn()
+  }
+  return otelTracer.startActiveSpan('vectlite.search', { attributes: searchAttributes(query, options) }, (span) => {
+    try {
+      const value = fn()
+      if (isPromiseLike(value)) {
+        return value.then(
+          (resolved) => {
+            span.setAttributes(searchAttributes(query, options, resolved?.stats ?? null))
+            span.end()
+            return resolved
+          },
+          (error) => {
+            span.recordException?.(error)
+            span.setStatus?.({ code: 2, message: error?.message ?? String(error) })
+            span.end()
+            throw error
+          },
+        )
+      }
+      span.setAttributes(searchAttributes(query, options, value?.stats ?? null))
+      span.end()
+      return value
+    } catch (error) {
+      span.recordException?.(error)
+      span.setStatus?.({ code: 2, message: error?.message ?? String(error) })
+      span.end()
+      throw error
+    }
+  })
+}
+
 function asArray(values) {
   return Array.from(values)
 }
@@ -123,6 +202,7 @@ function normalizeWriteOptions(options = {}) {
     namespace: options.namespace ?? null,
     sparse: options.sparse ?? null,
     vectors: options.vectors ?? null,
+    ttl: options.ttl ?? null,
   }
 }
 
@@ -150,16 +230,16 @@ class Transaction {
   }
 
   insert(id, vector, metadata = null, options = {}) {
-    const { namespace, sparse, vectors } = normalizeWriteOptions(options)
+    const { namespace, sparse, vectors, ttl } = normalizeWriteOptions(options)
     return wrapError(() =>
-      this._native.insert(id, asArray(vector), encode(metadata), namespace, encode(sparse), encode(vectors)),
+      this._native.insert(id, asArray(vector), encode(metadata), namespace, encode(sparse), encode(vectors), ttl),
     )
   }
 
   upsert(id, vector, metadata = null, options = {}) {
-    const { namespace, sparse, vectors } = normalizeWriteOptions(options)
+    const { namespace, sparse, vectors, ttl } = normalizeWriteOptions(options)
     return wrapError(() =>
-      this._native.upsert(id, asArray(vector), encode(metadata), namespace, encode(sparse), encode(vectors)),
+      this._native.upsert(id, asArray(vector), encode(metadata), namespace, encode(sparse), encode(vectors), ttl),
     )
   }
 
@@ -205,6 +285,10 @@ class Database {
     return wrapError(() => this._native.dimension)
   }
 
+  get metric() {
+    return wrapError(() => this._native.metric)
+  }
+
   get readOnly() {
     return wrapError(() => this._native.readOnly)
   }
@@ -234,21 +318,35 @@ class Database {
     )
   }
 
+  listCursor(options = {}) {
+    return wrapError(() => {
+      const raw = decode(
+        this._native.listCursor(
+          options.namespace ?? null,
+          encode(options.filter),
+          options.limit ?? null,
+          options.cursor ?? null,
+        ),
+      )
+      return { records: raw.records, cursor: raw.cursor ?? null }
+    })
+  }
+
   transaction() {
     return wrapError(() => new Transaction(this._native.transaction()))
   }
 
   insert(id, vector, metadata = null, options = {}) {
-    const { namespace, sparse, vectors } = normalizeWriteOptions(options)
+    const { namespace, sparse, vectors, ttl } = normalizeWriteOptions(options)
     return wrapError(() =>
-      this._native.insert(id, asArray(vector), encode(metadata), namespace, encode(sparse), encode(vectors)),
+      this._native.insert(id, asArray(vector), encode(metadata), namespace, encode(sparse), encode(vectors), ttl),
     )
   }
 
   upsert(id, vector, metadata = null, options = {}) {
-    const { namespace, sparse, vectors } = normalizeWriteOptions(options)
+    const { namespace, sparse, vectors, ttl } = normalizeWriteOptions(options)
     return wrapError(() =>
-      this._native.upsert(id, asArray(vector), encode(metadata), namespace, encode(sparse), encode(vectors)),
+      this._native.upsert(id, asArray(vector), encode(metadata), namespace, encode(sparse), encode(vectors), ttl),
     )
   }
 
@@ -282,6 +380,32 @@ class Database {
     return wrapError(() => this._native.deleteByFilter(encode(filter), options.namespace ?? null))
   }
 
+  updateMetadata(id, metadata, options = {}) {
+    return wrapError(() =>
+      this._native.updateMetadata(id, encode(metadata), options.namespace ?? null),
+    )
+  }
+
+  setTtl(id, ttl, options = {}) {
+    return wrapError(() => this._native.setTtl(id, ttl, options.namespace ?? null))
+  }
+
+  clearTtl(id, options = {}) {
+    return wrapError(() => this._native.clearTtl(id, options.namespace ?? null))
+  }
+
+  createIndex(field, indexType) {
+    return wrapError(() => this._native.createIndex(field, indexType))
+  }
+
+  dropIndex(field) {
+    return wrapError(() => this._native.dropIndex(field))
+  }
+
+  listIndexes() {
+    return wrapError(() => decode(this._native.listIndexes()))
+  }
+
   flush() {
     return wrapError(() => this._native.flush())
   }
@@ -299,12 +423,46 @@ class Database {
   }
 
   search(query = null, options = {}) {
-    return wrapError(() => decode(this._native.search(query == null ? null : asArray(query), encode(options))))
+    return withSearchSpan(query, options, () =>
+      wrapError(() => decode(this._native.search(query == null ? null : asArray(query), encode(options)))),
+    )
   }
 
   searchWithStats(query = null, options = {}) {
-    return wrapError(() =>
-      decode(this._native.searchWithStats(query == null ? null : asArray(query), encode(options))),
+    return withSearchSpan(query, options, () =>
+      wrapError(() =>
+        decode(this._native.searchWithStats(query == null ? null : asArray(query), encode(options))),
+      ),
+    )
+  }
+
+  searchAsync(query = null, options = {}) {
+    return withSearchSpan(query, options, () =>
+      wrapAsync(
+        this._native.searchAsync(query == null ? null : asArray(query), encode(options)),
+      ).then(decode),
+    )
+  }
+
+  searchWithStatsAsync(query = null, options = {}) {
+    return withSearchSpan(query, options, () =>
+      wrapAsync(
+        this._native.searchWithStatsAsync(query == null ? null : asArray(query), encode(options)),
+      ).then(decode),
+    )
+  }
+
+  flushAsync() {
+    return wrapAsync(this._native.flushAsync())
+  }
+
+  compactAsync() {
+    return wrapAsync(this._native.compactAsync())
+  }
+
+  bulkIngestAsync(records, options = {}) {
+    return wrapAsync(
+      this._native.bulkIngestAsync(encode(records), options.namespace ?? null, options.batchSize ?? 10_000),
     )
   }
 }
@@ -345,7 +503,7 @@ class Store {
 
 function open(path, options = {}) {
   return wrapError(() =>
-    new Database(native.open(path, options.dimension ?? null, options.readOnly ?? false, options.lockTimeout ?? null)),
+    new Database(native.open(path, options.dimension ?? null, options.readOnly ?? false, options.lockTimeout ?? null, options.metric ?? null)),
   )
 }
 
@@ -393,6 +551,7 @@ module.exports = {
   Store,
   Transaction,
   VectLiteError,
+  configureOpenTelemetry,
   open,
   openStore,
   restore,

package/native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vectlite-node"
-version = "0.1.12"
+version = "0.9.0"
 edition = "2024"
 license = "MIT"
 description = "Node.js bindings for vectlite."