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

# Vector Stores

> How RAGLight stores embeddings and performs retrieval.

# Vector Stores

## Overview

A **vector store** is the component responsible for storing embeddings and performing similarity search.

In RAGLight, vector stores are a **core abstraction** that sit between:

* the **ingestion pipeline** (documents → chunks → embeddings)
* and the **retrieval step** used by RAG / Agentic RAG pipelines

A vector store in RAGLight is not just a passive database. It actively:

* orchestrates document ingestion
* applies document processors and chunking
* stores embeddings and metadata
* exposes retrieval APIs used by higher-level pipelines

All vector store implementations inherit from a shared base class: `VectorStore`.

***

## How vector stores work in RAGLight

At a high level, the lifecycle looks like this:

1. **Documents are ingested** from folders or repositories
2. Files are processed using document processors (PDF, code, text, …)
3. Content is chunked and embedded
4. Embeddings are stored in one or more collections
5. At query time, the vector store retrieves the most relevant chunks

This logic is intentionally explicit and shared across implementations.

***

## Collections and data separation

RAGLight separates stored data into **two logical collections**:

* **Main collection**: regular document chunks (text, docs, code blocks)
* **Class collection**: extracted class or signature documents (for code)

For a given `collection_name`, this results in:

* `collection_name`
* `collection_name_classes`

This design enables different retrieval strategies depending on the use case.

***

## Available vector stores

RAGLight supports two vector store backends:

| Backend                 | Constant          | Extra              | Notes                              |
| ----------------------- | ----------------- | ------------------ | ---------------------------------- |
| **Chroma** (`ChromaVS`) | `Settings.CHROMA` | `raglight[chroma]` | Requires a C++ compiler on Windows |
| **Qdrant** (`QdrantVS`) | `Settings.QDRANT` | `raglight[qdrant]` | Pure Python — Windows-friendly     |

The API is designed so backends can be swapped without changing ingestion or RAG logic.

***

## Chroma Vector Store

### What is Chroma?

Chroma is a lightweight vector database that works well for:

* local-first experimentation
* persistent on-disk indexes
* client/server deployments

RAGLight integrates Chroma via the `ChromaVS` implementation.

***

## Local vs Remote usage

Chroma can be used in **two distinct ways** in RAGLight.

### Local mode (embedded)

In local mode, Chroma runs embedded in your application and persists data to disk.

This mode is selected when you provide a `persist_directory`.

```python theme={null}
vector_store_config = VectorStoreConfig(
    database=Settings.CHROMA,
    persist_directory="./defaultDb",
    collection_name="default",
)
```

Use this mode when:

* prototyping locally
* iterating quickly on embeddings or chunking
* working on a single machine

***

### Remote mode (client/server)

In remote mode, RAGLight connects to an **external Chroma server** over HTTP.

This mode is selected when you provide **both** `host` and `port`.

```python theme={null}
vector_store_config = VectorStoreConfig(
    database=Settings.CHROMA,
    host="localhost",
    port=8000,
    collection_name="default",
)
```

In this setup:

* Chroma runs as a standalone service
* RAGLight acts as a client
* Persistence is managed by the server

This is useful when:

* multiple services need to share the same index
* you deploy RAGLight in containers
* you want a long-lived vector database

RAGLight enforces this configuration strictly:

* **either** `persist_directory`
* **or** `host` + `port`

Mixing both is not allowed.

***

## Qdrant Vector Store

### What is Qdrant?

Qdrant is a pure-Python vector database that works well for:

* Windows environments (no C++ compiler required)
* containerised or cloud deployments
* client/server (remote) setups

RAGLight integrates Qdrant via the `QdrantVS` implementation.

```bash theme={null}
pip install "raglight[qdrant]"
```

### Local mode (on-disk)

```python theme={null}
vector_store_config = VectorStoreConfig(
    database=Settings.QDRANT,
    persist_directory="./defaultDb",
    collection_name="default",
)
```

### Remote mode (client/server)

```python theme={null}
vector_store_config = VectorStoreConfig(
    database=Settings.QDRANT,
    host="localhost",
    port=6333,
    collection_name="default",
)
```

Like Chroma, you can run Qdrant as a standalone service and connect RAGLight to it over the network.

***

## Ingestion pipeline (shared logic)

The ingestion pipeline is implemented in the abstract `VectorStore` base class and reused by all backends.

During ingestion:

* directories are walked recursively
* ignored folders are filtered out
* document processors are selected per file
* documents are chunked and embedded
* chunks are stored in the main collection
* class/signature documents are stored in the class collection

Ingestion is parallelized to speed up indexing.

***

## Retrieval APIs

Vector stores expose two main retrieval methods:

### Standard retrieval

```python theme={null}
docs = vector_store.similarity_search(question, k=5)
```

Used for most RAG queries.

### Class-based retrieval

```python theme={null}
docs = vector_store.similarity_search_class(question, k=5)
```

Used when working with codebases or structured symbols.

Both methods support filtering and dynamic collection selection when needed.

***

## How pipelines use vector stores

At the pipeline level, vector stores are treated as a black box with a simple contract:

* given a query → return relevant documents

For example, the RAG pipeline performs:

```python theme={null}
retrieved_docs = vector_store.similarity_search(question, k=self.k)
```

The retrieved documents are then injected into the prompt and passed to the LLM.

***

## Search modes

Both **Chroma** and **Qdrant** support three retrieval strategies, configured via `search_type` in `VectorStoreConfig`:

| Value        | Behavior                                           |
| ------------ | -------------------------------------------------- |
| `"semantic"` | Vector similarity search (default)                 |
| `"bm25"`     | Keyword-based BM25 search                          |
| `"hybrid"`   | BM25 + semantic, fused with Reciprocal Rank Fusion |

```python theme={null}
vector_store_config = VectorStoreConfig(
    database=Settings.CHROMA,
    persist_directory="./defaultDb",
    collection_name="default",
    search_type=Settings.SEARCH_HYBRID,  # or SEARCH_SEMANTIC, SEARCH_BM25
)
```

See the [Hybrid Search](/documentation/hybrid-search) page for a full explanation and examples.

***

## When to rebuild your index

You must rebuild the vector store if you change:

* the embedding model
* the embedding provider
* document processors or chunking logic
* the set of ingested documents

This ensures stored embeddings remain consistent with retrieval.

***

## Summary

* Vector stores handle ingestion, storage, and retrieval.
* RAGLight separates chunks and class documents into dedicated collections.
* **Chroma** and **Qdrant** are both supported — swap via `database=Settings.CHROMA` or `database=Settings.QDRANT`.
* Both backends work locally (on-disk) or remotely (client/server).
* Switching between backends does not affect pipeline or retrieval logic.
* All three search modes (semantic, BM25, hybrid) are available on both backends.