Query Plan¶

--explain prints a formatted query plan and exits without connecting or executing.

-v/--verbose prints the same plan to stderr, then runs, tracing each backend command.

Examples¶

./iq --src orders '.[] | select(.total > 99) | {id, total}' --explain

./iq --src orders '.[] | select(.total > 99) | {id, total}' --explain -v

./iq --src cache '.[] | select(.active)' --explain

./iq --src orders '.[] | select(.total > 99 and (.active | not))' --explain

./iq --src orders '.[] | select(.total > 99)' -v

./iq '.[]' -v 2>/dev/null

Breakdown¶

The plan shows four things, syntax-highlighted when the destination is a terminal:

• Filter

  • The jq filter pretty-printed with real line breaks. Nested source("name"; "<jq>") sub-filters and every iq combine fragment are formatted too.

  • Under -v/--verbose, each top-level pipe stage also carries a short right-aligned note describing it (— keep inputs where …). The stage that reads from the store is marked with its route, colored by cost.

    • A green bounded read (keyed lookup)
    • A yellow streaming scan (batched over .[])
    • A red materialized scan (an aggregate, a non-.[] root, or any scan under --unbounded)

• Access Plan

  • The concrete backend calls each source will make, derived from the filter's route (bounded keys, streaming scan, or materialize)

• Pushdown

  • The breakdown: one line per top-level select(...) conjunct. Each line says whether the backend evaluates it (pushed) or it re-runs client-side (client-side). It also says why a client-side conjunct did not push.
  • A conjunct is client-side when the compiler cannot express it as a provable superset (an inexact negation, a non-portable regex, an unsafe field name, or any other unpushable construct). It is also client-side when the backend's translator declines the compiled predicate (a range on Elasticsearch, say), or when the source does no server-side filtering at all (the read-only file driver).
  • This is the observable split of what the backend evaluated versus what ran client-side. It is absent under --no-compile.

• Compiled Filter

  • As JSON, the merged fragment of the pushed conjuncts.