[SPARK-28792][SQL][DOC] Document CREATE DATABASE statement in SQL Reference. #25595

sharangk · 2019-08-27T09:02:45Z

What changes were proposed in this pull request?

Document CREATE DATABASE statement in SQL Reference Guide.

Why are the changes needed?

Currently Spark lacks documentation on the supported SQL constructs causing
confusion among users who sometimes have to look at the code to understand the
usage. This is aimed at addressing this issue.

Does this PR introduce any user-facing change?

Yes.

Before:

There was no documentation for this.

After:

How was this patch tested?

Manual Review and Tested using jykyll build --serve

sharangk · 2019-08-30T08:02:18Z

@dilipbiswal , @gatorsmile , Please review. Thanks

huaxingao · 2019-08-30T16:43:16Z

docs/sql-ref-syntax-ddl-create-database.md

[ WITH DBPROPERTIES ( property_name = property_value [ , ... ] ) ]
Since it's optional to have multiple property name value pairs, I think it's better to use [ , ... ] to show it's optional.

@dilipbiswal @gatorsmile
I am wondering if we should define a standard for the syntax format. Should we have a white space between the braces, =, |, ... and the text? I currently put a white space because I saw a couple of sql references have these standard. I am OK with either having white space or no white space, but I am thinking we may need to define a standard and write out the standard explicitly in the umbrella jira so everybody can follow. Also, shall we have 4 white space indentation for the 2nd line? I am ok with either 2 or 4, but prefer everybody to follow the same way.

@huaxingao About while spacing , i am +1 on this. About the indentation on the 2nd line, i don't have a strong preference. @gatorsmile do you have a preference here ?

Updated white spaces wherever required. Thanks

huaxingao · 2019-08-30T16:45:40Z

docs/sql-ref-syntax-ddl-create-database.md

Could you please rebase your branch and follow the parameters format in #25523? Thanks!

Formatted based on #25523 . Thanks

huaxingao · 2019-08-30T16:46:56Z

docs/sql-ref-syntax-ddl-create-database.md

nit: ### Related Statements

Updated. Thanks

dilipbiswal · 2019-08-30T17:48:04Z

docs/sql-ref-syntax-ddl-create-database.md

Between two tests, lets have a empty line ?

Done. Thanks

dilipbiswal · 2019-08-30T17:48:17Z

docs/sql-ref-syntax-ddl-create-database.md

Indent this ?

dilipbiswal · 2019-08-30T17:49:37Z

docs/sql-ref-syntax-ddl-create-database.md

Since this is an optional clause, should we specify what happens when this is not specified ? The database is created in the default warehouse directory ? Could you please check ?

Updated. Thanks

dilipbiswal · 2019-08-30T17:53:35Z

@sharangk Thanks for working on it. Can we please re-word some descriptions ? It sounds similar to some other docs.

sharangk · 2019-09-03T03:08:33Z

Thanks for the timely review. I will work the comments and resubmit the PR.

sharangk · 2019-09-05T12:04:52Z

Handled the comments. Thanks @dilipbiswal @huaxingao for timely review.
@gatorsmile , Could you please have a look at the changes.

dilipbiswal · 2019-09-12T07:11:33Z

docs/sql-ref-syntax-ddl-create-database.md

Tiny nit : Specifies the description for the database.

dilipbiswal · 2019-09-12T07:11:57Z

docs/sql-ref-syntax-ddl-create-database.md

Tiny nit: add Specifies

dilipbiswal · 2019-09-12T07:16:22Z

docs/sql-ref-syntax-ddl-create-database.md

Can we put the 2nd line under a comment like

-- Create database `customer_db`. This throws exception if database with name customer_db -- already exists.

dilipbiswal · 2019-09-12T07:17:09Z

docs/sql-ref-syntax-ddl-create-database.md

Can we put the 2nd line under a comment like

-- Create database `customer_db` only if database with same name doesn't exist with -- `Comments`,`Specific Location` and `Database properties`.

dilipbiswal · 2019-09-12T07:18:37Z

docs/sql-ref-syntax-ddl-create-database.md

lets indent the 2nd line so that it looks continuation of first line like :

