Visualization

Overview

sqry visualize turns any relation query into a diagram. It reads relation data directly from the unified graph snapshot, so results are consistent with sqry query and sqry graph commands.

If the graph snapshot is missing, sqry visualize automatically builds it from source. For large repositories, running sqry index first is recommended to avoid the build overhead on first use.

Three output formats are supported:

All formats emit plain text to stdout by default. Use --output-file to write to a file instead.

Basic Usage

sqry visualize "callers:main" --format mermaid

The query argument accepts relation predicates:

• callers:<symbol> — nodes that call the named symbol
• callees:<symbol> — nodes called by the named symbol
• imports:<substring> — files that import a module matching the substring
• exports:<symbol> — files that export the named symbol

Mermaid

Mermaid diagrams are the default format. GitHub renders them inline when pasted into .md files, making them useful for architecture documentation and pull request descriptions.

sqry visualize "callers:AuthService.login" --format mermaid --path .

Example output:

graph TD
    api_handler --> AuthService.login
    middleware_auth --> AuthService.login
    test_login --> AuthService.login

Paste this block into any Markdown file with a mermaid code fence and GitHub (or any Mermaid-aware renderer) will draw the diagram automatically.

Control traversal depth and direction:

sqry visualize "callers:main" --format mermaid --depth 5 --max-nodes 200 --direction left-right

Available --direction values: top-down, bottom-up, left-right, right-left.

Graphviz DOT

DOT format is compatible with the Graphviz dot tool and any renderer that accepts .dot files.

# Generate the DOT file
sqry visualize "imports:std" --format graphviz --output-file deps.dot --path .

# Render to PNG with Graphviz
dot -Tpng deps.dot -o deps.png

# Render to SVG (vector, scales cleanly in docs)
dot -Tsvg deps.dot -o deps.svg

Graphviz DOT is well-suited for large dependency trees where you need precise layout control. The dot, neato, fdp, and circo layout engines each produce different arrangements — dot (hierarchical) is usually the right starting point for call graphs, while fdp or neato work better for dense import graphs.

D2

D2 is a modern diagram language with clean output and scripting support.

sqry visualize "callees:process" --format d2 --depth 5

To render with the D2 CLI:

sqry visualize "callees:process" --format d2 --output-file graph.d2
d2 graph.d2 graph.svg

D2 supports themes, layout engines (dagre, elk), and directional preferences through its own flags. See the D2 documentation for rendering options.

Use Cases

Architecture documentation — Generate a DOT or Mermaid diagram of your module import graph and embed it in a README.md or architecture doc. The diagram stays current because it is generated from the live index rather than maintained by hand.

Pull request reviews — Add a visualization of what changed structurally to a PR description. For example, show the call graph around a refactored function before and after the change so reviewers can see the impact at a glance:

# On the feature branch
sqry visualize "callers:process_payment" --format mermaid

Onboarding new developers — Generate a callees diagram for a key entry point (for example, callees:main or callees:handle_request) to give new team members a map of execution flow before they read individual files:

sqry visualize "callees:handle_request" --format mermaid --depth 3