You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datafusion.apache.org by gi...@apache.org on 2026/05/28 21:33:23 UTC
(datafusion) branch asf-site updated: Publish built docs triggered by d5643aed9e1e009452be6ce8dea91cdcc86488b2
This is an automated email from the ASF dual-hosted git repository.
github-actions[bot] pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 381299e594 Publish built docs triggered by d5643aed9e1e009452be6ce8dea91cdcc86488b2
381299e594 is described below
commit 381299e594181262511573520c98210b5a14ef88
Author: github-actions[bot] <gi...@users.noreply.github.com>
AuthorDate: Thu May 28 21:33:18 2026 +0000
Publish built docs triggered by d5643aed9e1e009452be6ce8dea91cdcc86488b2
---
_sources/user-guide/explain-usage.md.txt | 40 +++++++++++++++++++
searchindex.js | 2 +-
user-guide/explain-usage.html | 67 ++++++++++++++++++++++++++++++++
3 files changed, 108 insertions(+), 1 deletion(-)
diff --git a/_sources/user-guide/explain-usage.md.txt b/_sources/user-guide/explain-usage.md.txt
index 9e06acbce4..0f3f008c52 100644
--- a/_sources/user-guide/explain-usage.md.txt
+++ b/_sources/user-guide/explain-usage.md.txt
@@ -241,6 +241,46 @@ When predicate pushdown is enabled, `DataSourceExec` with `ParquetSource` gains
- `row_pushdown_eval_time`: time spent evaluating row-level filters
- `page_index_eval_time`: time required to evaluate the page index filters
+## Postgres-style `EXPLAIN (...)` options
+
+In addition to the legacy keyword form (`EXPLAIN ANALYZE VERBOSE FORMAT tree SELECT ...`),
+DataFusion accepts a Postgres-style option list on dialects whose
+[`supports_explain_with_utility_options`](https://docs.rs/sqlparser/latest/sqlparser/dialect/trait.Dialect.html#method.supports_explain_with_utility_options)
+returns `true`. This includes the default `GenericDialect`, `PostgreSqlDialect`, and
+`DuckDbDialect`, among others.
+
+```sql
+EXPLAIN (ANALYZE, VERBOSE, METRICS 'rows,bytes', LEVEL dev)
+SELECT ... ;
+```
+
+The recognized options are:
+
+| Option | Argument | Effect |
+| --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `ANALYZE` | boolean, optional | Execute the plan and collect metrics. Defaults to `TRUE` when bare. Equivalent to the `ANALYZE` keyword. |
+| `VERBOSE` | boolean, optional | Show per-partition metrics and additional detail. Equivalent to the `VERBOSE` keyword. |
+| `FORMAT` | identifier/string | One of `indent`, `tree`, `pgjson`, `graphviz`. Equivalent to the `FORMAT <format>` clause. |
+| `METRICS` | string | Filter `ANALYZE` metrics by category. Accepts `'all'`, `'none'`, or any comma-separated subset of `rows,bytes,timing,uncategorized`. |
+| `LEVEL` | identifier/string | `summary` or `dev`. Controls metric verbosity for `ANALYZE`. |
+| `TIMING` | boolean | Sugar over `METRICS`: toggles inclusion of the `timing` category. |
+| `SUMMARY` | boolean | Sugar over `LEVEL`: `TRUE` → `summary`, `FALSE` → `dev`. |
+| `COSTS` | boolean | Include statistics in plain `EXPLAIN` output (equivalent to `SET datafusion.explain.show_statistics`). Not valid with `ANALYZE`. |
+
+Boolean arguments can be written bare (`ANALYZE` → `true`), as `TRUE`/`FALSE`,
+`ON`/`OFF`, or `0`/`1`.
+
+The statement-level options take precedence over session config, so you can leave
+the session defaults alone and override just for the current query:
+
+```sql
+EXPLAIN (ANALYZE, LEVEL dev, METRICS 'rows,bytes') SELECT ...;
+```
+
+Postgres options that DataFusion does not model (`BUFFERS`, `WAL`, `SETTINGS`,
+`GENERIC_PLAN`, `MEMORY`) return a clear error rather than being silently
+accepted — use `METRICS` to filter what appears in the output.
+
## Partitions and Execution
DataFusion determines the optimal number of cores to use as part of query
diff --git a/searchindex.js b/searchindex.js
index 42767edc73..3fc3398273 100644
--- a/searchindex.js
+++ b/searchindex.js
@@ -1 +1 @@
-Search.setIndex({"alltitles":{"!=":[[74,"op-neq"]],"!~":[[74,"op-re-not-match"]],"!~*":[[74,"op-re-not-match-i"]],"!~~":[[74,"id19"]],"!~~*":[[74,"id20"]],"#":[[74,"op-bit-xor"]],"%":[[74,"op-modulo"]],"&":[[74,"op-bit-and"]],"(relation, name) tuples in logical fields and logical columns are unique":[[15,"relation-name-tuples-in-logical-fields-and-logical-columns-are-unique"]],"*":[[74,"op-multiply"]],"+":[[74,"op-plus"]],"-":[[74,"op-minus"]],"/":[[74,"op-divide"]],"1. Array Literal Con [...]
\ No newline at end of file
+Search.setIndex({"alltitles":{"!=":[[74,"op-neq"]],"!~":[[74,"op-re-not-match"]],"!~*":[[74,"op-re-not-match-i"]],"!~~":[[74,"id19"]],"!~~*":[[74,"id20"]],"#":[[74,"op-bit-xor"]],"%":[[74,"op-modulo"]],"&":[[74,"op-bit-and"]],"(relation, name) tuples in logical fields and logical columns are unique":[[15,"relation-name-tuples-in-logical-fields-and-logical-columns-are-unique"]],"*":[[74,"op-multiply"]],"+":[[74,"op-plus"]],"-":[[74,"op-minus"]],"/":[[74,"op-divide"]],"1. Array Literal Con [...]
\ No newline at end of file
diff --git a/user-guide/explain-usage.html b/user-guide/explain-usage.html
index 50dced0718..4c4ad69b04 100644
--- a/user-guide/explain-usage.html
+++ b/user-guide/explain-usage.html
@@ -654,6 +654,72 @@ by all 16 cores.</p>
<li><p><code class="docutils literal notranslate"><span class="pre">page_index_eval_time</span></code>: time required to evaluate the page index filters</p></li>
</ul>
</section>
+<section id="postgres-style-explain-options">
+<h2>Postgres-style <code class="docutils literal notranslate"><span class="pre">EXPLAIN</span> <span class="pre">(...)</span></code> options<a class="headerlink" href="#postgres-style-explain-options" title="Link to this heading">#</a></h2>
+<p>In addition to the legacy keyword form (<code class="docutils literal notranslate"><span class="pre">EXPLAIN</span> <span class="pre">ANALYZE</span> <span class="pre">VERBOSE</span> <span class="pre">FORMAT</span> <span class="pre">tree</span> <span class="pre">SELECT</span> <span class="pre">...</span></code>),
+DataFusion accepts a Postgres-style option list on dialects whose
+<a class="reference external" href="https://docs.rs/sqlparser/latest/sqlparser/dialect/trait.Dialect.html#method.supports_explain_with_utility_options"><code class="docutils literal notranslate"><span class="pre">supports_explain_with_utility_options</span></code></a>
+returns <code class="docutils literal notranslate"><span class="pre">true</span></code>. This includes the default <code class="docutils literal notranslate"><span class="pre">GenericDialect</span></code>, <code class="docutils literal notranslate"><span class="pre">PostgreSqlDialect</span></code>, and
+<code class="docutils literal notranslate"><span class="pre">DuckDbDialect</span></code>, among others.</p>
+<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">EXPLAIN</span><span class="w"> </span><span class="p">(</span><span class="k">ANALYZE</span><span class="p">,</span><span class="w"> </span><span class="k">VERBOSE</span><span class="p">,</span><span class="w"> </span><span class="n">METRICS</span><span class="w"> </span><span class="s1">'rows,bytes'</span><span class="p">,</span><span class="w"> </span><span class="k">LEVEL</span><spa [...]
+<span class="k">SELECT</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The recognized options are:</p>
+<div class="pst-scrollable-table-container"><table class="table">
+<thead>
+<tr class="row-odd"><th class="head"><p>Option</p></th>
+<th class="head"><p>Argument</p></th>
+<th class="head"><p>Effect</p></th>
+</tr>
+</thead>
+<tbody>
+<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ANALYZE</span></code></p></td>
+<td><p>boolean, optional</p></td>
+<td><p>Execute the plan and collect metrics. Defaults to <code class="docutils literal notranslate"><span class="pre">TRUE</span></code> when bare. Equivalent to the <code class="docutils literal notranslate"><span class="pre">ANALYZE</span></code> keyword.</p></td>
+</tr>
+<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">VERBOSE</span></code></p></td>
+<td><p>boolean, optional</p></td>
+<td><p>Show per-partition metrics and additional detail. Equivalent to the <code class="docutils literal notranslate"><span class="pre">VERBOSE</span></code> keyword.</p></td>
+</tr>
+<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">FORMAT</span></code></p></td>
+<td><p>identifier/string</p></td>
+<td><p>One of <code class="docutils literal notranslate"><span class="pre">indent</span></code>, <code class="docutils literal notranslate"><span class="pre">tree</span></code>, <code class="docutils literal notranslate"><span class="pre">pgjson</span></code>, <code class="docutils literal notranslate"><span class="pre">graphviz</span></code>. Equivalent to the <code class="docutils literal notranslate"><span class="pre">FORMAT</span> <span class="pre"><format></span></code> clause [...]
+</tr>
+<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">METRICS</span></code></p></td>
+<td><p>string</p></td>
+<td><p>Filter <code class="docutils literal notranslate"><span class="pre">ANALYZE</span></code> metrics by category. Accepts <code class="docutils literal notranslate"><span class="pre">'all'</span></code>, <code class="docutils literal notranslate"><span class="pre">'none'</span></code>, or any comma-separated subset of <code class="docutils literal notranslate"><span class="pre">rows,bytes,timing,uncategorized</span></code>.</p></td>
+</tr>
+<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">LEVEL</span></code></p></td>
+<td><p>identifier/string</p></td>
+<td><p><code class="docutils literal notranslate"><span class="pre">summary</span></code> or <code class="docutils literal notranslate"><span class="pre">dev</span></code>. Controls metric verbosity for <code class="docutils literal notranslate"><span class="pre">ANALYZE</span></code>.</p></td>
+</tr>
+<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">TIMING</span></code></p></td>
+<td><p>boolean</p></td>
+<td><p>Sugar over <code class="docutils literal notranslate"><span class="pre">METRICS</span></code>: toggles inclusion of the <code class="docutils literal notranslate"><span class="pre">timing</span></code> category.</p></td>
+</tr>
+<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">SUMMARY</span></code></p></td>
+<td><p>boolean</p></td>
+<td><p>Sugar over <code class="docutils literal notranslate"><span class="pre">LEVEL</span></code>: <code class="docutils literal notranslate"><span class="pre">TRUE</span></code> → <code class="docutils literal notranslate"><span class="pre">summary</span></code>, <code class="docutils literal notranslate"><span class="pre">FALSE</span></code> → <code class="docutils literal notranslate"><span class="pre">dev</span></code>.</p></td>
+</tr>
+<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">COSTS</span></code></p></td>
+<td><p>boolean</p></td>
+<td><p>Include statistics in plain <code class="docutils literal notranslate"><span class="pre">EXPLAIN</span></code> output (equivalent to <code class="docutils literal notranslate"><span class="pre">SET</span> <span class="pre">datafusion.explain.show_statistics</span></code>). Not valid with <code class="docutils literal notranslate"><span class="pre">ANALYZE</span></code>.</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<p>Boolean arguments can be written bare (<code class="docutils literal notranslate"><span class="pre">ANALYZE</span></code> → <code class="docutils literal notranslate"><span class="pre">true</span></code>), as <code class="docutils literal notranslate"><span class="pre">TRUE</span></code>/<code class="docutils literal notranslate"><span class="pre">FALSE</span></code>,
+<code class="docutils literal notranslate"><span class="pre">ON</span></code>/<code class="docutils literal notranslate"><span class="pre">OFF</span></code>, or <code class="docutils literal notranslate"><span class="pre">0</span></code>/<code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
+<p>The statement-level options take precedence over session config, so you can leave
+the session defaults alone and override just for the current query:</p>
+<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">EXPLAIN</span><span class="w"> </span><span class="p">(</span><span class="k">ANALYZE</span><span class="p">,</span><span class="w"> </span><span class="k">LEVEL</span><span class="w"> </span><span class="n">dev</span><span class="p">,</span><span class="w"> </span><span class="n">METRICS</span><span class="w"> </span><span class="s1">'rows,bytes'</span><span class="p">)</span><span cl [...]
+</pre></div>
+</div>
+<p>Postgres options that DataFusion does not model (<code class="docutils literal notranslate"><span class="pre">BUFFERS</span></code>, <code class="docutils literal notranslate"><span class="pre">WAL</span></code>, <code class="docutils literal notranslate"><span class="pre">SETTINGS</span></code>,
+<code class="docutils literal notranslate"><span class="pre">GENERIC_PLAN</span></code>, <code class="docutils literal notranslate"><span class="pre">MEMORY</span></code>) return a clear error rather than being silently
+accepted — use <code class="docutils literal notranslate"><span class="pre">METRICS</span></code> to filter what appears in the output.</p>
+</section>
<section id="partitions-and-execution">
<h2>Partitions and Execution<a class="headerlink" href="#partitions-and-execution" title="Link to this heading">#</a></h2>
<p>DataFusion determines the optimal number of cores to use as part of query
@@ -867,6 +933,7 @@ Elapsed<span class="w"> </span><span class="m">0</span>.062<span class="w"> </sp
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#understanding-large-query-plans">Understanding large query plans</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#more-debugging-information-explain-verbose">More Debugging Information: <code class="docutils literal notranslate"><span class="pre">EXPLAIN</span> <span class="pre">VERBOSE</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#execution-counters-explain-analyze">Execution Counters: <code class="docutils literal notranslate"><span class="pre">EXPLAIN</span> <span class="pre">ANALYZE</span></code></a></li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#postgres-style-explain-options">Postgres-style <code class="docutils literal notranslate"><span class="pre">EXPLAIN</span> <span class="pre">(...)</span></code> options</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#partitions-and-execution">Partitions and Execution</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#example-of-an-aggregate-query">Example of an Aggregate Query</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#data-in-this-example">Data in this Example</a></li>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org