Execution Profile Reference

Use this page to interpret the immutable execution-profile data returned by profiled previews, SQL Server writes, and selected write_all cache aliases. For export steps and viewer guidance, see Export execution profiles.

Execution Profile Model

The Rust crate exports one immutable execution-profile model for bounded previews, one-output SQL Server writes, and selected write_all cache aliases. This foundation also supplies the reusable terminal consumer and bounded tracing summary. It does not by itself expose a profile option or attach the immutable result to an operation report. Individual operation APIs own that integration; the model itself does not change query execution.

ExecutionProfileMode defaults to Disabled. Its other value is Detailed. The stable JSON spellings used by the remaining enums are:

The public Rust model uses typed values and read-only accessors. JSON is an explicit projection of that model, not its in-memory source of truth.

Profile Schema

{
  "scope": "preview",
  "outcome": "success",
  "partial": false,
  "delta_funnel_row_limit": 20,
  "operators": [
    {
      "node_id": 0,
      "parent_node_id": null,
      "operator_name": "GlobalLimitExec",
      "output_partition_count": 1,
      "metrics_available": true,
      "aggregated_metrics": [],
      "metrics": [],
      "delta_provider_read_stats": null
    }
  ]
}

partial is derived from outcome: it is false only for success. delta_funnel_row_limit is the exact Delta Funnel preview limit, converted to an unsigned 64-bit value with saturation. It is null for both write scopes. A successful limited preview means the limited execution completed normally; it does not describe an unbounded write.

Operators are the unique physical-plan nodes in deterministic first-seen pre-order. IDs start at zero and are local to one profile. The root parent is null. Repeated references to the exact same Arc<dyn ExecutionPlan> keep the first node and first parent, while distinct nodes remain separate even when their names and metadata match. operator_name is only DataFusion's short ExecutionPlan::name() value. Plan display text is never collected.

metrics_available=false means DataFusion returned no metric set. An available but empty set uses metrics_available=true with two empty metric arrays. Every operator, including a zero-output-partition root, remains in the profile.

Raw and Aggregated Metrics

Each operator has two views of the same terminal DataFusion metric set:

• metrics preserves original per-partition entries.
• aggregated_metrics uses DataFusion's aggregate_by_name() result and therefore sets partition and output_partition to null.

Both arrays are sorted by category, name, partition, output partition, value kind, and typed value. Original metric position is used only to order otherwise identical redacted entries. Collection reads each node's metric set once and does not execute or poll the plan.

DataFusion operator metrics are cumulative counters and gauges. Partitions and operators can execute concurrently, and parent and child work can overlap. Do not sum operator compute durations and call the result query wall time. The profile does not derive wall-time percentages.

Each metric has this envelope:

{
  "name": "output_rows",
  "category": "summary",
  "partition": 0,
  "output_partition": null,
  "value_kind": "count",
  "value": 42,
  "components": null
}

DataFusion 54.1 values map as follows:

All non-timestamp usize conversions saturate to u64. A numeric zero is an available measured value. Unavailable metrics use the relevant absence signal, such as metrics_available=false, a null optional provider field, or a null unset or out-of-range timestamp. Current memory is a terminal gauge, not a promised peak. Ratios preserve their two integer components and are not converted to floating-point percentages. Custom display text is not exposed.

Labels and Redaction

The collector recognizes only an exact outputPartition label whose value is a base-10 non-negative integer that fits in u64. It normalizes that value to output_partition. Malformed values and every other label are dropped, including filename, expr, and unknown future labels.

Profiles never include plan display text, expressions, SQL, schemas, literals, URLs, paths, storage options, headers, credentials, or custom metric display text. These redaction rules apply to both JSON and Rust Debug output.

Delta Provider Snapshots

A DeltaDataFusionExec operator can contain a canonical delta_arrow_reader::DeltaDataFusionMetricsSnapshot under delta_provider_read_stats. The profile flattens that snapshot through the established provider JSON mapping, so provider fields keep their existing names and availability semantics. Rust callers read the separately retained source name through delta_provider_source_name().

Terminal consumers associate snapshots by exact shared metrics identity, not source name, plan-node identity, or snapshot contents. They reuse the immutable snapshot captured at the shared terminal transition and do not take a later live snapshot. A scan missing from a supplied terminal set gets null provider stats and an internal redacted diagnostic. A supplied snapshot with no matching scan is ignored. The standalone internal collector can instead snapshot each unique handle once when no terminal set is supplied.

This model is application-level query profiling. It does not collect syscall, CPU stack, scheduler, Tokio, network-packet, perf, eBPF, or kernel profiles, and it does not run EXPLAIN ANALYZE or execute the query a second time.