[SPARK-28810][DOC][SQL] Document SHOW TABLES in SQL Reference. #25561

shivusondur · 2019-08-23T03:56:09Z

What changes were proposed in this pull request?

Added the reference for SHOW TABLES sql command.

Why are the changes needed?

To help the customer usage

Does this PR introduce any user-facing change?

It updates the Sql command reference doc.

How was this patch tested?

Attached the Snap

amanomer · 2019-08-24T13:27:42Z

docs/sql-ref-syntax-aux-show-tables.md

form -> from.

databse -> database.

docs/sql-ref-syntax-aux-show-tables.md

sandeep-katta · 2019-08-27T05:09:52Z

docs/sql-ref-syntax-aux-show-tables.md

refer tables.scala for syntax

shivusondur · 2019-09-02T10:50:58Z

@dilipbiswal @gatorsmile
Updated the PR according to #25525 and #25523 PR's.
Updated the ScreenShot after creating the document from Jekyll build

Please review and kindly check for merging.

gatorsmile · 2019-09-20T21:05:49Z

ok to test

SparkQA · 2019-09-20T21:21:01Z

Test build #111092 has finished for PR 25561 at commit 172849a.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

dilipbiswal · 2019-09-21T07:33:36Z

docs/sql-ref-syntax-aux-show-tables.md

+  </dd>
+  <dt><code><em>LIKE 'regex_pattern'</em></code></dt>
+  <dd>
+     A regex pattern that is used to filter out unwanted functions.


@shivusondur Can you please check the code here ? Looks like this is copied from SHOW FUNCTIONS. Please make sure the pattern is processed the same way in SHOW TABLES. If so, you can change from "unwanted functions" to "unwanted tables"..

dilipbiswal · 2019-09-21T07:35:22Z

docs/sql-ref-syntax-aux-show-tables.md

+{% highlight sql %}
+-- List all tables in default database
+SHOW TABLES;
+-----------+------------+--------------+--+


Nit: two space align for results to match the other prs ?

dilipbiswal · 2019-09-21T07:35:55Z

docs/sql-ref-syntax-aux-show-tables.md

+
+{% endhighlight %}
+
+### Related statements.


remove period

dilipbiswal · 2019-09-21T07:36:18Z

docs/sql-ref-syntax-aux-show-tables.md

+SHOW TABLES [{FROM|IN} database_name] [LIKE 'regex_pattern']
+{% endhighlight %}
+
+### Parameter


Nit: Parameters ?

2. Changed to "unwanted tables" 3. Added the "two space align in the result" 4. removed the period in "statements" 5. verified the links in the Related statements

shivusondur · 2019-09-21T11:21:34Z

@dilipbiswal
i handled all your comments, please have a look.
and again thanks for your review.

SparkQA · 2019-09-21T11:30:47Z

Test build #111117 has finished for PR 25561 at commit 19f39fc.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

dilipbiswal · 2019-09-21T18:17:20Z

docs/sql-ref-syntax-aux-show-tables.md

+  <dt><code><em>LIKE 'regex_pattern'</em></code></dt>
+  <dd>
+     Specifies the regex pattern that is used to filter out unwanted tables.
+       <br> - Only `*` and `|` are allowed as wildcard pattern.


@shivusondur Can you please include the example with output using the 'I' as wildcard ? From the code its not clear to me if this is supported.

@dilipbiswal
Done

dilipbiswal · 2019-09-21T18:19:01Z

docs/sql-ref-syntax-aux-show-tables.md

+{% highlight sql %}
+-- List all tables in default database
+SHOW TABLES;
+  +-----------+------------+--------------+--+


Please lets fix the formatting. Did we construct this output by hand ? Can we paste the
actual output here please so we preserve the formatting.

@dilipbiswal
I just Copy and paste the actual output from the Beeline console
Here is the beeline console snap

In the UI it looks like below, i think it is normal

Only in the git file editor, it shows inconsistent.

SparkQA · 2019-09-22T03:50:27Z

Test build #111140 has finished for PR 25561 at commit 55ea2cf.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

dilipbiswal · 2019-09-22T08:22:41Z

docs/sql-ref-syntax-aux-show-tables.md

+  | default   | sam        | false        |
+  | default   | sam1       | false        |
+  +-----------+------------+--------------+--+
+-- List all tables matching the pattern `sam*|suj`


Nit: can we have a line between previous test and this one.

@dilipbiswal
Done, updated the snap's also.

SparkQA · 2019-09-22T08:53:54Z

Test build #111148 has finished for PR 25561 at commit 0dd4efb.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

dilipbiswal · 2019-09-22T18:29:54Z

docs/sql-ref-syntax-aux-show-tables.md

+### Description

-**This page is under construction**
+List all the `tables` from the database with `database-name` and `is temporary table`.


@shivusondur Sorry.. re-reading this one last time :-)
SHOW TABLES statement returns all the tables for an optionally specified database. Additionally, the output
of this statement may be filtered via an optional matching pattern. If no database is specified then the tables
are returned from the current database.

