Visualization

Visualize and debug your GraphRAG knowledge graphs using Gephi and GraphML exports

GraphRAG generates GraphML files that can be visualized using graph visualization tools like Gephi. This guide walks you through the complete process of creating beautiful, insightful visualizations of your knowledge graph.

Overview

Visualizing your knowledge graph helps you:

• Understand structure: See how entities and relationships are organized
• Identify clusters: Discover communities and themes in your data
• Debug issues: Spot problems with entity extraction or relationships
• Communicate insights: Share visual representations with stakeholders

Prerequisites

Before visualizing your graph, you need:

• A completed GraphRAG index with GraphML snapshots enabled
• Gephi installed on your system
• The Leiden Algorithm plugin for Gephi

Enable GraphML snapshots

GraphML snapshots must be enabled during indexing to generate visualization files.

1. Configure settings.yaml

   Open your settings.yaml and ensure GraphML snapshots are enabled:

   settings.yaml

   snapshots:
     graphml: true
   

   This setting is enabled by default in newly initialized projects.

2. Run the index

   graphrag index --root ./my-project
   

   This generates a graph.graphml file in your output directory.

3. Locate the GraphML file

   After indexing completes, find the file at:

   ./my-project/output/graph.graphml
   

If you’ve already run indexing without GraphML enabled, you’ll need to re-run the index with the setting enabled.

Visualization workflow

Follow these steps to create a professional graph visualization:

1. Import into Gephi

1. Launch Gephi

   Open Gephi on your system.

2. Import the GraphML file

   1. Go to File → Open
   2. Navigate to your output folder
   3. Select graph.graphml
   4. Click Open

   You’ll see a basic visualization of your graph nodes and edges.

2. Install Leiden Algorithm plugin

The Leiden algorithm detects communities in your graph, which is essential for meaningful visualization.

1. Open Plugin Manager

   Go to Tools → Plugins

2. Find Leiden Algorithm

   1. Click the Available Plugins tab
   2. Search for “Leiden Algorithm”
   3. Check the box next to it
   4. Click Install
3. Restart Gephi

   Restart Gephi after installation completes

3. Run statistics

Generate statistics that will help you visualize the graph structure.

1. Calculate Average Degree

   In the Statistics panel (right side):

   1. Find Average Degree
   2. Click Run
   3. Click Close on the report dialog
2. Run Leiden Algorithm

   In the Statistics panel:

   1. Find Leiden Algorithm
   2. Click Run
   3. Configure settings:
      • Quality function: Modularity
      • Resolution: 1.0
   4. Click OK
   5. Close the report when complete

The Leiden algorithm identifies communities (clusters) in your graph. Higher resolution values create more, smaller communities.

4. Color nodes by cluster

Color-code nodes based on their community membership.

1. Open Appearance panel

   Find the Appearance panel in the upper left

2. Configure node colors

   1. Click the Nodes tab
   2. Click Partition (not Ranking)
   3. Click the color palette icon in the upper right
   4. Select Cluster from the dropdown
3. Generate color palette

   1. Click Palette…
   2. Click Generate…
   3. Uncheck Limit number of colors
   4. Click Generate
   5. Click OK
4. Apply colors

   Click Apply to color your graph

Your graph should now show different colored clusters representing communities in your knowledge graph.

5. Resize nodes by degree centrality

Make important nodes (with many connections) larger.

1. Select ranking mode

   In the Appearance panel:

   1. Ensure Nodes is selected
   2. Click Ranking (not Partition)
   3. Click the sizing icon (three circles of different sizes)
2. Configure node sizes

   1. Select Degree from the dropdown
   2. Set Min size: 10
   3. Set Max size: 150
3. Apply sizing

   Click Apply

Nodes with more connections will now appear larger, making hubs visually prominent.

6. Layout the graph

Arrange nodes spatially to reveal structure.

Step 1: OpenORD layout

1. Select OpenORD

   In the Layout panel (lower left), select OpenORD

2. Configure settings

   Set the following stage iterations:

   • Liquid: 50
   • Expansion: 50
   • Cooldown: 0
   • Crunch: 0
   • Simmer: 0
3. Run layout

   1. Click Run
   2. Watch the progress bar
   3. Click Stop when complete

OpenORD does initial positioning. The graph may still look messy - that’s expected.

Step 2: ForceAtlas2 layout

1. Select ForceAtlas2

   In the Layout panel, select Force Atlas 2

2. Configure settings

   Adjust the following settings:

   • Scaling: 15
   • Dissuade Hubs: ✓ checked
   • LinLog mode: ✗ unchecked
   • Prevent Overlap: ✓ checked
