Skip to main content

​
Manage Large Graphs

As your graphs grow, organization becomes critical. This guide shows you best practices for managing large, complex graphs with many nodes and connections.

​
Prerequisites

Before you begin, make sure you have:

Graph Experience

Experience creating and running smaller graphs. You understand the basics.

Large Graph

A graph that’s becoming complex (10+ nodes, many connections).

Organization Goals

Goals for improving graph organization and maintainability.

Graph Editor Open

Cerulion Graph Editor running with your graph open.
Large graphs (20+ nodes) can become hard to understand and maintain. These practices help keep them manageable.

​
Challenges with Large Graphs

Large graphs face several challenges:
  • Visual clutter - Too many nodes and connections make the canvas hard to read
  • Navigation difficulty - Finding specific nodes becomes time-consuming
  • Maintenance burden - Changes require understanding the entire graph
  • Performance issues - Very large graphs may run slower
  • Collaboration problems - Team members struggle to understand the system

​
Best Practices

Organize nodes into logical groups:
1

Identify functional groups

Identify nodes that work together:
  • Input group - Nodes that receive external data
  • Processing group - Nodes that transform data
  • Output group - Nodes that send results
2

Arrange spatially

Place related nodes near each other:
  • Left side - Input/publisher nodes
  • Center - Processing nodes
  • Right side - Output/subscriber nodes
3

Use visual separation

Add space between groups:
  • Vertical spacing - Separate groups vertically
  • Horizontal flow - Arrange groups left-to-right
  • Clear boundaries - Use whitespace to separate groups

​
2. Use Descriptive Names

Clear naming makes graphs self-documenting:
  • Node names - Describe what the node does (e.g., Temperature Processor, not Node1)
  • Topic names - Indicate what data flows through (e.g., temperature_readings, not topic1)
  • Schema names - Clearly identify data structures (e.g., TemperatureReading, not Data)
Good names eliminate the need for extensive documentation. The graph becomes self-explanatory.

​
3. Minimize Cross-Connections

Reduce connections that cross the graph:
1

Arrange nodes linearly

Arrange nodes so data flows in one direction:
  • Top to bottom - Or left to right
  • Minimal back-edges - Avoid connections that go backward
  • Clear flow - Data should flow in a predictable direction
2

Use intermediate nodes

Instead of long connections, use intermediate nodes:
  • Break long paths - Add nodes in the middle
  • Reduce crossing - Shorter connections cross less
  • Improve readability - Easier to follow data flow

​
4. Create Subgraphs

Break large graphs into smaller subgraphs:
1

Identify subsystems

Find groups of nodes that form a subsystem:
  • Input subsystem - All input handling
  • Processing subsystem - Core processing logic
  • Output subsystem - All output handling
2

Create separate graphs

Create separate graph files for each subsystem:
  • Main graph - Orchestrates subsystems
  • Sub-graphs - Contain subsystem nodes
  • Clear interfaces - Define how subgraphs connect
3

Connect subgraphs

Connect subgraphs through well-defined interfaces:
  • Input topics - Subgraph receives data
  • Output topics - Subgraph produces data
  • Minimal coupling - Subgraphs interact through topics only

​
5. Document Your Graph

Add documentation to explain complex parts:
  • Comments - Add notes on nodes explaining non-obvious logic
  • README - Document the overall graph structure
  • Diagrams - Create high-level architecture diagrams
  • Annotations - Use node descriptions to explain purpose
Documentation helps when revisiting graphs later or when onboarding new team members.

​
6. Use Consistent Patterns

Establish patterns and use them consistently:
  • Naming conventions - Consistent naming across nodes
  • Layout patterns - Similar graphs use similar layouts
  • Connection patterns - Use the same connection styles
  • Code patterns - Similar nodes use similar code structure
Consistent patterns make graphs easier to understand. Once you learn one part, you understand similar parts.

​
7. Leverage Reusable Components

Create reusable node types:
1

Identify common patterns

Find nodes that appear multiple times:
  • Data transformers - Common transformation logic
  • Validators - Data validation nodes
  • Formatters - Output formatting nodes
2

Create templates

Create node templates for common patterns:
  • Save node configurations - As templates
  • Reuse across graphs - Use templates in multiple graphs
  • Maintain centrally - Update templates in one place

​
Organizational Strategies

​
Layered Architecture

Organize graphs in layers: 
Layer 1: Input (Sensors, Publishers)
    ↓
Layer 2: Processing (Transformers, Filters)
    ↓
Layer 3: Aggregation (Joiners, Mergers)
    ↓
Layer 4: Output (Loggers, Actuators)

​
Pipeline Stages

Organize as sequential stages: 
Stage 1: Data Collection
Stage 2: Data Cleaning
Stage 3: Data Processing
Stage 4: Data Analysis
Stage 5: Data Output

​
Domain-Driven Organization

Organize by business domain: 
Domain: Sensor Management
Domain: Data Processing
Domain: User Interface
Domain: Storage

​
Tools and Features

​
Canvas Navigation

Use navigation features:
  • Zoom - Zoom in/out to see details or overview
  • Pan - Move around large canvases
  • Fit to Screen - See entire graph at once
  • Search - Find nodes by name

​
Node Filtering

Filter nodes to focus on specific parts:
  • By type - Show only certain node types
  • By connection - Show nodes connected to selected node
  • By name - Filter by name pattern

​
Graph Views

Create different views of the same graph:
  • Overview - High-level architecture view
  • Detail - Detailed implementation view
  • Data flow - Focus on data flow paths
  • Execution - Focus on execution order

​
Performance Considerations

Large graphs may have performance implications:
  • Code generation time - Larger graphs take longer to generate
  • Build time - More nodes mean longer compilation
  • Runtime overhead - More nodes consume more resources
  • Memory usage - Large graphs use more memory
If your graph has 50+ nodes, consider breaking it into multiple graphs or using subgraphs.

​
Troubleshooting Large Graphs

Problem: Too many nodes and connections make the graph unreadable.Solutions:
  • Group related nodes together
  • Use subgraphs to break into smaller pieces
  • Minimize cross-connections
  • Use zoom and pan to navigate
  • Consider splitting into multiple graphs
Problem: Can’t find specific nodes in a large graph.Solutions:
  • Use search functionality to find nodes by name
  • Use node filtering to show only relevant nodes
  • Organize nodes into clear groups
  • Use consistent naming conventions
  • Create an index or map of node locations
Problem: Large graph runs slowly or uses too much memory.Solutions:
  • Break graph into smaller subgraphs
  • Optimize node code for performance
  • Reduce unnecessary nodes
  • Use more efficient data structures
  • Profile to identify bottlenecks

​
Next Steps

Now that you understand large graph management, learn more:

Examples

See examples of well-organized graphs.

Concepts

Review core concepts for better graph design.

Performance

Optimize your graphs for better performance.

Reference

See naming conventions and best practices.