# How to Enable Semantic Search in Code-Graph-RAG: A Complete Setup Guide

> Learn to enable semantic search in Code-Graph-RAG with this complete setup guide. Install the semantic extra, start Qdrant, and run the indexer to embed functions for powerful code querying.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-08-11

---

**Enable semantic search in Code-Graph-RAG by installing the `semantic` extra (`pip install "code-graph-rag[semantic]"`), starting a Qdrant vector store, and running the indexer to embed functions into a dense vector space.**

Code-Graph-RAG (cgr) provides dense vector search capabilities that allow you to retrieve functions using natural language queries rather than exact string matching. According to the vitali87/code-graph-rag source code, this feature embeds source code fragments into a high-dimensional space and performs approximate nearest-neighbor (ANN) searches against a Qdrant vector store.

## Understanding the Semantic Search Architecture

### Embedding Layer

The embedding layer converts function source text into dense vectors using transformer models. In [`codebase_rag/embedder.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py), the functions `embed_code` and `embed_code_batch` handle the vectorization, utilizing models from the **semantic extra** (specifically `torch`, `transformers`, and `sentence-transformers`).

### Vector Store

Vectors are persisted in Qdrant via the thin wrapper implemented in [`codebase_rag/vector_store.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/vector_store.py). This module provides `search_embeddings` for querying and `upsert_embeddings` for storing vectors.

### Search Tool Interface

The LangChain-compatible tool is exposed through [`codebase_rag/tools/semantic_search.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tools/semantic_search.py). The `semantic_code_search` function (lines 44-46) embeds queries, while lines 46-48 handle the ANN search against Qdrant.

## Step-by-Step: Enable Semantic Search in Code-Graph-RAG

### 1. Install the Semantic Extra

The heavy ML dependencies are optional. Install them using pip:

```bash
pip install "code-graph-rag[semantic]"

```

The [`pyproject.toml`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml) defines this extra under `[project.optional-dependencies]`, pulling in `torch`, `transformers`, and `sentence-transformers`.

### 2. Configure the Vector Store

Start a Qdrant instance or point to an existing deployment using the `VECTOR_STORE_URL` environment variable. The default Docker Compose configuration includes a Qdrant service, but you can customize endpoints via [`cgr.yaml`](https://github.com/vitali87/code-graph-rag/blob/main/cgr.yaml) or environment variables.

### 3. Index Your Codebase

Run the graph updater to create embeddings for every function and method:

```bash
python -m codebase_rag.graph_updater --project my_project

```

This process calls `embed_code_batch` from [`embedder.py`](https://github.com/vitali87/code-graph-rag/blob/main/embedder.py) and stores results via `vector_store.upsert_embeddings`.

### 4. Verify Dependencies

The runtime guard in [`codebase_rag/utils/dependencies.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/utils/dependencies.py) checks for the presence of ML libraries. If the check passes, the search tool activates automatically; otherwise, it degrades gracefully with a warning logged via `ex.SEMANTIC_EXTRA` (see lines 36-38 in [`semantic_search.py`](https://github.com/vitali87/code-graph-rag/blob/main/semantic_search.py)).

## Querying Code with Natural Language

### Programmatic Usage

Use the factory function `create_semantic_search_tool` to instantiate the search capability:

```python
from codebase_rag.tools.semantic_search import create_semantic_search_tool

# ingestor implements QueryProtocol (e.g., Neo4j driver wrapper)

semantic_tool = create_semantic_search_tool(ingestor)

# Search for relevant functions

result = await semantic_tool.run(
    query="find the function that parses JSON", 
    top_k=5
)
print(result)  # Returns qualified names and similarity scores

```

Behind the scenes, the tool embeds your query using `embed_code`, searches Qdrant via `search_embeddings`, and resolves node IDs to metadata using Cypher queries (`build_nodes_by_ids_query`).

### Retrieving Source Code

To fetch the actual source lines for a returned node ID, use the companion tool:

```python
from codebase_rag.tools.semantic_search import create_get_function_source_tool

source_tool = create_get_function_source_tool(ingestor)
source_code = await source_tool.run(node_id="function_123")

```

The underlying `get_function_source_code` function (lines 11-51 in [`semantic_search.py`](https://github.com/vitali87/code-graph-rag/blob/main/semantic_search.py)) handles path validation and project-root security checks.

## Summary

- **Install the semantic extra**: Run `pip install "code-graph-rag[semantic]"` to get PyTorch and transformer dependencies.
- **Start Qdrant**: Configure via [`cgr.yaml`](https://github.com/vitali87/code-graph-rag/blob/main/cgr.yaml) or `VECTOR_STORE_URL` environment variable.
- **Index with graph_updater**: Execute `python -m codebase_rag.graph_updater --project my_project` to vectorize functions.
- **Use semantic tools**: Import `create_semantic_search_tool` and `create_get_function_source_tool` from [`codebase_rag/tools/semantic_search.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tools/semantic_search.py).
- **Graceful degradation**: The dependency guard in [`utils/dependencies.py`](https://github.com/vitali87/code-graph-rag/blob/main/utils/dependencies.py) ensures the system warns rather than crashes if ML libraries are missing.

## Frequently Asked Questions

### What happens if I don't install the semantic extra?

If the ML stack is absent, the dependency guard in [`codebase_rag/utils/dependencies.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/utils/dependencies.py) detects the missing imports. The `semantic_code_search` tool short-circuits early (lines 36-38) and logs a warning via `ex.SEMANTIC_EXTRA`, allowing the rest of Code-Graph-RAG to function without semantic capabilities.

### Which embedding model does Code-Graph-RAG use?

The specific transformer model is configurable via [`cgr.yaml`](https://github.com/vitali87/code-graph-rag/blob/main/cgr.yaml) or environment variables. The [`embedder.py`](https://github.com/vitali87/code-graph-rag/blob/main/embedder.py) module uses `sentence-transformers` by default to encode both source code and natural language queries into the same dense vector space.

### Can I use a different vector store instead of Qdrant?

While Qdrant is the default and ships with the Docker Compose configuration, the [`vector_store.py`](https://github.com/vitali87/code-graph-rag/blob/main/vector_store.py) wrapper abstracts the client interface. You could extend it to support other ANN-compatible stores, though you would need to implement `search_embeddings` and `upsert_embeddings` methods for your chosen backend.

### How do I verify that semantic search is active?

Check the runtime dependency guard by importing from `codebase_rag.utils.dependencies`. If it returns `True` for the semantic extra check, the search tool will be active. Additionally, successful execution of `create_semantic_search_tool` without ImportError exceptions confirms the embedding layer is functional.