Skip to main content

explain

Ask the server how it plans a PPL query, without running it.

lynxdb explain '<PPL query>' [flags]

The CLI calls GET /api/v1/query/explain on the server named by --server. The server compiles the query and returns:

  • the logical plan: the IR tree the compiler produced from the PPL text;
  • the optimized plan: the tree after the rule-based optimizer, with the scan's column list and pruning predicate;
  • the optimizer rules that fired, with how often each fired;
  • scan hints: the result type (events or aggregate), a cost class, the free-text search terms, the fields read, and the sources in scope. A plan that reads every event of its sources says so.

Flags​

FlagDefaultDescription
--analyzefalseRun the query as well, and print its execution profile after the plan

--format json prints the server's explain response, and with --analyze the profile, as one JSON document.

Example​

lynxdb explain 'source=main timeout | stats count() by host'
Logical plan:
Project(`count()`, host)
└─ Aggregate(`count()` = count() BY host)
└─ Filter(SEARCH_WORD(_raw, "timeout"))
└─ Scan(main)

Optimized plan:
Project(`count()`, host)
└─ Aggregate(`count()` = count() BY host)
└─ Filter(SEARCH_WORD(_raw, "timeout"))
└─ Scan(main) columns=[_raw, _time, host] prune=SEARCH_WORD(_raw, "timeout")

Optimizer rules:
prune-scan x1

Scan:
result type aggregate
cost medium
search terms timeout
fields read _raw, _time, host
sources single main

The free-text term timeout becomes a SEARCH_WORD filter on _raw, and the scan reads three columns of the index main.

With --analyze​

lynxdb explain --analyze 'source=main level=ERROR | stats count()'

After the plan, the CLI runs the query and prints its profile: the time spent in each phase and the total.

  ══════ Query Profile ══════

Phase Breakdown:
exec 102µs 6% ████████████████████
──────────
total 1ms

The query runs over all time; explain has no time-range flags.

Invalid queries​

A query that does not compile prints the server's error code and message, the query with a caret under the position and, when the compiler has one, a suggestion. The command then exits with code 1.

explain compared with query --explain​

lynxdb explainlynxdb query --explain
Where it compilesOn the serverIn the CLI
Needs a serverYesNo
Logical and optimized plans, optimizer rulesYesYes
Scan hints: result type, cost, search terms, fields read, sourcesYesNo
Execution profileWith --analyzeNo

See also​