Skip to content

Make tree the Default EXPLAIN Format and Reorder Documentation Sections #15706

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alamb merged 1 commit into from
Apr 14, 2025
Merged

Make tree the Default EXPLAIN Format and Reorder Documentation Sections #15706

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 33 additions & 33 deletions docs/source/user-guide/sql/explain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,39 +39,7 @@ the format from the [configuration value] `datafusion.explain.format`.

[configuration value]: ../configs.md

### `indent` format (default)

The `indent` format shows both the logical and physical plan, with one line for
each operator in the plan. Child plans are indented to show the hierarchy.

See [Reading Explain Plans](../explain-usage.md) for more information on how to interpret these plans.

```sql
> CREATE TABLE t(x int, b int) AS VALUES (1, 2), (2, 3);
0 row(s) fetched.
Elapsed 0.004 seconds.

> EXPLAIN SELECT SUM(x) FROM t GROUP BY b;
+---------------+-------------------------------------------------------------------------------+
| plan_type | plan |
+---------------+-------------------------------------------------------------------------------+
| logical_plan | Projection: sum(t.x) |
| | Aggregate: groupBy=[[t.b]], aggr=[[sum(CAST(t.x AS Int64))]] |
| | TableScan: t projection=[x, b] |
| physical_plan | ProjectionExec: expr=[sum(t.x)@1 as sum(t.x)] |
| | AggregateExec: mode=FinalPartitioned, gby=[b@0 as b], aggr=[sum(t.x)] |
| | CoalesceBatchesExec: target_batch_size=8192 |
| | RepartitionExec: partitioning=Hash([b@0], 16), input_partitions=16 |
| | RepartitionExec: partitioning=RoundRobinBatch(16), input_partitions=1 |
| | AggregateExec: mode=Partial, gby=[b@1 as b], aggr=[sum(t.x)] |
| | DataSourceExec: partitions=1, partition_sizes=[1] |
| | |
+---------------+-------------------------------------------------------------------------------+
2 row(s) fetched.
Elapsed 0.004 seconds.
```

### `tree` format
### `tree` format (default)

The `tree` format is modeled after [DuckDB plans] and is designed to be easier
to see the high level structure of the plan
Expand Down Expand Up @@ -138,6 +106,38 @@ to see the high level structure of the plan
Elapsed 0.016 seconds.
```

### `indent` format

The `indent` format shows both the logical and physical plan, with one line for
each operator in the plan. Child plans are indented to show the hierarchy.

See [Reading Explain Plans](../explain-usage.md) for more information on how to interpret these plans.

```sql
> CREATE TABLE t(x int, b int) AS VALUES (1, 2), (2, 3);
0 row(s) fetched.
Elapsed 0.004 seconds.

> EXPLAIN SELECT SUM(x) FROM t GROUP BY b;
+---------------+-------------------------------------------------------------------------------+
| plan_type | plan |
+---------------+-------------------------------------------------------------------------------+
| logical_plan | Projection: sum(t.x) |
| | Aggregate: groupBy=[[t.b]], aggr=[[sum(CAST(t.x AS Int64))]] |
| | TableScan: t projection=[x, b] |
| physical_plan | ProjectionExec: expr=[sum(t.x)@1 as sum(t.x)] |
| | AggregateExec: mode=FinalPartitioned, gby=[b@0 as b], aggr=[sum(t.x)] |
| | CoalesceBatchesExec: target_batch_size=8192 |
| | RepartitionExec: partitioning=Hash([b@0], 16), input_partitions=16 |
| | RepartitionExec: partitioning=RoundRobinBatch(16), input_partitions=1 |
| | AggregateExec: mode=Partial, gby=[b@1 as b], aggr=[sum(t.x)] |
| | DataSourceExec: partitions=1, partition_sizes=[1] |
| | |
+---------------+-------------------------------------------------------------------------------+
2 row(s) fetched.
Elapsed 0.004 seconds.
```

### `pgjson` format

The `pgjson` format is modeled after [Postgres JSON] format.
Expand Down