native-vector-store
Version:
High-performance local vector store with SIMD optimization for MCP servers
1,366 lines (398 loc) • 15.1 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: VectorStoreWrapper</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Class: VectorStoreWrapper</h1>
<section>
<header>
<h2><span class="attribs"><span class="type-signature"></span></span>VectorStoreWrapper<span class="signature">(dimensions)</span><span class="type-signature"></span></h2>
</header>
<article>
<div class="container-overview">
<h4 class="name" id="VectorStoreWrapper"><span class="type-signature"></span>new VectorStoreWrapper<span class="signature">(dimensions)</span><span class="type-signature"></span></h4>
<div class="description">
<p>Creates a new VectorStore instance</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>dimensions</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>The dimensionality of embedding vectors (e.g., 1536 for OpenAI embeddings)</p></td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Throws:</h5>
<dl>
<dt>
<div class="param-desc">
<p>If dimensions is not a positive integer</p>
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">TypeError</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
</div>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="addDocument"><span class="type-signature"></span>addDocument<span class="signature">(doc)</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
<p>Add a single document to the store. Only works before finalization.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>doc</code></td>
<td class="type">
<span class="param-type"><a href="global.html#Document">Document</a></span>
</td>
<td class="description last"><p>Document object with embedding in metadata</p></td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Throws:</h5>
<dl>
<dt>
<div class="param-desc">
<p>If called after finalization or document format is invalid</p>
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Error</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>store.addDocument({
id: 'doc-1',
text: 'Sample document',
metadata: {
embedding: new Array(1536).fill(0).map(() => Math.random())
}
});</code></pre>
<h4 class="name" id="finalize"><span class="type-signature"></span>finalize<span class="signature">()</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
<p>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().</p>
</div>
<dl class="details">
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>// Manual finalization after adding documents
store.addDocument(doc1);
store.addDocument(doc2);
store.finalize(); // Must call before searching</code></pre>
<h4 class="name" id="isFinalized"><span class="type-signature"></span>isFinalized<span class="signature">()</span><span class="type-signature"> → {boolean}</span></h4>
<div class="description">
<p>Check if the store has been finalized and is ready for searching.</p>
</div>
<dl class="details">
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>True if finalized, false otherwise</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">boolean</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>if (store.isFinalized()) {
const results = store.search(query, 10);
}</code></pre>
<h4 class="name" id="loadDir"><span class="type-signature"></span>loadDir<span class="signature">(path)</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
<p>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.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>path</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>Absolute or relative path to directory containing JSON files</p></td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Throws:</h5>
<dl>
<dt>
<div class="param-desc">
<p>If directory doesn't exist or contains invalid JSON</p>
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Error</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h5>Examples</h5>
<pre class="prettyprint"><code>// Load documents from a directory
store.loadDir('./knowledge-base');
// Store is automatically finalized and ready for searches</code></pre>
<pre class="prettyprint"><code>// 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
}
}</code></pre>
<pre class="prettyprint"><code>// 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"
}
}</code></pre>
<h4 class="name" id="normalize"><span class="type-signature"></span>normalize<span class="signature">()</span><span class="type-signature"> → {void}</span></h4>
<dl class="details">
<dt class="important tag-deprecated">Deprecated:</dt><dd><ul class="dummy"><li>Use finalize() instead</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h4 class="name" id="search"><span class="type-signature"></span>search<span class="signature">(query, k, normalizeQuery<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Array.<<a href="global.html#SearchResult">SearchResult</a>>}</span></h4>
<div class="description">
<p>Search for the k most similar documents to a query embedding.
Uses SIMD-optimized cosine similarity for fast performance.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>query</code></td>
<td class="type">
<span class="param-type">Float32Array</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last"><p>Query embedding vector (must match store dimensions)</p></td>
</tr>
<tr>
<td class="name"><code>k</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last"><p>Number of results to return (top-k nearest neighbors)</p></td>
</tr>
<tr>
<td class="name"><code>normalizeQuery</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
true
</td>
<td class="description last"><p>Whether to L2-normalize the query vector</p></td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Throws:</h5>
<dl>
<dt>
<div class="param-desc">
<p>If store is not finalized or query dimensions don't match</p>
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Error</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Array of search results sorted by similarity (highest first)</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Array.<<a href="global.html#SearchResult">SearchResult</a>></span>
</dd>
</dl>
<h5>Examples</h5>
<pre class="prettyprint"><code>// Basic search
const queryEmbedding = new Float32Array(1536);
const results = store.search(queryEmbedding, 10);</code></pre>
<pre class="prettyprint"><code>// Search with pre-normalized query
const normalized = normalizeVector(queryEmbedding);
const results = store.search(normalized, 5, false);</code></pre>
<pre class="prettyprint"><code>// Filter results by score threshold
const results = store.search(queryEmbedding, 20)
.filter(r => r.score > 0.7);</code></pre>
<h4 class="name" id="size"><span class="type-signature"></span>size<span class="signature">()</span><span class="type-signature"> → {number}</span></h4>
<div class="description">
<p>Get the number of documents in the store.</p>
</div>
<dl class="details">
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Number of documents loaded</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">number</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>console.log(`Loaded ${store.size()} documents`);</code></pre>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="VectorStore.html">VectorStore</a></li><li><a href="VectorStoreWrapper.html">VectorStoreWrapper</a></li></ul><h3><a href="global.html">Global</a></h3>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.4</a>
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>