vector-index

Bun.VectorIndex exposes Bun's existing native vector index. It requires the optional browser_index provider, enabled in a checkout with bun bd --browser-index=on. Check Bun.VectorIndex.available before opening it.

if (!Bun.VectorIndex.available) throw new Error("Vector index provider unavailable");

const index = new Bun.VectorIndex("/absolute/private/search.index", {
  dimensions: 3,
  metric: "l2",
});
try {
  index.add(1n, new Float32Array([1, 0, 0]));
  index.add(2n, [0, 1, 0]);
  const hits = index.search([1, 0, 0], 5, { allowedKeys: [1n] });
  // [{ key: 1n, score: 0 }]
  index.save();
} finally {
  index.close();
}

The constructor opens an existing native index or creates an in-memory index with that persistence path. Reopening requires the stored dimensions and metric to match. save() writes the native persistent format atomically. close() is idempotent and does not save implicitly.

Keys are bigint values in 0n..18446744073709551615n. Numeric keys are rejected; search results retain the full unsigned 64-bit value. Adding an existing key updates its vector. Vectors must contain exactly dimensions finite elements. remove(key) returns whether a live key was removed. count and dimensions describe the open index.

search(vector, k, { allowedKeys, ef }) applies the allowed key set before selecting neighbors. Omitting the set searches all live keys; an empty set returns no hits. It also accepts a BigUint64Array. The optional ef controls the native search breadth.

Scores are larger for closer matches. L2 returns negative squared distance; cosine uses the native cosine metric. L2 is the default. Operations are synchronous; use an application-owned Worker for large ingestion batches.

The index stores supplied embeddings. The application owns the model, dimensions, preprocessing, row identity mapping and generation manifest. Publish the document store and vector index as one verified generation before switching readers.