Expand description
EXPLAIN and EXPLAIN ANALYZE for field observations (Phase 11.5, ADR-0026).
explain is a pure function of validated metadata: it never materializes a
node and never writes to the store. explain_analyze executes the
observation and returns both the intended plan and the measured actual work,
which is the central evidence surface for Phase-11 claims (ADR-0027).
The JSON key sets are frozen and exact:
- plan —
selector,representation,format,adapter,capability,index_route,shape,index_reads,required_nodes,will_materialize,will_not_materialize. - actual —
format,adapter,index_nodes_read,seed_nodes_fetched,seed_nodes_materialized,member_decodes,xml_parses,nodes_id_shared,shared_resource_ids,inverse_work_units,descriptor_bytes_read,descriptor_read_mode,manifest_bytes_read,index_bytes_read,seed_bytes_read,bytes_read,bytes_returned,deepened,whole_source_materialized,wall_micros,basis,exact.
format/adapter are the detected format and its adapter; capability is the
resolved path (native, or common:<selector> -> <adapter>); index_route is
hier-index/none. member_decodes/xml_parses are observation-boundary
materialization requests (see ObserveStats); whole_source_materialized is
yes exactly when the answer verified whole-source integrity.
bytes_read is the sum of the four *_bytes_read classes: total physical
bytes this observation made the OS fetch, including the descriptor blob. It is
deliberately not the seed-store-only number it was before Phase 11.9’s
review (ADR-0027 accounting).
Structs§
- Explain
Actual - The measured cost of an executed observation.
- Explain
Plan - The intended plan plus its canonical JSON rendering.
Functions§
- explain
- Explain an observation without executing it. Pure.
- explain_
analyze - Execute an observation and report both the intended plan and actual work.