Skip to content

identify all statements that can be EXPLAINed #2682

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
merged 4 commits into from
Mar 12, 2018
Merged

identify all statements that can be EXPLAINed #2682

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
484fdbe
identify all statements that can be EXPLAINed
Mar 8, 2018
158170c
added links to all explainable statements
Mar 9, 2018
f326652
minor edits
Mar 9, 2018
f4ef58e
minor updates
Mar 12, 2018
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
24 changes: 21 additions & 3 deletions v1.0/explain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,23 @@ summary: The EXPLAIN statement provides information you can use to optimize SQL
toc: false
---

The `EXPLAIN` [statement](sql-statements.html) returns CockroachDB's query plan to execute [`DELETE`](delete.html), [`INSERT`](insert.html), [`SELECT`](select.html) or [`UPDATE`](update.html) statements. You can then use this information to optimize those queries.
The `EXPLAIN` [statement](sql-statements.html) returns CockroachDB's query plan for an [explainable statement](#explainable-statements). You can then use this information to optimize the query.

<div id="toc"></div>

## Explainable Statements

You can use `EXPLAIN` on the following statements:

- [`ALTER TABLE`](alter-table.html)
- [`CREATE DATABASE`](create-database.html), [`CREATE INDEX`](create-index.html), [`CREATE TABLE`](create-table.html), [`CREATE TABLE AS`](create-table-as.html), [`CREATE USER`](create-user.html), [`CREATE VIEW`](create-view.html)
- [`DELETE`](delete.html)
- `EXPLAIN`
- [`INSERT`](insert.html)
- [`SELECT`](select.html)
- [`SHOW COLUMNS`](show-columns.html), [`SHOW CONSTRAINTS`](show-constraints.html), [`SHOW CREATE TABLE`](show-create-table.html), [`SHOW CREATE VIEW`](show-create-view.html), [`SHOW CLUSTER SETTING`](show-cluster-setting.html), [`SHOW DATABASES`](show-databases.html), [`SHOW GRANTS`](show-grants.html), [`SHOW INDEX`](show-index.html), [`SHOW TABLES`](show-tables.html), [`SHOW USERS`](show-users.html)
- [`UPDATE`](update.html)

## Query Optimization

