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

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.

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 (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 (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:

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, ensuring consistent context formatting regardless of retrieval strategy.
• The mode selection is controlled through QueryParam.mode in 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, 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, containing _perform_kg_search, _get_node_data, and _get_edge_data. Mode definitions exist in lightrag/base.py, while 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}