vectlite 0.1.12 → 0.9.1

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,10 +103,140 @@ 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) {
+  if (
+    values != null &&
+    typeof values === 'object' &&
+    !Array.isArray(values) &&
+    !ArrayBuffer.isView(values) &&
+    typeof values[Symbol.iterator] !== 'function' &&
+    typeof values.length !== 'number'
+  ) {
+    throw new TypeError('vector must be an array-like or iterable of numbers')
+  }
   return Array.from(values)
 }
 
+function encodeNativeOptions(value) {
+  return typeof value === 'string' ? value : encode(value)
+}
+
+const SEARCH_OPTION_KEYS = new Set([
+  'query',
+  'k',
+  'filter',
+  'namespace',
+  'allNamespaces',
+  'sparse',
+  'denseWeight',
+  'sparseWeight',
+  'fetchK',
+  'mmrLambda',
+  'vectorName',
+  'fusion',
+  'rrfK',
+  'truncateDim',
+  'explain',
+  'queryVectors',
+  'vectorWeights',
+])
+
+function isSearchRequestObject(value) {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    !ArrayBuffer.isView(value) &&
+    [...SEARCH_OPTION_KEYS].some((key) => Object.prototype.hasOwnProperty.call(value, key))
+  )
+}
+
+function normalizeSearchArgs(query, options) {
+  if (isSearchRequestObject(query) && (options == null || Object.keys(options).length === 0)) {
+    const { query: normalizedQuery = null, ...normalizedOptions } = query
+    return { query: normalizedQuery, options: normalizedOptions }
+  }
+  return { query, options: options ?? {} }
+}
+
 function isPromiseLike(value) {
   return value != null && typeof value.then === 'function'
 }
@@ -123,6 +254,7 @@ function normalizeWriteOptions(options = {}) {
     namespace: options.namespace ?? null,
     sparse: options.sparse ?? null,
     vectors: options.vectors ?? null,
+    ttl: options.ttl ?? null,
   }
 }
 
@@ -150,16 +282,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 +337,10 @@ class Database {
     return wrapError(() => this._native.dimension)
   }
 
+  get metric() {
+    return wrapError(() => this._native.metric)
+  }
+
   get readOnly() {
     return wrapError(() => this._native.readOnly)
   }
@@ -234,21 +370,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 +432,78 @@ 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()))
+  }
+
+  enableQuantization(method = 'scalar', options = {}) {
+    return wrapError(() => this._native.enableQuantization(method, encodeNativeOptions(options)))
+  }
+
+  disableQuantization() {
+    return wrapError(() => this._native.disableQuantization())
+  }
+
+  get isQuantized() {
+    return wrapError(() => this._native.isQuantized)
+  }
+
+  get quantizationMethod() {
+    return wrapError(() => this._native.quantizationMethod)
+  }
+
+  validNumSubVectors() {
+    return wrapError(() => this._native.validNumSubVectors())
+  }
+
+  upsertMultiVectors(id, vector, multiVectors, options = {}) {
+    return wrapError(() =>
+      this._native.upsertMultiVectors(id, asArray(vector), encode(multiVectors), encode(options)),
+    )
+  }
+
+  searchMultiVector(space, queryTokens, options = {}) {
+    return wrapError(() =>
+      decode(this._native.searchMultiVector(space, encode(queryTokens), encode(options))),
+    )
+  }
+
+  enableMultiVectorQuantization(space, options = {}) {
+    return wrapError(() =>
+      this._native.enableMultiVectorQuantization(space, encodeNativeOptions(options)),
+    )
+  }
+
+  disableMultiVectorQuantization(space) {
+    return wrapError(() => this._native.disableMultiVectorQuantization(space))
+  }
+
+  isMultiVectorQuantized(space) {
+    return wrapError(() => this._native.isMultiVectorQuantized(space))
+  }
+
   flush() {
     return wrapError(() => this._native.flush())
   }
@@ -299,12 +521,68 @@ class Database {
   }
 
   search(query = null, options = {}) {
-    return wrapError(() => decode(this._native.search(query == null ? null : asArray(query), encode(options))))
+    const normalized = normalizeSearchArgs(query, options)
+    return withSearchSpan(normalized.query, normalized.options, () =>
+      wrapError(() =>
+        decode(
+          this._native.search(
+            normalized.query == null ? null : asArray(normalized.query),
+            encode(normalized.options),
+          ),
+        ),
+      ),
+    )
   }
 
   searchWithStats(query = null, options = {}) {
-    return wrapError(() =>
-      decode(this._native.searchWithStats(query == null ? null : asArray(query), encode(options))),
+    const normalized = normalizeSearchArgs(query, options)
+    return withSearchSpan(normalized.query, normalized.options, () =>
+      wrapError(() =>
+        decode(
+          this._native.searchWithStats(
+            normalized.query == null ? null : asArray(normalized.query),
+            encode(normalized.options),
+          ),
+        ),
+      ),
+    )
+  }
+
+  searchAsync(query = null, options = {}) {
+    const normalized = normalizeSearchArgs(query, options)
+    return withSearchSpan(normalized.query, normalized.options, () =>
+      wrapAsync(
+        this._native.searchAsync(
+          normalized.query == null ? null : asArray(normalized.query),
+          encode(normalized.options),
+        ),
+      ).then(decode),
+    )
+  }
+
+  searchWithStatsAsync(query = null, options = {}) {
+    const normalized = normalizeSearchArgs(query, options)
+    return withSearchSpan(normalized.query, normalized.options, () =>
+      wrapAsync(
+        this._native.searchWithStatsAsync(
+          normalized.query == null ? null : asArray(normalized.query),
+          encode(normalized.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),
     )
   }
 }
@@ -341,11 +619,15 @@ class Store {
   collections() {
     return wrapError(() => this._native.collections())
   }
+
+  close() {
+    return wrapError(() => this._native.close())
+  }
 }
 
 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 +675,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.1"
 edition = "2024"
 license = "MIT"
 description = "Node.js bindings for vectlite."