3. Run layout

   1. Click Run
   2. Watch as nodes settle into position
   3. Click Stop when nodes stop moving significantly

   This may take several minutes for large graphs. Be patient!

Your graph should now have a clean, organized layout with distinct communities.

7. Add labels (optional)

Display entity names on the visualization.

1. Show labels

   In the bottom toolbar of the graph view, click the Show node labels button (“T” icon)

2. Configure label appearance

   1. Click the label settings button
   2. Adjust:
      • Font size: Based on your preference
      • Show labels: For visible nodes only
      • Label color: Black or contrasting color
3. Resize labels (optional)

   You can also size labels by node degree for better readability

For large graphs, consider showing labels only for important nodes (high degree) to avoid clutter.

Understanding your visualization

Graph elements

Nodes

Represent entities extracted from your documents (people, organizations, concepts)

Edges

Represent relationships between entities

Colors

Indicate communities - groups of closely related entities

Size

Indicates centrality - how many connections an entity has

Interpreting patterns

Dense clusters: Topics or themes with many interconnected entities

Bridge nodes: Entities connecting different communities (often important cross-cutting concepts)

Peripheral nodes: Mentioned infrequently or in isolation

Star patterns: Central entities with many direct connections (key people, organizations, or concepts)

Export and share

Export as image

1. Open Preview

   Click the Preview tab at the top of Gephi

2. Configure preview

   Adjust settings for best appearance:

   • Preset: Default
   • Background color: White
   • Show labels: As desired
3. Export

   1. Click Export: SVG/PDF/PNG
   2. Choose format (PNG for presentations, SVG for editing)
   3. Set resolution (high for publications)
   4. Save file

Export interactive version

Gephi can export interactive web visualizations:

1. Install the Sigma Exporter plugin
2. Go to File → Export → Sigma.js template
3. Configure and export to create an interactive HTML visualization

Advanced techniques

Filter by community

Focus on specific communities:

1. Open Filters panel

   Find the Filters panel on the right

2. Add partition filter

   1. Expand Attributes → Partition
   2. Drag Cluster to the Queries area
3. Select communities

   Check/uncheck clusters to show/hide communities

4. Apply filter

   Click Filter to update the visualization

Size by other metrics

You can size nodes by different centrality measures:

• Betweenness centrality: Nodes that connect different parts of the graph
• Closeness centrality: Nodes close to all others
• Eigenvector centrality: Nodes connected to other important nodes

Run these under Statistics → Network Overview, then use them in the Appearance panel.

Multi-level analysis

GraphRAG’s Leiden algorithm creates hierarchical communities. To visualize different levels:

1. Run Leiden multiple times with different resolution parameters
2. Create separate visualizations for each level
3. Compare to see how communities nest within each other

Troubleshooting

Graph appears as a dense ball

Solution:

• Run ForceAtlas2 longer (it may take time to untangle)
• Increase Scaling parameter to 20-30
• Enable Prevent Overlap
• Try Fruchterman Reingold layout instead

Nodes are all the same color

Solution:

• Ensure you ran the Leiden Algorithm
• Check that you selected Partition not Ranking
• Verify Cluster appears in the dropdown
• Re-run Leiden if needed

Cannot find graph.graphml file

Solution:

• Verify snapshots.graphml: true in settings.yaml
• Re-run indexing with snapshots enabled
• Check the storage.base_dir setting for output location

Gephi crashes or runs slowly

Solution:

• Increase Gephi’s memory allocation
• Filter the graph to show fewer nodes
• Use a more powerful machine for large graphs
• Consider sampling your data before indexing

Example workflow summary

Here’s the complete process at a glance:

1. Enable GraphML

   snapshots:
     graphml: true
   
2. Run indexing

   graphrag index --root ./my-project
   
3. Import to Gephi

   Open output/graph.graphml

4. Install Leiden plugin

   Tools → Plugins → Leiden Algorithm

5. Run statistics

   • Average Degree
   • Leiden Algorithm (Modularity, Resolution 1.0)
6. Apply appearance

   • Color by Cluster (Partition)
   • Size by Degree (10-150)
7. Layout

   • OpenORD (Liquid 50, Expansion 50)
   • ForceAtlas2 (Scaling 15, Dissuade Hubs, Prevent Overlap)
8. Export

   Preview → Export as PNG/SVG

Next steps

Configuration

Learn about all configuration options

Best practices

Optimize your GraphRAG workflow

Query methods

Learn different search approaches

Data model

Understand the output schema