Query & Visualization

Goal

Exact retrieval. Live dashboards. Pipe to tools. Embed in docs. Zero guesswork.

6.1 Find Basics

Start simple. Filter. Sort. Group. Done.

onde find task                              # all tasks
onde find task --status BLOCKED             # filter
onde find task --sort priority              # sort
onde find task --group-by status            # group
onde find task --limit 10 --offset 20       # paginate

Rules:

Filters match property keys exactly. --status BLOCKED ≠ --status blocked.
Schema defaults apply when flags missing. (@sort, @group from schema)
Output prints to terminal. Pipe or redirect anytime.

6.2 Output Formats

One flag. Many shapes. Pick by destination.

onde find task --format md          # standard markdown (re-ingestable)
onde find task --format md-dense    # compact TOON rows (agent-friendly)
onde find task --format table       # terminal grid
onde find task --format json        # scripts, LLMs, APIs
onde find task --format csv         # spreadsheets
onde find task --format mermaid     # diagrams (GitHub/VS Code render)
onde find task --format dot         # Graphviz
onde find task --format lines       # one line per node (grep-friendly)

Write directly to disk:

onde find task --format md --output reports/blocked.md
# Auto-creates parent dirs. Overwrites safe.

Core Rule: md and md-dense output = valid input. Query → file → onde lint → graph absorbs it. Round-trip guaranteed.

6.3 Query DSL (`onde q`)

When find flags hit limits. Pipes chain logic. Arrows traverse edges.

# Group + count
onde q 'task | group by status | count'

# Multi-hop: blocked tasks that depend on TODO tasks
onde q 'task[status=BLOCKED] >depends> task[status=TODO]'

# Reverse: people who own TODO tasks
onde q 'person <owns< task[status=TODO]'

# Negation: tasks with zero dependencies
onde q 'task NOT >depends> task'

# Variables + aggregation
onde q '$p = person <owns< task[status=TODO] | group by $p | count'

Syntax Cheat:

> forward edge. < backward edge.
| pipe to next step.
group by, sort, count, avg, sum, having work like SQL but lighter.
Relative dates: today, -7d, +3d. Absolute: 2026-04-10.

Rule: Start with find. Graduate to q when you need multi-hop, negation, or variables.

6.4 Graph Traversal

Follow edges. See chains. Measure impact.

Command	What It Follows	Depth
`onde deps <id>`	`depends` edges only	Direct (use `--depth N` for more)
`onde depended-by <id>`	Reverse `depends`	Direct
`onde ancestors <id>`	ALL edge types upstream	Full tree
`onde descendants <id>`	ALL edge types downstream	Full tree
`onde path <from> <to>`	ALL edges	Shortest route
`onde impact <id>`	ALL edges reachable	Full fan-out

Examples:

onde deps task-882 --depth 3 --format mermaid
onde impact task-882 --format tree
onde path task-882 task-895

Rule: deps/depended-by = edge-specific. ancestors/descendants/impact = type-agnostic. Cycle-safe. Never infinite loop.

(Time-travel traversal with --as-of → Section 7)

6.5 Embedded Queries (`onde::`)

Live views inside markdown. Auto-refresh on onde lint. Zero config.

Write query line:

## Blocked Tasks
onde:: find task --status BLOCKED --fields id,title,status

Run onde lint. Result fills below:

## Blocked Tasks
onde:: find task --status BLOCKED --fields id,title,status
- task-882 | Fix token refresh | BLOCKED
- task-895 | API rate limit | BLOCKED

View Formats: list (default), dense, table, cards, timeline, tree, mermaid, csv, json.

onde:: task[status=BLOCKED] --format cards --fields id,title,priority
onde:: impact task-882 --format tree
onde:: q 'task | group by status | count' --format table

Bidirectional Rule:

--fields present = editable. Change BLOCKED → DONE in result → onde lint updates source node → all mirrors/queries cascade.
No --fields = read-only cache. Manual edits overwritten next lint.
Computed fields (@edge_count, aggregations) = read-only.

Dashboard Pattern: Stack multiple onde:: blocks in one file. One onde lint refreshes all.

6.6 Daily Patterns

Goal	Command
Quick terminal scan	`onde find task --format table`
Feed LLM/agent	`onde find task --format json \| llm "prioritize"`
Export to sheets	`onde find task --format csv --output data/tasks.csv`
Live project board	`onde::` blocks + `--format cards` + `--group-by status`
Dependency map	`onde deps task-882 --format mermaid --output docs/deps.mmd`
Bulk edit via query	`onde:: find task --fields id,status` → edit rows → `onde lint`

6.7 Common Traps

Trap	Symptom	Fix
Edits vanish	Edited query result, next lint overwrote it	Add `--fields`. Enables bidirectional sync.
Wrong traversal	Used `deps` expecting all edges	`deps` = `depends` only. Use `ancestors`/`impact` for all edges.
Fuzzy search fail	`--status block` returns nothing	Filters exact. Use full value or DSL regex later.
DSL syntax error	Quotes/brackets mismatched	Wrap complex DSL in single quotes: `onde q '...'`
Overcomplicating	Writing 5-line DSL for simple filter	Use `onde find --flag`. DSL for multi-hop/negation only.

Next Step: → Time Travel & History: Never Lose Context