> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions about VectoriaDB

Find answers to common questions about VectoriaDB.

## General

<AccordionGroup>
  <Accordion title="What is VectoriaDB?">
    VectoriaDB is a lightweight in-memory vector database for semantic search. It uses transformers.js to generate embeddings locally, so your data never leaves the server. It's designed for tool discovery, document search, and recommendation systems.
  </Accordion>

  <Accordion title="When should I use VectoriaDB?">
    Use VectoriaDB when you need:

    * **Semantic search** over tools, documents, or prompts
    * **Offline operation** without external API dependencies
    * **Privacy-first** applications where data can't leave the server
    * **Type-safe** metadata with TypeScript generics

    For simple keyword matching without semantic understanding, consider the [TF-IDF variant](/vectoriadb/guides/alternatives/tfidf) instead.
  </Accordion>

  <Accordion title="What's the difference between VectoriaDB and TFIDFVectoria?">
    | Feature          | VectoriaDB                     | TFIDFVectoria                 |
    | ---------------- | ------------------------------ | ----------------------------- |
    | Understanding    | Semantic (understands meaning) | Keyword-based (exact matches) |
    | Dependencies     | transformers.js (\~22MB model) | Zero dependencies             |
    | Initialization   | Async (model download)         | Synchronous                   |
    | Reindex required | No                             | Yes, after changes            |

    Use VectoriaDB for semantic understanding, TFIDFVectoria for simple keyword matching.
  </Accordion>

  <Accordion title="Is VectoriaDB production-ready?">
    Yes. VectoriaDB includes production-ready features:

    * **Operational guardrails**: Rate limits, batch validation, document size limits
    * **Persistence**: File and Redis storage adapters
    * **Error handling**: Typed error classes with machine-readable codes
    * **HNSW indexing**: Sub-millisecond queries at scale
  </Accordion>
</AccordionGroup>

## Performance

<AccordionGroup>
  <Accordion title="How many documents can VectoriaDB handle?">
    VectoriaDB can handle 100,000+ documents efficiently:

    * **Brute-force search**: Good for \< 10,000 documents
    * **HNSW indexing**: Required for > 10,000 documents, supports 100,000+

    Memory usage is approximately 1.5KB per document (384-dimensional embeddings + metadata).
  </Accordion>

  <Accordion title="How fast is search?">
    Search performance depends on your configuration:

    | Documents | Brute-force | HNSW (ef=50) |
    | --------- | ----------- | ------------ |
    | 10,000    | \~50ms      | \~1ms        |
    | 50,000    | \~250ms     | \~1ms        |
    | 100,000   | \~500ms     | \~2ms        |

    Enable HNSW for sub-millisecond queries on large datasets.
  </Accordion>

  <Accordion title="Why is the first query slow?">
    The first query after initialization may be slower because:

    1. **Model warmup**: The first embedding generation warms up the model
    2. **JIT compilation**: JavaScript engines optimize hot code paths

    Subsequent queries are significantly faster. Consider running a warmup query during startup.
  </Accordion>

  <Accordion title="How much memory does VectoriaDB use?">
    Memory usage depends on:

    * **Embeddings**: \~1.5KB per document (384 dimensions x 4 bytes)
    * **Metadata**: Variable based on your metadata size
    * **HNSW index**: \~50-100 bytes per document for graph connections

    For 100,000 documents, expect \~150-200MB memory usage.
  </Accordion>
</AccordionGroup>

## Configuration

<AccordionGroup>
  <Accordion title="Can I use a different embedding model?">
    Yes. VectoriaDB supports any transformers.js-compatible model:

    ```ts title="src/custom-model.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    const db = new VectoriaDB({
      modelName: 'Xenova/paraphrase-MiniLM-L6-v2',
      dimensions: 384, // Match model dimensions
    });
    ```

    The default `Xenova/all-MiniLM-L6-v2` provides good quality with fast inference.
  </Accordion>

  <Accordion title="How do I enable HNSW?">
    Enable HNSW for datasets > 10,000 documents:

    ```ts title="src/enable-hnsw.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    const db = new VectoriaDB({
      useHNSW: true,
      hnsw: {
        M: 16,           // Connections per node
        efConstruction: 200, // Build quality
        efSearch: 50,    // Search quality
      },
    });
    ```

    See [HNSW guide](/vectoriadb/guides/scaling/hnsw-overview) for tuning details.
  </Accordion>

  <Accordion title="How do I persist embeddings?">
    Use a storage adapter to persist embeddings between restarts:

    ```ts title="src/persistence.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    const db = new VectoriaDB({
      storageAdapter: new FileStorageAdapter({
        cacheDir: './.cache/vectoriadb',
        namespace: 'my-index',
      }),
    });

    await db.initialize();
    await db.addMany(documents);
    await db.saveToStorage();
    ```

    See [Storage guide](/vectoriadb/guides/storage/overview) for details.
  </Accordion>

  <Accordion title="What's the default similarity threshold?">
    The default threshold is `0.3`. Adjust based on your use case:

    * **0.3-0.4**: Loose matching, more results
    * **0.5-0.6**: Moderate matching, balanced
    * **0.7+**: Strict matching, high precision

    Start low and increase if you're getting too many irrelevant results.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Why am I getting VectoriaNotInitializedError?">
    You must call `initialize()` before any operation:

    ```ts title="src/fix-not-initialized.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    const db = new VectoriaDB();
    await db.initialize(); // Required!

    await db.add('id', 'text', metadata);
    ```

    `initialize()` is idempotent - calling it multiple times is safe.
  </Accordion>

  <Accordion title="Why are my search results empty?">
    Common causes:

    1. **Threshold too high**: Lower the `threshold` option
    2. **No matching documents**: Check that documents are indexed
    3. **Filter too restrictive**: Review your `filter` function

    ```ts title="src/debug-search.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    // Debug: search without filters
    const results = await db.search(query, {
      threshold: 0.1, // Low threshold
      topK: 20,       // More results
      // No filter
    });
    console.log('Found:', results.length);
    ```
  </Accordion>

  <Accordion title="Model download fails - what should I do?">
    If model download fails:

    1. **Check network**: Ensure internet access to Hugging Face
    2. **Check permissions**: Ensure write access to `cacheDir`
    3. **Use a proxy**: Set `HTTPS_PROXY` environment variable
    4. **Pre-download**: Download the model manually

    The model is cached after first download.
  </Accordion>

  <Accordion title="How do I debug poor search quality?">
    To improve search quality:

    1. **Check document text**: Ensure text is descriptive
    2. **Adjust threshold**: Try different values
    3. **Inspect scores**: Look at `result.score` values
    4. **Review embeddings**: Use `includeVector: true` to inspect

    ```ts title="src/debug-quality.ts" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
    const results = await db.search(query, {
      topK: 10,
      threshold: 0.0, // Show all
      includeVector: true,
    });

    for (const r of results) {
      console.log(`${r.id}: ${r.score.toFixed(3)}`);
    }
    ```
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Common Errors" icon="triangle-exclamation" href="/vectoriadb/troubleshooting/common-errors">
    Error reference and solutions
  </Card>

  <Card title="Error Handling" icon="code" href="/vectoriadb/reference/errors">
    Programmatic error handling
  </Card>
</CardGroup>