LightRAG Query Modes Explained: local, global, hybrid, mix, naive, and bypass

LightRAG provides six distinct query modes—local, global, hybrid, mix, naive, and bypass—that control whether the system performs entity-centric graph retrieval, relationship-focused searches, vector-only lookup, or skips retrieval entirely.

LightRAG, an open-source retrieval-augmented generation framework maintained by HKUDS, offers flexible query modes that determine how context is retrieved before LLM generation. These modes allow developers to fine-tune the balance between structured knowledge graph data and raw document chunks. Understanding LightRAG query modes is essential for optimizing retrieval performance and answer quality across different use cases.

Overview of the Six Query Modes

local Mode (Entity-Centric Retrieval)

The local mode focuses on entities and their related chunks using low-level keywords. It returns a rich graph of entities, relationships, and the most relevant document fragments. This mode is ideal when you need detailed, entity-centric answers such as definitions or explanations.

According to the source code in lightrag/lightrag.py, the local mode triggers the kg_query function with entity-focused parameters (lines 5252-5258).

global Mode (Relationship-Centric Retrieval)

The global mode prioritizes relationships and their connected entities using high-level keywords. Unlike local mode, it returns relationship-centric data with minimal chunk content, making it suitable for high-level overviews or discovering how concepts inter-relate.

The implementation shows that global mode also uses kg_query but with relationship-focused weighting.

hybrid Mode (Combined Entity and Relationship)

Hybrid mode combines the results of local and global retrieval in a round-robin fashion, merging both entity- and relationship-focused results. This provides a balanced view that includes both specific details and broader context.

The kg_query function handles hybrid requests by orchestrating multiple sub-queries and merging their outputs.

mix Mode (Graph plus Vector Search)

The mix mode returns knowledge graph data plus vector-retrieved document chunks, making it the most inclusive mode. It merges structured graph data and raw text results, ideal for comprehensive answers that benefit from both sources.

Like local and global, mix mode is processed through kg_query in lightrag/lightrag.py.

naive Mode (Vector-Only Retrieval)

Naive mode performs a pure vector search without any graph optimization. Only the chunks array is populated in the response, while entities and relationships remain empty. This provides fast, lightweight retrieval when the graph is not needed or unavailable.

The source code distinguishes this mode by calling naive_query instead of kg_query.

bypass Mode (No Retrieval)

The bypass mode skips all retrieval steps entirely. All data arrays are empty, and the LLM receives only the raw user prompt. This is useful for pure LLM generation tasks like creative writing where no context lookup is required.

Internally, this builds an empty result via convert_to_user_format.

How Query Modes Are Implemented

The query mode is encoded in the request payload under the metadata.query_mode field. In lightrag/lightrag.py, the aquery_data method (lines 2635-2639) determines which internal query function to invoke based on this mode value.

For Ollama compatibility, the system parses query prefixes to set the mode. The parse_query_mode helper in lightrag/api/routers/ollama_api.py (lines 1891-2009) builds a mapping from prefixes such as /local, /global, /naive, /hybrid, /mix, and /bypass to the corresponding SearchMode enum values.

The mode selection follows this dispatch logic:

• kg_query is called for local, global, hybrid, and mix modes
• naive_query is used for the naive mode
• bypass constructs an empty result via convert_to_user_format

Practical Usage Examples

You can specify query modes either through JSON metadata or Ollama-compatible prefix syntax.

Setting Mode via Metadata

# Explicit mode in the JSON payload (FastAPI request)

payload = {
    "model": "lightrag:latest",
    "messages": [{"role": "user", "content": "Explain attention mechanisms"}],
    "metadata": {"query_mode": "local"},   # choose local mode

}
response = client.post("/api/generate", json=payload).json()
print(response["metadata"]["query_mode"])   # → "local"

Using Prefix Syntax

# Mode prefix in the prompt (Ollama compatibility)

prompt = "/global What are the main challenges in reinforcement learning?"

# The Ollama API parses the prefix and sets SearchMode.global_

response = client.post("/api/generate", json={
    "model": "lightrag:latest",
    "messages": [{"role": "user", "content": prompt}]
})
print(response.json()["metadata"]["query_mode"])   # → "global"

Advanced prefix syntax supports custom prompts:

# Bracket syntax allows custom user prompts while selecting a mode

prompt = "/local[use mermaid] Explain transformer architecture"

Bypass Mode for Pure Generation

# Bypass mode for pure LLM generation without retrieval

payload = {
    "model": "lightrag:latest",
    "messages": [{"role": "user", "content": "Write a short poem about the sea"}],
    "metadata": {"query_mode": "bypass"},
}

# No retrieval performed; only the LLM processes the prompt

Summary

• LightRAG offers six query modes that range from full graph retrieval (local, global, hybrid, mix) to vector-only (naive) to no retrieval (bypass)
• The mode is specified via metadata.query_mode in API requests or through /mode prefixes in Ollama-compatible interfaces
• Local mode targets entities and chunks, while global mode focuses on relationships and high-level keywords
• Hybrid and mix modes combine multiple retrieval strategies for comprehensive context
• Naive mode performs vector search without graph optimization for faster, lightweight results
• Bypass mode skips retrieval entirely, sending only the user prompt to the LLM
• Implementation resides primarily in lightrag/lightrag.py with prefix parsing handled in lightrag/api/routers/ollama_api.py

Frequently Asked Questions

What is the difference between local and global query modes in LightRAG?

Local mode focuses on specific entities and their immediate relationships using low-level keywords, returning detailed entity-centric data and document chunks. Global mode prioritizes high-level relationships and connected entities, returning relationship-centric data with minimal chunk content for broader conceptual overviews.

When should I use hybrid mode versus mix mode?

Use hybrid mode when you want a balanced combination of entity-focused (local) and relationship-focused (global) results merged in round-robin fashion. Use mix mode when you need the most comprehensive results possible, as it combines full knowledge graph data with additional vector-retrieved document chunks beyond what the graph provides.

How do I switch query modes when using the Ollama-compatible API?

Prepend your prompt with a slash-mode prefix such as /local, /global, /hybrid, /mix, /naive, or /bypass. The parse_query_mode function in lightrag/api/routers/ollama_api.py automatically parses these prefixes and sets the corresponding SearchMode enum value before processing the query.

Does bypass mode still use the LightRAG knowledge graph?

No. Bypass mode skips all retrieval steps entirely, leaving the entities, relationships, and chunks arrays empty. The LLM receives only the raw user prompt without any context from the knowledge graph or vector store, making it suitable for pure generation tasks where retrieval is unnecessary.

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