Skip to main content

​
What is Relational Mode?

Relational mode (-r flag) enables deep dependency analysis. Instead of just looking at files in the error stack, Splat:
  1. Parses the error stack trace
  2. Identifies all files involved
  3. Builds a dependency graph of imports/includes
  4. Recursively follows relationships to Nth degree
  5. Gathers context from all related files
  6. Provides fixes with full understanding of your codebase
Relational mode is essential for debugging errors that span multiple modules, especially in large codebases with complex dependencies.

​
Basic Syntax

splat squash -r "<your-command>"
The -r flag must come before your command.

​
How It Works

​
Standard Mode (Without -r)

$ splat squash "python3 app.py"
1

Parse Error Stack

Extracts only the files mentioned in the error traceback
2

Gather Context

Reads content from error stack files only
3

Generate Fix

AI analyzes limited context and suggests a fix
Files analyzed: Only those in the error stack (typically 1-3 files)

​
Relational Mode (With -r)

$ splat squash -r "python3 app.py"
1

Parse Error Stack

Extracts files mentioned in the error traceback
2

Build Dependency Graph

Analyzes import statements and builds an adjacency list of all related files
3

Recursive Traversal

Follows imports recursively to find all Nth-degree related files
4

Gather Full Context

Reads content from all related files in the dependency graph
5

Generate Contextual Fix

AI analyzes complete context and suggests an informed fix
Files analyzed: All files in the dependency tree (can be 10+ files)

​
Dependency Graph Example

Consider this project structure: 
project/
├── app.py          # Imports utils/database.py
├── models.py       # Imported by database.py
└── utils/
    ├── database.py  # Imports models.py, config.py
    └── config.py    # Base configuration

​
Error in app.py

from utils.database import get_connection

def main():
    conn = get_connection()
    result = conn.execute_query("SELECT * FROM users")  # Error: wrong method
    print(result)

​
Without -r Flag

$ splat squash "python3 app.py"

 Analyzing error...
 Files analyzed: app.py

 Error: AttributeError: 'Connection' object has no attribute 'execute_query'

 Note: Limited context - consider using -r flag for better analysis
Splat only sees app.py and doesn’t know about the Connection class definition in models.py.

​
With -r Flag

$ splat squash -r "python3 app.py"

 Building dependency graph...
 Files analyzed:
   - app.py
   - utils/database.py
   - models.py
   - utils/config.py

 Analyzing error with full context...

 Error: AttributeError: 'Connection' object has no attribute 'execute_query'
 File: app.py:5

 Analysis:
  The Connection class (defined in models.py) has a 'query' method,
  not 'execute_query'. The error occurs because app.py is calling
  the wrong method name.

 Suggested fix:
  Change 'execute_query' to 'query'

 Fix applied successfully!
With relational mode, Splat understands the full context by analyzing models.py and sees the correct method name.

​
Real-World Use Cases

​
Multi-Module Import Errors

$ splat squash "python3 main.py"

 ImportError: cannot import name 'UserService'
 Limited context available

​
Type Mismatch Across Modules

$ splat squash "npm start"

 TypeError: Cannot read property 'map' of undefined
 File: components/UserList.js:12

​
Configuration Issues

$ splat squash -r "python3 manage.py runserver"

 Dependency graph includes:
   manage.py → settings.py → config/database.py → config/base.py

 Error: django.core.exceptions.ImproperlyConfigured

 Analysis:
  DATABASE_URL environment variable referenced in config/database.py
  but not set. Default config in config/base.py suggests using SQLite
  for development.

 Suggested fix:
  Set DATABASE_URL in .env or update settings.py to use SQLite default

 Would you like me to:
  1. Create .env with SQLite default
  2. Update settings.py to fallback to SQLite

​
Performance Considerations

Use relational mode when:
  • Error involves multiple files
  • Import/dependency issues
  • Type mismatches across modules
  • Configuration errors
  • Complex application logic
  • First time debugging unfamiliar code
Skip -r for simple cases:
  • Single-file syntax errors
  • Simple typos
  • Missing brackets/parentheses
  • Quick iterations on the same error
  • Without -r: ~1-2 seconds (1-3 files)
  • With -r: ~3-5 seconds (5-20 files)
  • Large projects: ~5-10 seconds (20+ files)
Splat uses Groq’s fast inference to keep analysis quick even with full context.
Relational mode respects your .gitignore:
  • Skips node_modules/, venv/, .env files
  • Won’t analyze files in ignored directories
  • Keeps sensitive data private
Only project files tracked by git are included in the dependency graph.

​
Technical Details

Relational mode uses these algorithms:

​
1. Error Stack Parsing

def parse_error_stack(error_info: str) -> List[str]:
    # Extracts file paths from error traces
    # Regex pattern matches: File "path/to/file.py", line X
    file_pattern = re.compile(r'(?:File "([^"]+)")')
    return list(set(matches))

​
2. Dependency Graph Building

def build_adjacency_list(files: List[str], project_root: str) -> Dict[str, List[str]]:
    # Parse AST to find imports
    # Build adjacency list: {file: [imported_files]}
    # Recursively process imported files
    return adjacency_list

​
3. Nth Degree Traversal

def get_nth_related_files(start_files: List[str], graph: Dict) -> Set[str]:
    # BFS traversal of dependency graph
    # Returns all files reachable from start_files
    return related_files
This ensures complete context for AI analysis.

​
Tips for Best Results

Optimize Your Workflow

  1. Start with -r for new errors - Get full context on first try
  2. Use standard mode for iterations - Faster when fixing the same issue
  3. Keep dependencies clean - Smaller graphs = faster analysis
  4. Check .gitignore - Ensure it excludes dependencies and build artifacts
Very large projects (1000+ files) may take longer. Consider organizing code into smaller modules or microservices for better Splat performance.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us