CREATE DATABASE IF NOT EXISTS customer_db COMMENT 'This is customer database' LOCATION '/user' WITH DBPROPERTIES (ID=001, Name='John');

dilipbiswal · 2019-09-12T07:19:46Z

@sharangk Mostly looks good. I have put some minor comments.

…erence # Why are the changes needed? Currently Spark lacks documentation on the supported SQL constructs causing confusion among users who sometimes have to look at the code to understand the usage. This is aimed at addressing this issue. ## How was this patch tested? This is just a documentation change, verified manually.

sharangk · 2019-09-16T04:05:32Z

@dilipbiswal , Thanks for the review. Resubmitted the PR with updates. Please have a look. Thanks !!!

dilipbiswal · 2019-09-17T05:36:17Z

docs/sql-ref-syntax-ddl-create-database.md

+    <dd>Creates a database with the given name if it doesn't exists. If a database with the same name already exists, nothing will happen.</dd>
+
+    <dt><code><em>database_directory</em></code></dt>
+    <dd>Path of the file system in which database to be created. If the specified path does not exist in the underlying file system, this command creates a directory with the path. If location is not specified, database will be created in default warehouse directory.</dd>


@sharangk in which the specified database is to be created ?

sharangk · 2019-09-17T11:38:13Z

@dilipbiswal , Thanks. Handled the review comments.

dilipbiswal · 2019-09-17T14:27:03Z

LGTM
cc @gatorsmile

gatorsmile · 2019-09-17T20:38:49Z

ok to test

SparkQA · 2019-09-17T21:05:37Z

Test build #110828 has finished for PR 25595 at commit 0225553.

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

gatorsmile · 2019-09-17T21:39:35Z

Thanks! Merged to master.

dongjoon-hyun added the SQL label Aug 28, 2019

huaxingao reviewed Aug 30, 2019

View reviewed changes

dilipbiswal reviewed Aug 30, 2019

View reviewed changes

sharangk force-pushed the createDbDoc branch 4 times, most recently from b494bfb to 246290d Compare September 5, 2019 11:13

dilipbiswal reviewed Sep 12, 2019

View reviewed changes

docs/sql-ref-syntax-ddl-create-database.md Outdated

Copy link

Contributor

dilipbiswal Sep 12, 2019

Choose a reason for hiding this comment

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

Tiny nit : Specifies the description for the database.

dilipbiswal reviewed Sep 12, 2019

View reviewed changes

docs/sql-ref-syntax-ddl-create-database.md Outdated

Copy link

Contributor

dilipbiswal Sep 12, 2019

Choose a reason for hiding this comment

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

Tiny nit: add Specifies

dilipbiswal reviewed Sep 12, 2019

View reviewed changes

sharangk added 3 commits September 13, 2019 16:21

updated review comments

7ef960b

sharangk force-pushed the createDbDoc branch from 67cbbbc to 7ef960b Compare September 13, 2019 11:13

dilipbiswal reviewed Sep 17, 2019

View reviewed changes

updated sentence

5cb4c42

Update sql-ref-syntax-ddl-create-database.md

0225553

gatorsmile closed this in dd32476 Sep 17, 2019

[SPARK-28792][SQL][DOC] Document CREATE DATABASE statement in SQL Reference. #25595

[SPARK-28792][SQL][DOC] Document CREATE DATABASE statement in SQL Reference. #25595

Uh oh!

Conversation

sharangk commented Aug 27, 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?

Before:

After:

How was this patch tested?

Uh oh!

sharangk commented Aug 30, 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!

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!

dilipbiswal commented Aug 30, 2019

Uh oh!

sharangk commented Sep 3, 2019

Uh oh!

sharangk commented Sep 5, 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!

dilipbiswal commented Sep 12, 2019

Uh oh!

sharangk commented Sep 16, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sharangk commented Sep 17, 2019

Uh oh!

dilipbiswal commented Sep 17, 2019

Uh oh!

gatorsmile commented Sep 17, 2019

Uh oh!

SparkQA commented Sep 17, 2019

Uh oh!

gatorsmile commented Sep 17, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

sharangk commented Aug 27, 2019 •

edited

Loading