dilipbiswal · 2019-09-22T18:30:19Z

LGTM - except a minor comment.

dilipbiswal · 2019-09-22T18:30:30Z

cc @gatorsmile

shivusondur · 2019-09-23T00:46:46Z

@dilipbiswal and @gatorsmile
Handled the all the comments.

SparkQA · 2019-09-23T00:57:51Z

Test build #111176 has finished for PR 25561 at commit 1d08b22.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

srowen · 2019-09-28T15:44:00Z

docs/sql-ref-syntax-aux-show-tables.md

+  <dt><code><em>LIKE 'regex_pattern'</em></code></dt>
+  <dd>
+     Specifies the regex pattern that is used to filter out unwanted tables.
+       <br> - Only `*` and `|` are allowed as wildcard pattern.


| isn't a wildcard pattern, so I wouldn't imply it is.
Is it really treated as a full regex otherwise? if not, I wouldn't call it a regex unless it is generally called this in other similar references.

@srowen Thats a very good point Sean. How about we name the pattern 'identifier_with_wildcards' (and describe as such) as mentioned in ShowTablesCommand's comment ?

Is it a SQL-like pattern that supports wildcards like %? then I'd just call it a pattern

@srowen I quickly tried in my env. It does not support SQL-like pattern like %. I only saw the following work :

* : Matches 0 or more characters.

. : Matches a char

| : works like or expression.

@shivusondur Can you please confirm ?

@dilipbiswal @srowen
I also tesed, it is same behaviour you mentioned above.
It will use the below method to handle, here they are handling "|" and "*" seperatly, remaining treating as regex

spark/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/util/StringUtils.scala

Line 88 in e1ea806

