Collections Graph

Render a live graph of your Typesense collections and their interconnections (Unicode or ASCII), plus Mermaid output for docs.

Overview

Render a live graph of your Typesense collections and their interconnections directly in the terminal, using Unicode box‑drawing by default with an ASCII fallback.

• Discovers collections and references from Typesense live schemas (fallback to local registry).
• Builds a forward graph (from referrer → referenced collection).
• Detects isolated collections and immediate cycles (A ↔ B).
• Renders:
  • ascii: layered boxes with labeled connectors when width allows
  • ascii_compact: grouped list for narrow terminals

Usage

# Auto width detection; Unicode boxes
g = SearchEngine.collections_graph
puts g[:ascii]          # layered when it fits terminal width
puts g[:ascii_compact]  # compact grouped list

# Mermaid (for docs)
File.write('collections.mmd', g[:mermaid])

# Options
SearchEngine.collections_graph(style: :unicode, width: 120)  # force width
SearchEngine.collections_graph(style: :ascii)                # ASCII only

Output (layered)

Collections Graph (nodes: N, edges: M)

┌──────────┐                          ┌─────────────┐
│ books    │  ── via publisher_id → id ── │ publishers │
└──────────┘                          └─────────────┘

┌──────────┐                                ┌─────────┐
│ books    │  ── via author_ids → id ──  │ authors │
└──────────┘                                └─────────┘

Isolated: …
Cycles: none

Output (compact)

Collections Graph (nodes: N, edges: M)
- books
  └─ ▶ publishers   [via publisher_id -> id]
  └─ ▶ authors      [via author_ids -> id]
Isolated: …
Cycles: none

Notes

• Width is detected via IO.console.winsize, then ENV[‘COLUMNS’], then stty size; defaults to 100 if unknown.
• Live discovery uses field reference: “<collection>.<foreign_key>” from Typesense schemas; falls back to compiled model schemas when Typesense is unavailable.
• Emits search_engine.collections.graph with counts and layout mode.

Mermaid

Use the returned mermaid string to embed diagrams in docs:

You can also render images locally via @mermaid-js/mermaid-cli:

npm i -g @mermaid-js/mermaid-cli
mmdc -i collections.mmd -o collections.png

See also

Schema

Compile model → Typesense schema and manage lifecycle

Indexer

Index collections and documents efficiently

Joins

Related collections and reference/association features

DX

Developer experience tools and CLI