# How LightRAG Dual-Level Retrieval Works: Local vs Global Search Modes Explained

> Explore LightRAG's dual-level retrieval. Understand how local and global search modes process queries using distinct vector stores and graph traversal for precise or broad pattern matching.

- Repository: [✨Data Intelligence Lab@HKU✨/LightRAG](https://github.com/HKUDS/LightRAG)
- Tags: internals
- Published: 2026-03-23

---

**LightRAG's dual-level retrieval system routes queries through distinct vector stores and graph traversal strategies—entity-centric "local" mode for concrete facts and relationship-centric "global" mode for broad patterns—controlled by the `mode` parameter in [`lightrag/operate.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py).**

LightRAG, developed in the HKUDS/LightRAG repository, implements a sophisticated dual-level retrieval architecture that balances granular entity search with abstract relationship pattern matching. This design enables the system to handle specific factual questions through local navigation while answering analytical queries that require understanding global graph structures. Understanding these internal pathways is essential for optimizing query performance and context relevance.

## Local vs Global Retrieval Modes

LightRAG supports two primary retrieval strategies that operate on different levels of the knowledge graph abstraction:

| Mode | Search Target | Scoring Mechanism | Primary Use Case |
|------|-------------|-------------------|------------------|
| **Local** | **Entities** matching low-level (LL) keywords | Vector similarity in `entities_vdb` | Concrete facts about specific concepts (e.g., "What are the symptoms of COVID-19?") |
| **Global** | **Relationships** matching high-level (HL) keywords | Vector similarity in `relationships_vdb` | Patterns across the graph (e.g., "How are renewable energy policies evolving worldwide?") |

The **local** branch searches the entity vector store using low-level keywords extracted from the user query, retrieves the top-K entities, and then fetches neighboring edges from graph storage to provide immediate relationships. The **global** branch queries the relationship vector store using high-level keywords to identify matching edges first, then looks up the endpoint entities to establish context.

## The Four-Stage Query Pipeline

Both retrieval modes share a common pipeline implemented in `lightrag/operate.py::_build_query_context`:

1. **_perform_kg_search** – Obtains raw entities, relations, and optional vector chunks based on the selected mode.
2. **_apply_token_truncation** – Enforces `max_entity_tokens`, `max_relation_tokens`, and `max_total_tokens` limits.
3. **_merge_all_chunks** – De-duplicates and orders text chunks referenced by selected nodes or edges.
4. **_build_context_str** – Assembles the final LLM prompt or context string with citation metadata.

The `query_param.mode` flag determines which branches execute during the search stage. When set to `"local"`, only `_get_node_data` executes; when `"global"`, only `_get_edge_data` runs; hybrid configurations trigger both branches.

## Local Mode: Entity-Centric Retrieval

Local retrieval operates through the `_get_node_data` function in [`lightrag/operate.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py) (lines 4279–4354), which implements an entity-first traversal strategy.

The process begins with **embedding pre-computation**, where low-level keywords are embedded and used to query the `entities_vdb` vector store. The system then performs **batch graph retrieval** using `knowledge_graph_inst.get_nodes_batch` and `knowledge_graph_inst.node_degrees_batch` to fetch node properties and connectivity metrics.

After retrieving the seed entities, the system calls `_find_most_related_edges_from_entities` to walk the graph and collect neighboring edges. These edges are retrieved via `knowledge_graph_inst.get_edges_batch`. The function returns enriched entity dictionaries and attached relation dictionaries that populate the **local side** of the final context.

## Global Mode: Relationship-Centric Retrieval

Global retrieval uses the `_get_edge_data` function in [`lightrag/operate.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py) (lines 4554–4610) to implement a relationship-first approach suited for pattern discovery.

This mode queries the `relationships_vdb` using high-level keyword embeddings to identify relevant edges through vector similarity. The system fetches edge properties via `knowledge_graph_inst.get_edges_batch`, then resolves the endpoint entities through `_find_most_related_entities_from_relationships`, which gathers unique source and target IDs and pulls node data using `knowledge_graph_inst.get_nodes_batch`.

The results—edge dictionaries and their associated entity dictionaries—constitute the **global side** of the merged context, capturing broader structural patterns rather than isolated facts.

## Hybrid and Mix Configurations

When `query_param.mode` is set to `"hybrid"` or `"mix"`, the system executes both `_get_node_data` and `_get_edge_data` branches if the corresponding keyword sets are present. This enables comprehensive coverage that combines specific entity details with global relationship patterns.

In `"mix"` mode, the system additionally retrieves vector chunks for the original query from `chunks_vdb` and records them in `chunk_tracking` with source identifier `"C"`, blending knowledge graph results with raw text retrieval.

## Token-Aware Context Construction

After the pure search completes, `_apply_token_truncation` enforces budget constraints based on the retrieval mode. The system respects `max_source_ids_per_entity` and `max_source_ids_per_relation` limits during the `_merge_all_chunks` phase, which de-duplicates text chunks and respects the `related_chunk_number` parameter.

The final `_build_context_str` assembly includes entity descriptions, relationship descriptions, relevant text chunks (for mix mode), and citation metadata containing source IDs and file paths. This ensures the LLM receives optimized context regardless of whether the underlying retrieval was local, global, or hybrid.

## Practical Implementation Example

The following example demonstrates how to configure `QueryParam` for local and global retrieval modes:

```python
from lightrag.lightrag import LightRAG
from lightrag.types import QueryParam

# Initialize LightRAG instance

rag = LightRAG()

# Local retrieval: Entity-centric search

local_param = QueryParam(
    mode="local",
    top_k=5,
    chunk_top_k=0,
)
local_result = rag.query("What are the causes of climate change?", param=local_param)
print("Local entities:", [e["entity_name"] for e in local_result.entities])

# Global retrieval: Relationship-centric search

global_param = QueryParam(
    mode="global",
    top_k=5,
    chunk_top_k=0,
)
global_result = rag.query(
    "How have renewable-energy policies evolved globally?",
    param=global_param,
)
print("Global relations:", [
    (r["src_id"], r["tgt_id"]) for r in global_result.relationships
])

```

Key implementation details illustrated above include the `top_k` parameter limiting entity counts in local mode and relationship counts in global mode, and the `chunk_top_k` parameter controlling whether vector-search chunks are included.

## Summary

- **Local mode** searches the `entities_vdb` vector store using low-level keywords, retrieves matching nodes via `_get_node_data`, and gathers neighboring edges to answer specific factual queries.
- **Global mode** queries the `relationships_vdb` using high-level keywords, retrieves matching edges via `_get_edge_data`, and resolves endpoint entities to identify broad patterns across the knowledge graph.
- Both modes share downstream processing through `_apply_token_truncation`, `_merge_all_chunks`, and `_build_context_str` in [`lightrag/operate.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py), ensuring consistent context formatting regardless of retrieval strategy.
- The mode selection is controlled through `QueryParam.mode` in [`lightrag/base.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/base.py), supporting `"local"`, `"global"`, `"hybrid"`, and `"mix"` configurations.

## Frequently Asked Questions

### When should I use local mode versus global mode in LightRAG?

Use **local mode** when your query asks for concrete facts about specific entities, such as retrieving attributes or direct relationships of a named concept. Use **global mode** when investigating abstract patterns, trends, or connections that span multiple entities without requiring a specific starting node, as this searches relationship descriptions directly.

### How does LightRAG manage token limits during dual-level retrieval?

LightRAG enforces token budgets through `_apply_token_truncation` in [`lightrag/operate.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py), which respects `max_entity_tokens`, `max_relation_tokens`, and `max_total_tokens` parameters from `QueryParam`. The system truncates results before calling `_merge_all_chunks` to ensure the final context assembled by `_build_context_str` fits within the LLM's context window.

### What is the difference between hybrid and mix modes?

**Hybrid** mode executes both local and global retrieval branches when corresponding keywords are present, merging entity-centric and relationship-centric results. **Mix** mode extends this by additionally retrieving raw text chunks from `chunks_vdb` via vector search, blending knowledge graph context with non-structured text retrieval for comprehensive coverage.

### Which source files contain the core dual-level retrieval logic?

The primary implementation resides in [`lightrag/operate.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py), containing `_perform_kg_search`, `_get_node_data`, and `_get_edge_data`. Mode definitions exist in [`lightrag/base.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/base.py), while [`lightrag/api/routers/query_routes.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/routers/query_routes.py) documents the external API behaviors. Graph storage interactions use methods defined in `lightrag/kgs/*.py` such as [`networkx_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/networkx_impl.py).