--explain output

--explain prints a stable plan report and exits without executing the query. It does not contact a provider or local model.

Pure-jq report

ajq explain v1
query: ".users[] | select(.active) | .name"
execution: pure-jq deterministic
deterministic: yes
model_calls: 0
backend_calls: 0
byte_reproducible: yes
stdin: ignored

Semantic report

ajq explain v1
query: ".[] | select(sem_match(.msg; \"urgent\")) | .msg"
execution: semantic split plan
deterministic: no
model_calls: input-dependent
backend_calls: input-dependent
byte_reproducible: cache-dependent
stdin: harvested for estimates
planned_call_sites: 1
semantic_predicates: 1
semantic_values: 0
estimates:
  estimate_status: available
  static_call_sites: 1
  input_frames: 1
  harvested_judgements: 3
  post_dedup_judgements: 2
  mock_judge_batches: 1
  over_harvest_bound: post_dedup_judgements == mock distinct judgements; may be a safe superset of execute-needed judgements
subgraphs:
  deterministic: jq outside semantic call sites
  semantic: 1 planned call site(s)
semantic_plan:
  - call_id: 1
    op: "sem_match"
    kind: "predicate"
    value_expr: ".msg"
    specs: ["urgent"]
    source_range: 13:38
    gated: n/a
    execution: 3-phase
    subgraph: semantic

Header fields

estimates block

Present when valid stdin was supplied and the mock harvest path can estimate the query.

semantic_plan entries

When estimates are unavailable

If stdin is empty or invalid, or the query uses a semantic execution shape the current executor cannot safely estimate/execute, the static plan is still printed and estimate_status is marked unavailable with a reason.

--explain --stream is intentionally unavailable without reading stdin. Its report names semantic user-stream inline, says stdin: not harvested, and includes execution_selection: user-selected --stream interleaving, inline per-uncached-judgement batching, and disabled cross-frame pre-resolve deduplication. This is a mode choice, not a change to backend/model/cache identity or the run-global call cap.

The important distinction is execution mode. sem_score in sort_by(...) and sem_norm in group_by(...) can use the three-phase placeholder path. Gated unbounded value shapes, such as select(sem_score(.review; "positivity") > 0.8), can use interleaved fallback; their estimate status is unavailable because ajq resolves values as execution reaches them rather than harvesting a complete up-front set. Standalone sem_extract and sem_redact are registered but currently fail as unsupported in three-phase execution.

Related

• Estimate model calls before running — using these numbers.
• Control semantic costs — cap and inspect real runs.
• The three-phase executor — harvest, deduplication, and cache behavior.