identify all statements that can be EXPLAINed #2682

lnhsingh · 2018-03-08T22:29:13Z

Closes #1963.

cockroach-teamcity · 2018-03-08T22:29:17Z

This change is

cockroach-teamcity · 2018-03-08T22:34:12Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/59c13d5db490955801a5a03536badb1eacecd838/

knz · 2018-03-09T10:32:18Z

v1.0/explain.md

+- [`ALTER TABLE`](alter-table.html)
+- [`CREATE`](sql-grammar.html#create_stmt)
+- [`DELETE`](delete.html)
+- [`HELP`](sql-grammar.html#help_stmt)


Remove HELP, it was not meant to be documented.

knz · 2018-03-09T10:32:42Z

v1.0/explain.md

+- [`INSERT`](insert.html)
+- [`SELECT`](select.html)
+- [`SHOW`](sql-grammar.html#show_stmt)
+- [`SPLIT`](sql-grammar.html#split_stmt)


There is no "SPLIT" statement, it's a special form of ALTER.

knz · 2018-03-09T10:32:52Z

v1.0/explain.md

+
+You can use `EXPLAIN` on the following statements:
+
+- [`ALTER TABLE`](alter-table.html)


I think all the forms of ALTER can be explained, not just ALTER TABLE. Or perhaps that was not true in 1.0?

I would also put the various ALTER statements on the same line with proper doc links like this:

- [`ALTER TABLE`](alter-table.html), [`ALTER INDEX`](alter-index.html), ...

According to the full SQL grammar, only ALTER TABLE is explainable in 1.0. I'll update the following versions with how you suggested though.

knz · 2018-03-09T10:33:16Z

v1.0/explain.md

+- [`SELECT`](select.html)
+- [`SHOW`](sql-grammar.html#show_stmt)
+- [`SPLIT`](sql-grammar.html#split_stmt)
+- [`UPDATE`](update.html)


You can add EXPLAIN to this list too (EXPLAIN is explainable)

knz · 2018-03-09T10:34:09Z

v2.0/explain.md

+- [`SET CLUSTER SETTING`](set-cluster-setting.html)
+- [`SHOW`](sql-grammar.html#show_stmt)
+- [`UPDATE`](update.html)
+- [`UPSERT`](upsert.html)


Add EXPLAIN to this list.

knz · 2018-03-09T10:38:30Z

v1.1/explain.md

+- [`EXECUTE`](sql-grammar.html#execute_stmt)
+- [`IMPORT`](sql-grammar.html#import_stmt)
+- [`PAUSE JOB`](sql-grammar.html#pause_stmt)
+- [`RESET`](sql-grammar.html#reset_stmt)


link reset-vars.html

knz · 2018-03-09T10:38:41Z

v1.1/explain.md

+- [`PAUSE JOB`](sql-grammar.html#pause_stmt)
+- [`RESET`](sql-grammar.html#reset_stmt)
+- [`RESTORE`](restore.html)
+- [`RESUME JOB`](sql-grammar.html#resume_stmt)


link resume-job.html

knz · 2018-03-09T10:38:51Z

v1.1/explain.md

+- [`RESTORE`](restore.html)
+- [`RESUME JOB`](sql-grammar.html#resume_stmt)
+- [`SELECT`](select.html)
+- [`SET SESSION`](sql-grammar.html#set_session_stmt)


link set-vars.html

knz · 2018-03-09T10:39:04Z

v1.1/explain.md

+- [`SELECT`](select.html)
+- [`SET SESSION`](sql-grammar.html#set_session_stmt)
+- [`SET CLUSTER SETTING`](set-cluster-settings.html)
+- [`SHOW`](sql-grammar.html#show_stmt)


list the various SHOW pages

knz · 2018-03-09T10:39:16Z

v2.0/explain.md


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

+## Explainable Statements
+
+- [`ALTER`](sql-grammar.html#alter_stmt)


ditto precise page links as for 1.1.

jseldess

Only a few suggestions on top of @knz's.

jseldess · 2018-03-09T14:22:25Z

v2.0/explain.md


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

+## Explainable Statements
+


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:

jseldess · 2018-03-09T14:26:55Z

v1.0/explain.md

@@ -4,10 +4,24 @@ 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 to execute the [explainable statements](#explainable-statments). You can then use this information to optimize those queries.


nit: to execute the explainable statements > for an explainable statement.

Also, I'd tweak the second sentence a bit: You can then use this information to optimize the query.

Please apply this change to other versions of the page as well.

cockroach-teamcity · 2018-03-09T17:09:17Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/51cf1aade029f7c02acf91e11beb30b708191a0f/

cockroach-teamcity · 2018-03-09T17:48:11Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/c9fe1835a9aec22365418db8b48bbe64623a7648/

cockroach-teamcity · 2018-03-09T17:49:10Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/701c77b173d831b5f79f2f3444aec6be058fed09/

cockroach-teamcity · 2018-03-09T17:50:42Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/f631d5df0657fbfdedf70a32f96abcaf6e3a7ed1/

jseldess · 2018-03-09T18:35:28Z

v1.0/explain.md

@@ -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 statements](#explainable-statements). You can then use this information to optimize the query.


explainable statements > explainable statement

jseldess · 2018-03-09T18:35:34Z

v1.1/explain.md

@@ -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 statements](#explainable-statements). You can then use this information to optimize the query.


explainable statements > explainable statement

jseldess · 2018-03-09T18:35:52Z

v2.0/explain.md

@@ -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 statements](#explainable-statements). You can then use this information to optimize the query.


explainable statements > explainable statement

jseldess

Something in the v2.0 page seems to have messed up the page after the diagram: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/f631d5df0657fbfdedf70a32f96abcaf6e3a7ed1/dev/explain.html#synopsis

Can you wrap the diagram in <section> tags and see if that fixes the problem?

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

cockroach-teamcity · 2018-03-09T18:46:12Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/025ea30c201214398a569fc6e829f48a083b3e92/

cockroach-teamcity · 2018-03-11T05:34:18Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/025ea30c201214398a569fc6e829f48a083b3e92/

jseldess

Seems like we need to update the explainable_stmt description under "Parameters" and the See Also list as well, on all versions of the page. For See Also, no need to list all statements that can be explained, I think.

Closes #1963.

fix broken links fix broken link

cockroach-teamcity · 2018-03-12T15:11:34Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/fd9684a76b69da3f2ae08456b821dc61496d51db/

cockroach-teamcity · 2018-03-12T15:15:59Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/f4ef58ebe3c04f4143b1167a9cb4e290247d80a5/

jseldess · 2018-03-12T17:15:29Z

LGTM, @lhirata!

lnhsingh requested a review from jseldess March 8, 2018 22:29

lnhsingh added the in progress label Mar 8, 2018

knz reviewed Mar 9, 2018

View reviewed changes

jseldess reviewed Mar 9, 2018

View reviewed changes

lnhsingh added the fixitday label Mar 9, 2018

lnhsingh force-pushed the fixit-explain branch from 701c77b to f631d5d Compare March 9, 2018 17:48

jseldess reviewed Mar 9, 2018

View reviewed changes

jseldess reviewed Mar 11, 2018

View reviewed changes

Lauren added 4 commits March 12, 2018 11:11

identify all statements that can be EXPLAINed

484fdbe

Closes #1963.

added links to all explainable statements

158170c

fix broken links fix broken link

minor edits

f326652

minor updates

f4ef58e

lnhsingh force-pushed the fixit-explain branch from fd9684a to f4ef58e Compare March 12, 2018 15:11

jseldess merged commit 8698fc7 into master Mar 12, 2018

jseldess deleted the fixit-explain branch March 12, 2018 17:15

jseldess removed the in progress label Mar 12, 2018


		You can use `EXPLAIN` on the following statements:

		- [`ALTER TABLE`](alter-table.html)

identify all statements that can be EXPLAINed #2682

identify all statements that can be EXPLAINed #2682

Uh oh!

Conversation

lnhsingh commented Mar 8, 2018

Uh oh!

cockroach-teamcity commented Mar 8, 2018

Uh oh!

cockroach-teamcity commented Mar 8, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jseldess left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cockroach-teamcity commented Mar 9, 2018

Uh oh!

cockroach-teamcity commented Mar 9, 2018

Uh oh!

cockroach-teamcity commented Mar 9, 2018

Uh oh!

cockroach-teamcity commented Mar 9, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment