Settings reference

Complete reference for GraphRAG settings.yaml configuration

GraphRAG can be configured using a settings.yaml or settings.json file in your project root. This page documents all available configuration options.

Environment variable substitution

Configuration values can reference environment variables using ${VAR_NAME} syntax:

completion_models:
  default_completion_model:
    api_key: ${GRAPHRAG_API_KEY}

.env

GRAPHRAG_API_KEY=your-api-key-here

If a .env file is present in your project root, environment variables will be automatically loaded.

Language model configuration

Completion models

Define completion models for text generation tasks:

completion_models:
  default_completion_model:
    model_provider: openai
    model: gpt-4.1
    auth_method: api_key
    api_key: ${GRAPHRAG_API_KEY}
    retry:
      type: exponential_backoff
      max_retries: 7
      base_delay: 2.0
    rate_limit:
      type: sliding_window
      period_in_seconds: 60
      requests_per_period: 100

You can define multiple models and reference them by key in workflow configurations. See LLM Models for detailed examples.

Embedding models

Define embedding models for vector generation:

embedding_models:
  default_embedding_model:
    model_provider: openai
    model: text-embedding-3-large
    auth_method: api_key
    api_key: ${GRAPHRAG_API_KEY}

Input configuration

Input settings

Configure document input format and location:

input:
  type: text  # text, csv, json, jsonl
  encoding: utf-8
  file_pattern: ".*\\.txt$"  # regex pattern for files
  id_column: id  # for CSV/JSON
  title_column: title  # for CSV/JSON
  text_column: text  # for CSV/JSON

type · string · default: "text"

Input data format: text, csv, json, or jsonl

encoding · string · default: "utf-8"

Character encoding for input files

file_pattern · string

Regex pattern to match input files (defaults based on type)

id_column · string

Column name for document IDs (CSV/JSON only)

title_column · string

Column name for document titles (CSV/JSON only)

text_column · string

Column name for document text content (CSV/JSON only)

Chunking configuration

Configure how documents are split into chunks:

chunking:
  type: tokens  # tokens or sentence
  size: 1200
  overlap: 100
  encoding_model: o200k_base
  prepend_metadata:
    - title
    - source

type · string · default: "tokens"

Chunking strategy: tokens or sentence

size · integer · default: "1200"

Maximum chunk size in tokens

overlap · integer · default: "100"

Number of overlapping tokens between chunks

encoding_model · string · default: "o200k_base"

Tokenizer model for splitting text

prepend_metadata · array

Document metadata fields to prepend to each chunk

Storage configuration

See the Storage page for detailed storage configuration.

Workflow configurations

Text embedding

Configure text embedding generation:

embed_text:
  embedding_model_id: default_embedding_model
  model_instance_name: text_embedding
  batch_size: 16
  batch_max_tokens: 8191
  names:
    - text_unit_text
    - entity_description
    - community_full_content

embedding_model_id · string · required

Reference to embedding model configuration

batch_size · integer · default: "16"

Maximum number of texts to embed in one batch

batch_max_tokens · integer · default: "8191"

Maximum total tokens per batch

names · array

Which embeddings to generate: text_unit_text, entity_description, community_full_content

Graph extraction

Configure LLM-based entity and relationship extraction:

extract_graph:
  completion_model_id: default_completion_model
  model_instance_name: extract_graph
  prompt: "prompts/extract_graph.txt"
  entity_types:
    - organization
    - person
    - geo
    - event
  max_gleanings: 1

completion_model_id · string · required

Reference to completion model configuration

prompt · string

Path to extraction prompt file

entity_types · array · default: "[organization, person, geo, event]"

List of entity types to extract

max_gleanings · integer · default: "1"

Number of additional extraction passes for thoroughness

NLP-based extraction

Configure NLP-based graph extraction (alternative to LLM):

extract_graph_nlp:
  normalize_edge_weights: true
  concurrent_requests: 25
  async_mode: threaded  # threaded or asyncio
  text_analyzer:
    extractor_type: regex_english  # regex_english, syntactic_parser, cfg
    max_word_length: 15
    include_named_entities: true

Description summarization

Configure entity and relationship description summarization:

summarize_descriptions:
  completion_model_id: default_completion_model
  model_instance_name: summarize_descriptions
  prompt: "prompts/summarize_descriptions.txt"
  max_length: 500
  max_input_tokens: 4000

max_length · integer · default: "500"

Maximum output tokens per summary

max_input_tokens · integer · default: "4000"

Maximum input tokens to collect for summarization

Graph clustering

Configure Leiden hierarchical clustering:

cluster_graph:
  max_cluster_size: 10
  use_lcc: true
  seed: 0xDEADBEEF

max_cluster_size · integer · default: "10"

Maximum cluster size for export

use_lcc · boolean · default: "true"

Whether to use only the largest connected component

seed · integer · default: "0xDEADBEEF"

Random seed for consistent clustering results

Graph pruning

Configure optional graph pruning to optimize modularity:

prune_graph:
  min_node_freq: 2
  max_node_freq_std: null
  min_node_degree: 1
  max_node_degree_std: null
  min_edge_weight_pct: 40.0
  remove_ego_nodes: true
  lcc_only: false

min_node_freq · integer · default: "2"

Minimum node frequency to retain

min_node_degree · integer · default: "1"

Minimum node degree (connections) to retain

min_edge_weight_pct · float · default: "40.0"

Minimum edge weight percentile to retain

remove_ego_nodes · boolean · default: "true"

Remove ego nodes (nodes connected to everything)

Community reports

Configure community report generation:

community_reports:
  completion_model_id: default_completion_model
  model_instance_name: community_reporting
  graph_prompt: "prompts/community_report_graph.txt"
  text_prompt: "prompts/community_report_text.txt"
  max_length: 2000
  max_input_length: 8000

graph_prompt · string

Prompt for graph-based community summarization

text_prompt · string

Prompt for text-based community summarization

max_length · integer · default: "2000"

Maximum output tokens per report

max_input_length · integer · default: "8000"

Maximum input tokens for report generation

Claim extraction

Configure optional claim extraction:

extract_claims:
  enabled: false
  completion_model_id: default_completion_model
  prompt: "prompts/extract_claims.txt"
  description: "Any claims or facts that could be relevant to information discovery."
  max_gleanings: 1

Claim extraction is disabled by default and requires prompt tuning for your specific domain.

Snapshots

Configure optional data snapshots:

snapshots:
  embeddings: false
  graphml: false
  raw_graph: false

embeddings · boolean · default: "false"

Export embeddings to parquet files

graphml · boolean · default: "false"

Export graph to GraphML format

raw_graph · boolean · default: "false"

Export raw extracted graph before merging

Query configurations

Local search

Configure local search for targeted queries:

local_search:
  completion_model_id: default_completion_model
  embedding_model_id: default_embedding_model
  prompt: "prompts/local_search_system_prompt.txt"
  text_unit_prop: 0.5
  community_prop: 0.15
  conversation_history_max_turns: 5
  top_k_entities: 10
  top_k_relationships: 10
  max_context_tokens: 12000

Global search

Configure global search for broad queries:

global_search:
  completion_model_id: default_completion_model
  map_prompt: "prompts/global_search_map_system_prompt.txt"
  reduce_prompt: "prompts/global_search_reduce_system_prompt.txt"
  knowledge_prompt: "prompts/global_search_knowledge_system_prompt.txt"
  data_max_tokens: 12000
  map_max_length: 1000
  reduce_max_length: 2000
  dynamic_search_threshold: 1

DRIFT search

Configure DRIFT search for iterative exploration:

drift_search:
  completion_model_id: default_completion_model
  embedding_model_id: default_embedding_model
  prompt: "prompts/drift_search_system_prompt.txt"
  reduce_prompt: "prompts/drift_search_reduce_prompt.txt"
  n_depth: 3
  drift_k_followups: 20
  concurrency: 32

Basic search

Configure basic vector search:

basic_search:
  completion_model_id: default_completion_model
  embedding_model_id: default_embedding_model
  prompt: "prompts/basic_search_system_prompt.txt"
  k: 10
  max_context_tokens: 12000

Advanced settings

Workflows

Override the default workflow execution order:

workflows:
  - extract_graph
  - summarize_descriptions
  - cluster_graph
  - community_reports

Most users don’t need to customize workflows. Only specify this if you want precise control over execution order.

Concurrency settings

Control global concurrency for async operations:

concurrent_requests: 25
async_mode: threaded  # threaded or asyncio

Next steps

LLM models

Detailed guide to configuring language models

Storage

Configure storage backends and caching

Initialization

Learn about the init command

Start indexing

Begin processing your documents