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

> Explore LightRAG query modes: local, global, hybrid, mix, naive, and bypass. Understand how each mode optimizes entity-centric, relationship-focused, or vector-only retrieval for better search results.

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

---

**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`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/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

```python

# 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

```python

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

```python

# Bracket syntax allows custom user prompts while selecting a mode

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

```

### Bypass Mode for Pure Generation

```python

# 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`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py) with prefix parsing handled in [`lightrag/api/routers/ollama_api.py`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/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.