Using `EXPLAIN`'s output, you can optimize your queries by taking the following points into consideration:
Expand Down Expand Up @@ -41,7 +54,7 @@ The user requires the appropriate [privileges](privileges.html) for the statemen
| `METADATA` | Include the columns each level uses in the **Columns** column, as well as **Ordering** detail. |
| `VERBOSE` | Imply the `EXPRS`, `METADATA`, and `QUALIFY` options. |
| `TYPES` | Include the intermediate [data types](data-types.html) CockroachDB chooses to evaluate intermediate SQL expressions. <br/><br/>`TYPES` also implies `METADATA` and `EXPRS` options.|
| `explainable_stmt` | The [`DELETE`](delete.html), [`INSERT`](insert.html), [`SELECT`](select.html) or [`UPDATE`](update.html) statement you want detail about. |
| `explainable_stmt` | The [statement](#explainable-statements) you want details about. |

{{site.data.alerts.callout_danger}}<code>EXPLAIN</code> also includes other modes besides query plans that are useful only to CockroachDB developers, which are not documented here.{{site.data.alerts.end}}

Expand Down Expand Up @@ -270,8 +283,13 @@ However, in the following query, column `k` is sorted in the `primary` index, so

## See Also

- [Indexes](indexes.html)
- [`ALTER TABLE`](alter-table.html)
- [`CREATE DATABASE`](create-database.html)
- [`CREATE TABLE`](create-table.html)
- [`DELETE`](delete.html)
- [Indexes](indexes.html)
- [`INSERT`](insert.html)
- [`SELECT`](select.html)
- [`SHOW CONSTRAINTS`](show-constraints.html)
- [`SHOW CREATE TABLE`](show-create-table.html)
- [`UPDATE`](update.html)
49 changes: 46 additions & 3 deletions v1.1/explain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,34 @@ summary: The EXPLAIN statement provides information you can use to optimize SQL
toc: false
---

The `EXPLAIN` [statement](sql-statements.html) returns CockroachDB's query plan to execute [`DELETE`](delete.html), [`INSERT`](insert.html), [`SELECT`](select.html) or [`UPDATE`](update.html) statements. You can then use this information to optimize those queries.
The `EXPLAIN` [statement](sql-statements.html) returns CockroachDB's query plan for an [explainable statement](#explainable-statements). You can then use this information to optimize the query.

<div id="toc"></div>

## Explainable Statements

You can `EXPLAIN` on the following statements:

- [`ALTER TABLE`](alter-table.html), [`ALTER INDEX`](alter-index.html), [`ALTER VIEW`](alter-view.html), [`ALTER DATABASE`](alter-database.html)
- [`BACKUP`](backup.html)
- [`CANCEL JOB`](cancel-job.html), [`CANCEL QUERY`](cancel-query.html)
- [`CREATE DATABASE`](create-database.html), [`CREATE INDEX`](create-index.html), [`CREATE TABLE`](create-table.html), [`CREATE TABLE AS`](create-table-as.html), [`CREATE USER`](create-user.html), [`CREATE VIEW`](create-view.html)
- [`DELETE`](delete.html)
- [`DROP DATABASE`](drop-database.html), [`DROP INDEX`](drop-index.html), [`DROP TABLE`](drop-table.html), [`DROP VIEW`](drop-view.html), [`DROP USER`](drop-user.html)
- [`EXECUTE`](sql-grammar.html#execute_stmt)
- `EXPLAIN`
- [`IMPORT`](import.html)
- [`PAUSE JOB`](pause-job.html)
- [`RESET SESSION`](reset-vars.html), [`RESET CLUSTER SETTINGS`](reset-cluster-setting.html)
- [`RESTORE`](restore.html)
- [`RESUME JOB`](resume-job.html)
- [`SELECT`](select.html)
- [`SET SESSION`](set-vars.html)
- [`SET CLUSTER SETTING`](set-cluster-setting.html)
- [`SHOW BACKUP`](show-backup.html), [`SHOW COLUMNS`](show-columns.html), [`SHOW CONSTRAINTS`](show-constraints.html), [`SHOW CREATE TABLE`](show-create-table.html), [`SHOW CREATE VIEW`](show-create-view.html), [`SHOW CLUSTER SETTING`](show-cluster-setting.html), [`SHOW DATABASES`](show-databases.html), [`SHOW GRANTS`](show-grants.html), [`SHOW INDEX`](show-index.html), [`SHOW JOBS`](show-jobs.html), [`SHOW QUERIES`](show-queries.html), [`SHOW SESSIONS`](show-sessions.html), [`SHOW TABLES`](show-tables.html), [`SHOW TRACE`](show-trace.html), [`SHOW USERS`](show-users.html)
- [`UPDATE`](update.html)
- [`UPSERT`](upsert.html)

## Query Optimization

Using `EXPLAIN`'s output, you can optimize your queries by taking the following points into consideration:
Expand Down Expand Up @@ -41,7 +65,7 @@ The user requires the appropriate [privileges](privileges.html) for the statemen
| `METADATA` | Include the columns each level uses in the **Columns** column, as well as **Ordering** detail. |
| `VERBOSE` | Imply the `EXPRS`, `METADATA`, and `QUALIFY` options. |
| `TYPES` | Include the intermediate [data types](data-types.html) CockroachDB chooses to evaluate intermediate SQL expressions. <br/><br/>`TYPES` also implies `METADATA` and `EXPRS` options.|
| `explainable_stmt` | The [`DELETE`](delete.html), [`INSERT`](insert.html), [`SELECT`](select.html) or [`UPDATE`](update.html) statement you want detail about. |
| `explainable_stmt` | The [statement](#explainable-statements) you want details about. |

{{site.data.alerts.callout_danger}}<code>EXPLAIN</code> also includes other modes besides query plans that are useful only to CockroachDB developers, which are not documented here.{{site.data.alerts.end}}

Expand Down Expand Up @@ -270,8 +294,27 @@ However, in the following query, column `k` is sorted in the `primary` index, so

## See Also

- [Indexes](indexes.html)
- [`ALTER TABLE`](alter-table.html)
- [`BACKUP`](backup.html)
- [`CANCEL JOB`](cancel-job.html)
- [`CANCEL QUERY`](cancel-query.html)
- [`CREATE DATABASE`](create-database.html)
- [`CREATE TABLE`](create-table.html)
- [`DELETE`](delete.html)
- [`DROP DATABASE`](drop-database.html)
- [`EXECUTE`](sql-grammar.html#execute_stmt)
- [Indexes](indexes.html)
- [`INSERT`](insert.html)
- [`IMPORT`](import.html)
- [`PAUSE JOB`](pause-job.html)
- [`RESET SESSION`](reset-vars.html)
- [`RESET CLUSTER SETTINGS`](reset-cluster-setting.html)
- [`RESTORE`](restore.html)
- [`RESUME JOB`](resume-job.html)
- [`SELECT`](select.html)
- [`SET SESSION`](set-vars.html)
- [`SET CLUSTER SETTING`](set-cluster-setting.html)
- [`SHOW CONSTRAINTS`](show-constraints.html)
- [`SHOW CREATE TABLE`](show-create-table.html)
- [`UPDATE`](update.html)
- [`UPSERT`](upsert.html)
48 changes: 44 additions & 4 deletions v2.0/explain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,35 @@ summary: The EXPLAIN statement provides information you can use to optimize SQL
toc: false
---

The `EXPLAIN` [statement](sql-statements.html) returns CockroachDB's query plan to execute [`DELETE`](delete.html), [`INSERT`](insert.html), [`SELECT`](select.html) or [`UPDATE`](update.html) statements. You can then use this information to optimize those queries.
The `EXPLAIN` [statement](sql-statements.html) returns CockroachDB's query plan for an [explainable statement](#explainable-statements). You can then use this information to optimize the query.

<div id="toc"></div>

## Explainable Statements

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's us an intro sentence like you have in the 1.1 version of the page:

You can use EXPLAIN on the following statements:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

You can `EXPLAIN` on the following statements:

- [`ALTER USER`](sql-grammar.html#alter_user_stmt), [`ALTER TABLE`](alter-table.html), [`ALTER INDEX`](alter-index.html), [`ALTER VIEW`](alter-view.html), [`ALTER DATABASE`](alter-database.html), [`ALTER SEQUENCE`](alter-sequence.html)
- [`BACKUP`](backup.html)
- [`CANCEL JOB`](cancel-job.html), [`CANCEL QUERY`](cancel-query.html)
- [`CREATE DATABASE`](create-database.html), [`CREATE INDEX`](create-index.html), [`CREATE TABLE`](create-table.html), [`CREATE TABLE AS`](create-table-as.html), [`CREATE USER`](create-user.html), [`CREATE VIEW`](create-view.html), [`CREATE SEQUENCE`](create-sequence.html)
- [`DELETE`](delete.html)
- [`DROP DATABASE`](drop-database.html), [`DROP INDEX`](drop-index.html), [`DROP SEQUENCE`](drop-sequence.html), [`DROP TABLE`](drop-table.html), [`DROP USER`](drop-user.html), [`DROP VIEW`](drop-view.html)
- [`EXECUTE`](sql-grammar.html#execute_stmt)
- `EXPLAIN`
- [`IMPORT`](import.html)
- [`INSERT`](insert.html)
- [`PAUSE JOB`](pause-job.html)
- [`RESET`](reset-vars.html)
- [`RESTORE`](restore.html)
- [`RESUME JOB`](resume-job.html)
- [`SELECT`](select.html)
- [`SET`](set-vars.html)
- [`SET CLUSTER SETTING`](set-cluster-setting.html)
- [`SHOW BACKUP`](show-backup.html), [`SHOW COLUMNS`](show-columns.html), [`SHOW CONSTRAINTS`](show-constraints.html), [`SHOW CREATE TABLE`](show-create-table.html), [`SHOW CREATE VIEW`](show-create-view.html), [`SHOW CREATE SEQUENCE`](show-create-sequence.html), [`SHOW CLUSTER SETTING`](show-cluster-setting.html), [`SHOW DATABASES`](show-databases.html), [`SHOW GRANTS`](show-grants.html), [`SHOW INDEX`](show-index.html), [`SHOW JOBS`](show-jobs.html), [`SHOW QUERIES`](show-queries.html), [`SHOW SESSIONS`](show-sessions.html), [`SHOW TABLES`](show-tables.html), [`SHOW TRACE`](show-trace.html), [`SHOW USERS`](show-users.html), [`SHOW HISTOGRAM`](sql-grammar.html#show_histogram_stmt)
- [`UPDATE`](update.html)
- [`UPSERT`](upsert.html)

## Query Optimization

Using `EXPLAIN`'s output, you can optimize your queries by taking the following points into consideration:
Expand All @@ -26,7 +51,7 @@ For more information, see [Find the Indexes and Key Ranges a Query Uses](#find-t

## Synopsis

{% include sql/{{ page.version.version }}/diagrams/explain.html %}
<section>{% include sql/{{ page.version.version }}/diagrams/explain.html %}</section>

## Required Privileges

Expand All @@ -41,7 +66,7 @@ The user requires the appropriate [privileges](privileges.html) for the statemen
| `METADATA` | Include the columns each level uses in the **Columns** column, as well as **Ordering** detail. |
| `VERBOSE` | Imply the `EXPRS`, `METADATA`, and `QUALIFY` options. |
| `TYPES` | Include the intermediate [data types](data-types.html) CockroachDB chooses to evaluate intermediate SQL expressions. <br/><br/>`TYPES` also implies `METADATA` and `EXPRS` options.|
| `explainable_stmt` | The [`DELETE`](delete.html), [`INSERT`](insert.html), [`SELECT`](select.html) or [`UPDATE`](update.html) statement you want detail about. |
| `explainable_stmt` | The [statement](#explainable-statements) you want details about. |

{{site.data.alerts.callout_danger}}<code>EXPLAIN</code> also includes other modes besides query plans that are useful only to CockroachDB developers, which are not documented here.{{site.data.alerts.end}}

Expand Down Expand Up @@ -346,8 +371,23 @@ at (and including) 4 and stopping before 6.

## See Also

- [`ALTER TABLE`](alter-table.html)
- [`ALTER SEQUENCE`](alter-sequence.html)
- [`BACKUP`](backup.html)
- [`CANCEL JOB`](cancel-job.html)
- [`CREATE DATABASE`](create-database.html)
- [`DROP DATABASE`](drop-database.html)
- [`EXECUTE`](sql-grammar.html#execute_stmt)
- [`IMPORT`](import.html)
- [Indexes](indexes.html)
- [`DELETE`](delete.html)
- [`INSERT`](insert.html)
- [`PAUSE JOB`](pause-job.html)
- [`RESET`](reset-vars.html)
- [`RESTORE`](restore.html)
- [`RESUME JOB`](resume-job.html)
- [`SELECT`](select.html)
- [`SET`](set-vars.html)
- [`SET CLUSTER SETTING`](set-cluster-setting.html)
- [`SHOW COLUMNS`](show-columns.html)
- [`UPDATE`](update.html)
- [`UPSERT`](upsert.html)