graphrag query

Query a knowledge graph index using various search methods

The query command searches your knowledge graph index to answer questions using different retrieval strategies.

Usage

graphrag query "<your question>" [OPTIONS]

Arguments

query · string · required

The question or query to execute against the knowledge graph.

Options

--root · string · default: "current directory"

The project root directory containing the configuration and index.

Aliases: -r

--method · string · default: "global"

The query algorithm to use.

Aliases: -m

Available methods:

• global - Best for questions about the entire dataset or high-level themes
• local - Best for specific entity-focused questions
• drift - Advanced multi-hop reasoning across communities
• basic - Simple similarity-based search over text chunks

--data · string

Index output directory containing the parquet files. If not specified, uses the output_storage.base_dir from configuration.

Aliases: -d

--community-level · integer · default: "2"

Leiden hierarchy level from which to load community reports. Higher values represent smaller, more granular communities.

Used by: global, local, and drift methods.

--dynamic-community-selection · boolean · default: "false"

Use global search with dynamic community selection. This allows the search to adaptively select relevant communities.

Use --dynamic-community-selection to enable.

Only used by: global method.

--response-type · string · default: "Multiple Paragraphs"

Free-form description of the desired response format.

Examples:

• "Single Sentence"
• "Multiple Paragraphs"
• "List of 3-7 Points"
• "Detailed Report"
• "Executive Summary"

--streaming · boolean · default: "false"

Print the response in a streaming manner as it’s generated, rather than waiting for the complete response.

Use --streaming to enable, --no-streaming to disable.

--verbose · boolean · default: "false"

Run the query with verbose logging to see detailed processing information.

Aliases: -v

Search methods

Global search

Best for questions about overall themes, trends, or dataset-wide patterns.

graphrag query "What are the main themes in the dataset?" --method global

Global search:

• Uses community reports at specified hierarchy level
• Employs map-reduce approach to aggregate insights
• Best for broad, thematic questions

Local search

Best for questions about specific entities, events, or detailed information.

graphrag query "What is the role of John Smith?" --method local

Local search:

• Focuses on specific entities and their neighborhoods
• Uses entity embeddings to find relevant context
• Best for targeted, specific questions

DRIFT search

Advanced search using multi-hop reasoning across communities.

graphrag query "How do these technologies impact healthcare?" --method drift

DRIFT search:

• Performs multi-hop reasoning across the graph
• Explores multiple community levels
• Best for complex analytical questions requiring deep reasoning

Basic search

Simple similarity-based search over text chunks.

graphrag query "machine learning applications" --method basic

Basic search:

• Uses text embeddings for similarity matching
• Searches over raw text units
• Best for simple retrieval or when you want direct text excerpts

Examples

Global search with custom response format

graphrag query "Summarize the key findings" \
  --method global \
  --response-type "List of 5-7 Points"

Local search with streaming

graphrag query "Tell me about the Paris Agreement" \
  --method local \
  --streaming

Query specific community level

graphrag query "What are the main topics?" \
  --method global \
  --community-level 1

Lower community levels (0, 1) contain broader, higher-level communities. Higher levels (2, 3+) contain more granular, specific communities.

Dynamic community selection

graphrag query "Explain the relationship between climate and economy" \
  --method global \
  --dynamic-community-selection

Query with custom data directory

graphrag query "What patterns emerge?" \
  --data ./custom_output \
  --method global

Verbose output for debugging

graphrag query "Tell me about innovation" \
  --method local \
  --verbose

Response types

The --response-type parameter is a free-form instruction that guides the LLM’s response format:

• “Single Sentence” - Concise one-sentence answer
• “Multiple Paragraphs” - Detailed multi-paragraph response (default)
• “List of 3-7 Points” - Bullet-point summary
• “Single Paragraph” - Brief paragraph
• “Detailed Report” - Comprehensive analysis
• “Executive Summary” - High-level overview
• “Comparison Table” - Structured comparison

Performance considerations

• Global search: Processes community reports, faster than local for broad questions
• Local search: Retrieves entity neighborhoods, can be slower for large graphs
• DRIFT search: Most computationally intensive due to multi-hop reasoning
• Basic search: Fastest method, simple vector similarity
• Streaming: Recommended for long responses to see results incrementally

Output format

By default, the query response is printed to stdout. When using --verbose, you’ll also see:

• Retrieved context information
• Token usage statistics
• Processing time
• Search parameters used

Next steps

• Understand search methods
• Configure query settings
• Optimize query performance