RAG-Anything Query Modes: How to Use Local, Global, Hybrid, and Naive Retrieval

RAG-Anything provides six distinct query modes—local, global, hybrid, naive, mix, and bypass—that determine whether retrieval runs against the current document only, the entire knowledge base, both combined, via keyword matching, automatically, or not at all, each optimized for different latency and accuracy requirements.

The HKUDS/RAG-Anything repository abstracts complex retrieval-augmented generation workflows behind a unified aquery API where the mode parameter controls the retrieval strategy. Understanding these query modes is essential for balancing search precision, computational cost, and answer completeness when querying indexed documents. All modes are implemented in the QueryMixin class and passed to the underlying LightRAG engine via QueryParam objects defined in raganything/query.py.

Available Query Modes in RAG-Anything

The six supported values are documented in the docstring of QueryMixin.aquery at line 109 of raganything/query.py. Each mode instructs LightRAG exactly where and how to search for relevant context before the LLM generates an answer.

Local Mode

Local mode searches only within the document that triggered the query, limiting the vector-store lookup to a small subset of chunks. This is the fastest path available because it avoids scanning the entire knowledge base. Use local mode when you are confident the answer is contained in the current file, such as when asking questions about a specific PDF chapter or markdown section.

Global Mode

Global mode searches the entire knowledge base by running an embedding-based similarity search across the full index. This mode maximizes recall by checking all processed documents for relevant context. Use global mode for broad-scope questions that may need information from any document, such as asking about overall system architecture across multiple files.

Hybrid Mode

Hybrid mode combines local and global results by first gathering top-k local chunks, then expanding with top-k global chunks, and finally merging and re-ranking them. This approach delivers the precision of local context while maintaining the ability to pull missing information from elsewhere in the corpus. Hybrid mode is ideal for most real-world queries where you need both focused and comprehensive evidence.

Naive Mode

Naive mode performs a simple lexical match using keyword-based search instead of embedding similarity, executing no vector search at all. This provides deterministic, exact-string matching useful for debugging or when embedding services are unavailable. Use naive mode when searching for specific configuration keys, exact identifiers, or in low-latency scenarios where approximate semantic search is unnecessary.

Mix Mode (Default)

Mix mode automatically chooses the best strategy based on current configuration: if a global index exists it behaves like hybrid, otherwise it falls back to local. This adaptive behavior makes it the recommended starting point when you are unsure which scope is needed. Mix mode is the default in all RAG-Anything examples and provides optimal performance without manual tuning.

Bypass Mode

Bypass mode skips retrieval entirely and sends the raw user prompt directly to the LLM with only the system prompt attached. This mode incurs no retrieval latency or cost because no document lookup occurs. Use bypass mode for purely generative tasks where grounding is not required, such as creative writing or when the knowledge base is incomplete or irrelevant.

Technical Implementation in the Source Code

The query mode selection logic resides in raganything/query.py, specifically within the QueryMixin class, while the high-level RAGAnything class in raganything/raganything.py wires the configuration. According to the docstring at line 109, the mode argument tells LightRAG where and how to look for relevant context before generation. At line 161, the selected mode is packaged into a QueryParam object:

QueryParam(mode=mode, …)

LightRAG interprets this parameter and builds the appropriate retrieval pipeline, whether that involves querying the local vector store, global vector store, executing a lexical grep, or skipping retrieval entirely. Default configuration values influencing this behavior are typically defined in raganything/config.py.

Performance Trade-offs and Selection Strategy

Understanding the computational characteristics of each mode helps optimize your RAG-Anything implementation. Local and naive modes touch far fewer vectors, delivering lower latency suitable for interactive applications. Global and hybrid modes maximize the chance of finding needed evidence but consume more compute and increase response times. Bypass mode eliminates retrieval costs entirely but provides no document grounding.

When combined with vision-language model enhancements using vlm_enhanced=True, the selected mode still controls text retrieval while the VLM step adds image understanding on top of the fetched context.

Code Examples for Each Query Mode

The following examples come directly from the RAG-Anything README (lines 606–614) and demonstrate practical usage of each mode:

# 1️⃣ Default – let RAG-Anything decide (mix)

await rag.aquery("What is the main contribution of this paper?", mode="mix")

# 2️⃣ Local only – fast, document-scoped

await rag.aquery("Explain the algorithm in Section 3", mode="local")

# 3️⃣ Global only – search the whole corpus

await rag.aquery("Which datasets were used across all experiments?", mode="global")

# 4️⃣ Hybrid – combine local + global (most common)

await rag.aquery(
    "How does the proposed method compare to the baseline in Table 2?",
    mode="hybrid",
    top_k=10   # optional: ask for more candidates before re-ranking

)

# 5️⃣ Naive keyword match – no embeddings

await rag.aquery(
    "Find every occurrence of the string 'learning_rate' in the docs",
    mode="naive"
)

# 6️⃣ Bypass – ask the LLM directly

await rag.aquery(
    "Write a short abstract summarising the whole project",
    mode="bypass"
)

# 7️⃣ VLM-enhanced query (automatic when vision_model_func is provided)

await rag.aquery(
    "Describe the figure that shows the performance curves",
    mode="hybrid",          # retrieval mode

    vlm_enhanced=True      # force VLM image analysis

)

Summary

• RAG-Anything supports six query modes implemented in raganything/query.py: local, global, hybrid, naive, mix, and bypass.
• Local mode provides the fastest retrieval by searching only the current document, while global mode scans the entire knowledge base for maximum recall.
• Hybrid mode merges local and global results for balanced precision and coverage, making it ideal for most production use cases.
• Naive mode uses lexical matching instead of embeddings for deterministic keyword searches.
• Mix mode automatically selects between hybrid and local based on index availability and serves as the recommended default.
• Bypass mode skips retrieval entirely for pure LLM generation when document grounding is unnecessary.

Frequently Asked Questions

What is the default query mode in RAG-Anything?

Mix mode is the default query mode in RAG-Anything. When using mode="mix", the system automatically behaves like hybrid if a global index exists, otherwise it falls back to local. This adaptive strategy eliminates the need to manually select between retrieval scopes for most workloads.

When should I use hybrid mode instead of global mode?

Use hybrid mode when you need both the precision of document-specific context and the comprehensiveness of cross-document search. While global mode searches the entire knowledge base uniformly, hybrid mode first retrieves relevant chunks from the current document then supplements with global results, making it more efficient for queries that primarily concern the active document but might reference external information.

How does the naive mode differ from the other retrieval options?

Naive mode operates entirely through lexical matching rather than vector similarity, performing keyword-based greps instead of embedding searches. Unlike local, global, or hybrid modes which rely on vector stores and approximate nearest neighbor search, naive mode returns exact string matches, making it suitable for finding specific configuration parameters, function names, or when embedding services are unavailable.

Does bypass mode still use the system prompt when skipping retrieval?

Yes, bypass mode skips the retrieval pipeline entirely but still attaches any configured system prompt to the request. Only the document context is omitted; the raw user prompt is sent to the LLM along with system instructions, making it suitable for pure generative tasks while maintaining conversation formatting and instruction following.

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