Skip to main content
The EXPLAIN ANALYZE 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 . The (DEBUG) option generates a URL to download a bundle with more details about the statement plan for advanced debugging.
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 instead. For example, EXPLAIN DELETE FROM t WHERE id = 1; shows the plan without deleting data.

Aliases

EXPLAIN ANALYSE is an alias for EXPLAIN ANALYZE.

Synopsis

explain_analyze syntax diagram

Parameters

Required privileges

To generate a statement bundle, you must have the to execute the SQL statement, as well as the privileges required to collect the statement bundle. To find the minimum required privileges for a SQL statement, refer to the for the statement. A user with the VIEWACTIVITY can generate a bundle for any statement. To grant this privilege, issue the following SQL commands. Replace with the user’s ID.

Success responses

A successful EXPLAIN ANALYZE statement returns a table with the following details in the info column: If you use the DISTSQL option, the statement will also return a URL generated for a physical statement plan that provides high level information about how a statement will be executed. The generated physical statement plan is encoded into a byte string after the fragment identifier (#) in the generated URL. The fragment is not sent to the web server; instead, the browser waits for the web server to return a decode.html resource, and then JavaScript on the web page decodes the fragment into a physical statement plan diagram. The statement plan is, therefore, not logged by a server external to the CockroachDB cluster and not exposed to the public internet. For details about reading the physical statement plan, see DistSQL plan diagram. If you use the DEBUG option, the statement will return only a URL and instructions to download the DEBUG bundle, which includes the physical statement plan.

Global properties

Statement plan tree properties

PLAN option

By default, EXPLAIN ANALYZE uses the PLAN option. EXPLAIN ANALYZE and EXPLAIN ANALYZE (PLAN) produce the same output.

PLAN suboptions

The PLAN suboptions VERBOSE and TYPES described in are also supported. For an example, see EXPLAIN ANALYZE (VERBOSE).

DISTSQL option

EXPLAIN ANALYZE (DISTSQL) generates a physical statement in the plan diagram. The DistSQL plan diagram displays the physical statement plan, as well as execution statistics. The statistics listed depend on the query type and the . If the query contains subqueries or post-queries there will be multiple diagrams.
You can use EXPLAIN ANALYZE (DISTSQL) only as the top-level statement in a query.

DistSQL plan diagram

The graphical plan diagram displays the processors and operations that make up the statement plan. While the text output from the PLAN option shows the statement plan across the cluster, the DISTSQL option shows details on each node involved in the query. The generated physical statement plan is encoded into a byte string after the fragment identifier (#) in the generated URL. The fragment is not sent to the web server; instead, the browser waits for the web server to return a decode.html resource, and then JavaScript on the web page decodes the fragment into a physical statement plan diagram. The statement plan is, therefore, not logged by a server external to the CockroachDB cluster and not exposed to the public internet.

DEBUG option

EXPLAIN ANALYZE (DEBUG) executes a query and generates a link to a ZIP file that contains the physical statement plan, execution statistics, statement tracing, and other information about the query. You can obtain this ZIP file by following the link provided in the EXPLAIN ANALYZE (DEBUG) output, or by activating in the DB Console.
Statement bundles can contain unredacted user data including histograms and placeholders that contain real data samples, statements that have real data which can contain PII information, and database schema that could be sensitive. Be careful when generating and sharing statement bundles. In CockroachDB v24.3.1 and later, admin users or SQL users with the VIEWACTIVITY system privilege can choose to redact user data from the dialog. To allow or disallow a role from seeing , set the VIEWACTIVITYREDACTED . In CockroachDB v21.2.x, v22.1.0 to v22.1.16, v22.2.0 to v22.2.6, non-admin SQL users with an authenticated HTTP session could download statement diagnostic bundles given a bundle URL from the DB Console or the EXPLAIN ANALYZE (DEBUG) statement with a valid HTTP session cookie. This has been resolved in v22.1.17 and v22.2.7. For more information, see the .

REDACT option

EXPLAIN ANALYZE (REDACT) executes a query and causes constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as ‹×› in the output. You can use the REDACT flag in combination with the PLAN option (including the VERBOSE and TYPES suboptions) to redact sensitive values in the physical statement plan, and with the DEBUG option to redact values in the statement bundle. For an example, see EXPLAIN ANALYZE (REDACT).

Examples

The following examples use the . Start the on a 3-node CockroachDB demo cluster with a larger data set.

EXPLAIN ANALYZE

Use EXPLAIN ANALYZE without an option, or equivalently with the PLAN option, to execute a query and display the physical statement plan with execution statistics. For example, the following EXPLAIN ANALYZE statement executes a simple query against the and then displays the physical statement plan with execution statistics:
If you perform a join, the estimated max memory allocation is also reported for the join. For example:

EXPLAIN ANALYZE (VERBOSE)

Use the VERBOSE suboption of PLAN to execute a query and display the physical statement plan with additional execution statistics.

EXPLAIN ANALYZE (DISTSQL)

Use EXPLAIN ANALYZE (DISTSQL) to execute a query, display the physical statement plan with execution statistics, and generate a link to a graphical DistSQL statement plan.
To view the DistSQL plan diagram, open the URL following Diagram. For an example, see .

EXPLAIN ANALYZE (DEBUG)

Use the DEBUG option to generate a ZIP file containing files with information about the query and the database objects referenced in the query. For example:
To download the ZIP file containing the statement diagnostics, run the \statement-diag download or cockroach statement-diag download commands. You can also obtain the bundle by activating in the DB Console.

EXPLAIN ANALYZE (REDACT)

Use the REDACT option to execute a query and cause constants, literal values, parameter values, and personally identifiable information (PII) to be redacted as ‹×› in the physical statement plan or statement bundle.
In the preceding output, the revenue comparison value is redacted as ‹×›.

See also