Class: VectorStoreWrapper

VectorStoreWrapper(dimensions)

new VectorStoreWrapper(dimensions)

Creates a new VectorStore instance

Parameters:
Name Type Description
dimensions number

The dimensionality of embedding vectors (e.g., 1536 for OpenAI embeddings)
Throws:

If dimensions is not a positive integer

Type
TypeError

Methods

addDocument(doc) → {void}

Add a single document to the store. Only works before finalization.

Parameters:
Name Type Description
doc Document

Document object with embedding in metadata
Throws:

If called after finalization or document format is invalid

Type
Error
Returns:
Type
void
Example
store.addDocument({
  id: 'doc-1',
  text: 'Sample document',
  metadata: {
    embedding: new Array(1536).fill(0).map(() => Math.random())
  }
});

finalize() → {void}

Finalize the store: normalize all embeddings and switch to serving mode. After calling this, no more documents can be added but searches become available. This is automatically called by loadDir().

Returns:
Type
void
Example
// Manual finalization after adding documents
store.addDocument(doc1);
store.addDocument(doc2);
store.finalize(); // Must call before searching

isFinalized() → {boolean}

Check if the store has been finalized and is ready for searching.

Returns:

True if finalized, false otherwise

Type
boolean
Example
if (store.isFinalized()) {
  const results = store.search(query, 10);
}

loadDir(path) → {void}

Load all JSON documents from a directory and automatically finalize the store. Documents should contain embedding vectors in their metadata field. Supports both single documents and arrays of documents per file.

Parameters:
Name Type Description
path string

Absolute or relative path to directory containing JSON files
Throws:

If directory doesn't exist or contains invalid JSON

Type
Error
Returns:
Type
void
Examples
// Load documents from a directory
store.loadDir('./knowledge-base');
// Store is automatically finalized and ready for searches
// Standard format with 'text' field
{
  "id": "doc-123",
  "text": "Document content...",
  "metadata": {
    "embedding": [0.1, 0.2, ...],  // Required: embedding vector
    "category": "product"           // Optional: additional metadata
  }
}
// Spring AI format with 'content' field
{
  "id": "doc-456",
  "content": "Document content...",  // 'content' instead of 'text'
  "metadata": {
    "embedding": [0.1, 0.2, ...],
    "category": "spring-ai"
  }
}

normalize() → {void}

Deprecated:
  • Use finalize() instead
Returns:
Type
void

Search for the k most similar documents to a query embedding. Uses SIMD-optimized cosine similarity for fast performance.

Parameters:
Name Type Attributes Default Description
query Float32Array

Query embedding vector (must match store dimensions)
k number

Number of results to return (top-k nearest neighbors)
normalizeQuery boolean <optional>
 true

Whether to L2-normalize the query vector
Throws:

If store is not finalized or query dimensions don't match

Type
Error
Returns:

Array of search results sorted by similarity (highest first)

Type
Array.<SearchResult>
Examples
// Basic search
const queryEmbedding = new Float32Array(1536);
const results = store.search(queryEmbedding, 10);
// Search with pre-normalized query
const normalized = normalizeVector(queryEmbedding);
const results = store.search(normalized, 5, false);
// Filter results by score threshold
const results = store.search(queryEmbedding, 20)
  .filter(r => r.score > 0.7);

size() → {number}

Get the number of documents in the store.

Returns:

Number of documents loaded

Type
number
Example
console.log(`Loaded ${store.size()} documents`);