Quickstart

GraphRAG can consume significant LLM resources. Start with the tutorial dataset until you understand the system, and experiment with fast/inexpensive models before committing to large indexing jobs.

Get GraphRAG running in 5 steps: install, initialize, configure, index, and query.

Prerequisites

Python 3.11-3.13
OpenAI API key or Azure OpenAI credentials

Step 1: Install GraphRAG

Create a project directory

mkdir graphrag_quickstart
cd graphrag_quickstart
python -m venv .venv

Activate your virtual environment

source .venv/bin/activate

Install the package

pip install graphrag

Step 2: Initialize your workspace

Initialize GraphRAG to create the necessary configuration files:

graphrag init

When prompted, specify your preferred models:

Chat model: gpt-4.1 (default) or gpt-4-turbo
Embedding model: text-embedding-3-large (default)

This creates:

settings.yaml - Main configuration file
.env - Environment variables (API keys)
input/ - Directory for source documents
prompts/ - Customizable extraction prompts

Step 3: Configure your API key

OpenAI
Azure OpenAI

Edit .env and add your OpenAI API key:

GRAPHRAG_API_KEY=sk-...

Edit .env and add your Azure OpenAI API key:

GRAPHRAG_API_KEY=your-azure-api-key

Then update settings.yaml with your Azure configuration:

models:
  completions:
    type: chat
    model_provider: azure
    model: gpt-4.1
    deployment_name: your-deployment-name
    api_base: https://your-instance.openai.azure.com
    api_version: 2024-02-15-preview
    
  embeddings:
    type: embedding
    model_provider: azure
    model: text-embedding-3-large
    deployment_name: your-embedding-deployment
    api_base: https://your-instance.openai.azure.com
    api_version: 2024-02-15-preview

Step 4: Add your data

Download the sample dataset (A Christmas Carol):

curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt

Or add your own documents to the input/ directory. Supported formats:

.txt files
.csv files (with text column)
.json files (with text field)

Step 5: Run the indexing pipeline

Build your knowledge graph index:

graphrag index

This process:

Chunks your documents into text units
Extracts entities, relationships, and claims
Builds a knowledge graph
Detects hierarchical communities
Generates community summaries
Creates vector embeddings

Indexing typically takes 5-15 minutes for the sample dataset with GPT-4. Cost: approximately

0.50-

2.00 depending on the model and dataset size.

The output is saved to output/ as parquet files.

Step 6: Query your knowledge graph

Now you can ask questions about your data using different search methods:

Global search
Local search
DRIFT search

Best for questions about the entire dataset:

graphrag query "What are the main themes in this story?"

Best for specific entity-focused questions:

graphrag query "Who is Scrooge and what are his main relationships?" --method local

Best for questions needing both entity details and community context:

graphrag query "How does Scrooge's character develop throughout the story?" --method drift

Understanding the search methods

Global search

Best for: Holistic dataset understandingUses all community summaries in a map-reduce process. Ideal for “what are the main themes” type questions.

Local search

Best for: Entity-specific questionsRetrieves entities and their neighbors. Ideal for “who is X” or “what does Y do” questions.

DRIFT search

Best for: Multi-level reasoningCombines local entity retrieval with community context. Ideal for complex questions requiring both depth and breadth.

Next steps

Configuration

Customize indexing, chunking, and model settings

Prompt tuning

Generate domain-specific prompts for better extraction

Query engine

Learn about all four search methods in depth

Python API

Use GraphRAG programmatically in your applications

Troubleshooting

Rate limit errors

If you hit rate limits:

Reduce parallelization in settings.yaml:

parallelization:
  concurrent_requests: 5  # Reduce from default 25

Add delays between requests:

concurrent_requests: 5
rate_limit_per_minute: 300

High costs

To reduce indexing costs:

Use gpt-3.5-turbo for initial testing
Enable caching to avoid re-processing:
```
cache:
  type: file
```
Use the “fast” indexing method:
```
graphrag index --method fast
```

Out of memory errors

For large datasets:

Increase chunk overlap to reduce total chunks
Reduce max_cluster_size in settings
Process documents in batches

Poor extraction quality

Improve extraction with prompt tuning:

graphrag prompt-tune

This auto-generates prompts optimized for your domain and data.

Get Started

Core Concepts

Indexing

Query Engine

Prompt Tuning

Configuration

Guides

Prerequisites

Step 1: Install GraphRAG

Step 2: Initialize your workspace

Step 3: Configure your API key

Step 4: Add your data

Step 5: Run the indexing pipeline

Step 6: Query your knowledge graph

Understanding the search methods

Global search

Local search

DRIFT search

Next steps

Configuration

Prompt tuning

Query engine

Python API

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Indexing

Query Engine

Prompt Tuning

Configuration

Guides

​Prerequisites

​Step 1: Install GraphRAG

​Step 2: Initialize your workspace

​Step 3: Configure your API key

​Step 4: Add your data

​Step 5: Run the indexing pipeline

​Step 6: Query your knowledge graph

​Understanding the search methods

Global search

Local search

DRIFT search

​Next steps

Configuration

Prompt tuning

Query engine

Python API

​Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Step 1: Install GraphRAG

Step 2: Initialize your workspace

Step 3: Configure your API key

Step 4: Add your data

Step 5: Run the indexing pipeline

Step 6: Query your knowledge graph

Understanding the search methods

Next steps

Troubleshooting