Skip to content

DOC-223: clarify EXPLAIN ANALYZE executes statements #23119

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

Open
rmloveland wants to merge 1 commit into
base: main
Choose a base branch
from
Open

DOC-223: clarify EXPLAIN ANALYZE executes statements #23119

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
12 changes: 10 additions & 2 deletions src/current/v26.2/explain-analyze.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,12 @@ docs_area: reference.sql

The `EXPLAIN ANALYZE` [statement]({% link {{ page.version.version }}/sql-statements.md %}) **executes a SQL query** and generates a statement plan with execution statistics. Statement plans provide information around SQL execution, which can be used to troubleshoot slow queries by figuring out where time is being spent, how long a processor (i.e., a component that takes streams of input rows and processes them according to a specification) is not doing work, etc. The `(DISTSQL)` option returns the statement plan and performance statistics as well as a generated link to a graphical distributed SQL physical statement plan tree. For more information about distributed SQL queries, see the [DistSQL section of our SQL layer architecture docs]({% link {{ page.version.version }}/architecture/sql-layer.md %}#distsql). The `(DEBUG)` option generates a URL to download a bundle with more details about the statement plan for advanced debugging.

{{site.data.alerts.callout_info}}
{% include {{ page.version.version }}/sql/physical-plan-url.md %}
{{site.data.alerts.callout_danger}}
`EXPLAIN ANALYZE` executes the target statement and may modify or delete data. It is not a dry run.

If you use `EXPLAIN ANALYZE` with a statement that changes data or acquires locks, those effects occur when the statement runs. For example, `EXPLAIN ANALYZE DELETE FROM t WHERE id = 1;` **deletes matching rows** and then reports execution statistics.

To inspect a statement plan without executing the statement, use [`EXPLAIN`]({% link {{ page.version.version }}/explain.md %}) instead. For example, `EXPLAIN DELETE FROM t WHERE id = 1;` shows the plan without deleting data.
{{site.data.alerts.end}}

## Aliases
Expand Down Expand Up @@ -165,6 +169,10 @@ unordered / ordered | _(Blue box)_ A synchronizer that takes one or more output
<data type> | If you specify [`EXPLAIN (DISTSQL, TYPES)`]({% link {{ page.version.version }}/explain.md %}#distsql-option), lists the data types of the input columns. | Both
Response | The response back to the client. | Both

{{site.data.alerts.callout_info}}
{% include {{ page.version.version }}/sql/physical-plan-url.md %}
{{site.data.alerts.end}}

## `DEBUG` option

`EXPLAIN ANALYZE (DEBUG)` executes a query and generates a link to a ZIP file that contains the [physical statement plan](#distsql-plan-diagram), execution statistics, statement tracing, and other information about the query.
Expand Down
Loading