def filterPattern(names: Seq[String], pattern: String): Seq[String] = {

OK, your comment is consistent with the docs then. Hm, but isn't it more accurate to say that * and | don't work like in regexes? * matches 0 or more characters, and | delimits whole regexes, which is different, but the rest is the same. Maybe a comment more like that. "The pattern is a regex except that * matches 0 or more characters by itself, and | may only be used at the top level to delimit alternative regexes to match." ?

@srowen @dilipbiswal
Thank you both for your time in reviewing.

I updated according to your suggestion and screenshot also I updated.
Now it will look like below.

SparkQA · 2019-10-01T18:39:10Z

Test build #111655 has finished for PR 25561 at commit 847fb8e.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

srowen · 2019-10-03T13:52:41Z

docs/sql-ref-syntax-aux-show-tables.md

+### Description

-**This page is under construction**
+`SHOW TABLES` statement returns all the tables for an optionally specified `database`.


Nit: add "The" at the start.
via -> by

SparkQA · 2019-10-03T18:10:53Z

Test build #111750 has finished for PR 25561 at commit 05a2e60.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

srowen · 2019-10-04T15:04:42Z

docs/sql-ref-syntax-aux-show-tables.md

+  <dt><code><em>LIKE 'regex_pattern'</em></code></dt>
+  <dd>
+     Specifies the regex pattern that is used to filter out unwanted tables.
+       <br> - The pattern is a regex except that `*` and `|`characters


"... except that * and | work differently"

srowen · 2019-10-04T15:05:00Z

docs/sql-ref-syntax-aux-show-tables.md

+### Description

-**This page is under construction**
+The `SHOW TABLES` statement returns all the tables for an optionally specified `database`.


Nit: no need to back-tick database here

@srowen
Done

dilipbiswal · 2019-10-04T20:08:40Z

docs/sql-ref-syntax-aux-show-tables.md

+  <dt><code><em>LIKE 'regex_pattern'</em></code></dt>
+  <dd>
+     Specifies the regex pattern that is used to filter out unwanted tables.
+       <br> - The pattern is a regex except that `*` and `|`characters


@shivusondur drop the "that" ?
@srowen Can you help check the above sentence please ?

@dilipbiswal
done

SparkQA · 2019-10-07T04:37:40Z

Test build #111830 has finished for PR 25561 at commit fed9431.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

dilipbiswal · 2019-10-07T04:40:09Z

LGTM
cc @srowen @gatorsmile

srowen · 2019-10-07T13:45:22Z

docs/sql-ref-syntax-aux-show-tables.md

+  <dt><code><em>LIKE 'regex_pattern'</em></code></dt>
+  <dd>
+     Specifies the regex pattern that is used to filter out unwanted tables.
+       <br> - The pattern is a regex except `*` and `|`characters


Nit: can you use an HTML unordered list? <ul><li>... etc? Or just make this a paragraph, not bullet points.

I still think this is kind of unclear, per the last comment. "except * ..." should be clarified. "except that * and | have a different meaning."

done.
used the html ul and li tags
and added the description like below
Except *and| characters remaining characters will follow the regular expression convention.

srowen · 2019-10-09T12:15:57Z

docs/sql-ref-syntax-aux-show-tables.md

-       <br> - The leading and trailing blanks are trimmed in the input pattern before processing.  
+     Specifies the regular expression pattern that is used to filter out unwanted tables. 
+     <ul> 
+          <li> Except `*` and `|` characters remaining characters will follow the regular expression convention.</li>


"Except for * and |, the pattern works like a regex"

srowen · 2019-10-09T12:16:58Z

docs/sql-ref-syntax-aux-show-tables.md

+     Specifies the regular expression pattern that is used to filter out unwanted tables. 
+     <ul> 
+          <li> Except `*` and `|` characters remaining characters will follow the regular expression convention.</li>
+          <li> `*` matches 0 or more characters and `|` used to provide more than one regex with OR condition. </li>


"* alone matches 0 or more characters, and | is used to separate multiple different regexes, any of which can match"

comments handled
Thanks for reviewing

srowen · 2019-10-10T18:30:07Z

docs/sql-ref-syntax-aux-show-tables.md

+  <dd>
+     Specifies the regular expression pattern that is used to filter out unwanted tables. 
+     <ul> 
+          <li> Except for * and | character, the pattern works like a regex.</li>


OK, I might put back the back-ticks or quotes around special chars here.

Done. The same correction I also interested. thank you

srowen · 2019-10-12T14:23:39Z

Merged to master

dongjoon-hyun added DOCUMENTATION SQL labels Aug 23, 2019

amanomer reviewed Aug 24, 2019

View reviewed changes

docs/sql-ref-syntax-aux-show-tables.md Outdated Show resolved Hide resolved

amanomer reviewed Aug 24, 2019

View reviewed changes

docs/sql-ref-syntax-aux-show-tables.md Outdated Show resolved Hide resolved

sandeep-katta reviewed Aug 27, 2019

View reviewed changes

docs/sql-ref-syntax-aux-show-tables.md Outdated

Copy link

Contributor

sandeep-katta Aug 27, 2019

Choose a reason for hiding this comment

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

refer tables.scala for syntax

shivusondur force-pushed the jiraSHOWTBLS branch from 6780347 to 172849a Compare September 2, 2019 10:39

dilipbiswal reviewed Sep 21, 2019

View reviewed changes

shivusondur added 3 commits September 21, 2019 16:41

Updated the document details

77e753a

Updated the document according to latest comments

5178160

1. changed to "Parameters"

19f39fc

2. Changed to "unwanted tables" 3. Added the "two space align in the result" 4. removed the period in "statements" 5. verified the links in the Related statements

shivusondur force-pushed the jiraSHOWTBLS branch from 172849a to 19f39fc Compare September 21, 2019 11:13

dilipbiswal reviewed Sep 21, 2019

View reviewed changes

1. Added the one more example to demonstrate the "|" wild card

55ea2cf

dilipbiswal reviewed Sep 22, 2019

View reviewed changes

Added the space between examples

0dd4efb

dilipbiswal reviewed Sep 22, 2019

View reviewed changes

srowen reviewed Sep 28, 2019

View reviewed changes

Updated the description

847fb8e

srowen reviewed Oct 3, 2019

View reviewed changes

handled the comments

05a2e60

shivusondur requested a review from srowen October 3, 2019 18:00

srowen reviewed Oct 4, 2019

View reviewed changes

dilipbiswal reviewed Oct 4, 2019

View reviewed changes

handled the comments

fed9431

srowen reviewed Oct 7, 2019

View reviewed changes

handled the comments

83cff5d

shivusondur requested a review from srowen October 9, 2019 04:41

srowen requested changes Oct 9, 2019

View reviewed changes

shivusondur added 2 commits October 10, 2019 09:24

handled the comments

f3e1c31

handled the comments

8e1e114

shivusondur requested a review from srowen October 10, 2019 04:06

srowen reviewed Oct 10, 2019

View reviewed changes

handled the comments

e26f55b

shivusondur requested a review from srowen October 11, 2019 03:52

srowen approved these changes Oct 11, 2019

View reviewed changes

srowen closed this in aa1acfe Oct 12, 2019

[SPARK-28810][DOC][SQL] Document SHOW TABLES in SQL Reference. #25561

[SPARK-28810][DOC][SQL] Document SHOW TABLES in SQL Reference. #25561

Uh oh!

Conversation

shivusondur commented Aug 23, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes were proposed in this pull request?

Why are the changes needed?

Does this PR introduce any user-facing change?

How was this patch tested?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivusondur commented Sep 2, 2019

Uh oh!

gatorsmile commented Sep 20, 2019

Uh oh!

SparkQA commented Sep 20, 2019

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!

shivusondur commented Sep 21, 2019

Uh oh!

SparkQA commented Sep 21, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivusondur Sep 22, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dilipbiswal Sep 21, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SparkQA commented Sep 22, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SparkQA commented Sep 22, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dilipbiswal commented Sep 22, 2019

Uh oh!

dilipbiswal commented Sep 22, 2019

Uh oh!

shivusondur commented Sep 23, 2019

Uh oh!

SparkQA commented Sep 23, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

shivusondur commented Aug 23, 2019 •

edited

Loading

shivusondur Sep 22, 2019 •

edited

Loading

dilipbiswal Sep 21, 2019 •

edited

Loading