Show the logical or physical execution plan for a SQL statement without scanning any data.
delta-forge-cli plan [--plan-type physical|logical] [--plan-format raw|debug] [--node <name>] <SQL>...## Overview `plan` calls the streaming query API with `include_plan: true`, which makes the server compile and plan the SQL and short-circuit before any scan. The INIT frame carries `physical_plan`, `logical_plan`, optional `physical_plan_debug`, optional `logical_plan_debug`, and `generation_time_ms`. No batches are streamed and no rows are read. This is the same wire path that backs the GUI's Plan tab and `query --with-plan`. ## Behavior - The four output combinations are independent. `physical raw` (default) prints DataFusion's standard physical-plan text. `physical debug` prints the verbose Rust Debug-derive of the physical plan. `logical raw` prints the readable logical plan. `logical debug` prints the verbose Debug-derive of the logical plan. - The plan body is written to stdout so it pipes cleanly into `less`, `grep`, or a file. Status (resolved node, plan type, server-side and wall-clock generation time) goes to stderr, so redirecting stdout still gives you a clean plan. - When `--node` is passed, the display name or `entity_ref` is resolved to a compute URL via `/list-compute-nodes` and used for this request only. - Exit code: `0` on success, `1` on SQL parse / plan error or auth failure, `2` on client-initialisation failure. ## Compatibility - `query --with-plan` is the convenience form when you want both the result and its plan in one call. It runs the query normally and then issues a second `include_plan: true` call, printing the physical plan to stderr after the result table so stdout stays pipe-friendly. - `EXECPLAN` (SQL-level) and `plan` (CLI-level) overlap but are not identical. `EXECPLAN` is parsed and executed inside the SQL pipeline and returns rows containing file-skipping statistics alongside the physical plan; `plan` is callable from any client without going through SQL parsing of the `EXECPLAN` keyword and returns a structured `ExecutionPlan` object. Pick the surface that fits your workflow.
| Name | Type | Description |
|---|---|---|
SQL | One or more words joined by whitespace forming the SQL statement to plan. Positional arguments are joined with a single space before the request is sent. The query is compiled and planned, never executed, so it is safe to run on huge tables. | |
--plan-type | Plan layer to print. `physical` shows the post-optimisation operator tree that would actually run (`ProjectionExec`, `AggregateExec`, `DataSourceExec`, etc.). `logical` shows the pre-optimisation plan, useful for confirming the planner understood the SQL the way you intended. | |
--plan-format | Render style. `raw` is the standard human-readable text representation (the same format DataFusion emits and the GUI's Raw tab shows). `debug` is the verbose `{:#?}` Rust Debug-derive printout matching the GUI's Debug tab; use it when Raw is silent on the question you are asking, for example to inspect predicate-pushdown internals or projection masks. | |
--node | Compute node display name or `entity_ref`. Resolved against the control plane's `/list-compute-nodes` endpoint and pins the plan request to that node for this invocation. Overrides the global `--node` flag. |
# Default: physical raw plan to stdout
delta-forge-cli plan SELECT count(*) FROM sales.orders WHERE status='shipped'# Logical plan in verbose Debug format
delta-forge-cli plan --plan-type logical --plan-format debug SELECT * FROM sales.orders WHERE region='EU'# Pin to a specific worker, capture plan to a file
delta-forge-cli plan --node prod-worker-01 SELECT * FROM analytics.daily_revenue >plan.txt# Run the query AND print the physical plan after the result table
delta-forge-cli query --with-plan SELECT count(*) FROM sales.orders