The --explain flag prints the query execution plan and exits without reading any log files or producing results.
Example
zeal --explain 'FROM app.json WHERE level = "error" WITHIN 5s OF level = "warn" GROUP BY request_id'
Query Plan
1. READ app.json (auto-detect format)
2. SCAN all entries
3. FILTER condition: level eq "error"
4. TEMPORAL find entries WITHIN 5s OF level eq "warn"
Strategy: binary search on sorted timestamps
5. GROUP BY request_id
Strategy: hash aggregation
6. OUTPUT text format
Use cases
Verify query syntax before running on large files. Explain mode parses and validates the query without touching the source files. If your query has a syntax error, you’ll see the error immediately.
# Catches syntax errors without reading multi-gigabyte log files
zeal --explain 'FROM /var/log/huge.log WHERE level = "error" AND status >= 500'
GROUP BY. This helps you anticipate performance before running.
Check that -f files are merged correctly. When combining -f flags with a FROM clause, the plan shows all sources that will be read:
zeal --explain -f app.log -f nginx.log 'WHERE status >= 500'
# Shows: READ app.log, READ nginx.log
Run --explain before executing any query against multi-gigabyte log files. It validates your query syntax and lets you review the plan at no cost.
