[DRILL-7015] Improve documentation for PARTITION BY

• Type: Improvement
• Status: Open
• Priority: Minor
• Resolution: Unresolved
• Affects Version/s: 1.15.0
• Component/s: Documentation
• Assignee: Bridget Bevens
• Reporter: Boaz Ben-Zvi
• Created: 29/Jan/19 22:44
• Updated: 04/Nov/19 12:53

Description

The documentation for CREATE TABLE AS (CTAS) shows the syntax of the command, without the optional PARTITION BY clause. That option is only mentioned later under the usage notes.

Suggestion: Add this optional clause to the syntax (same as for CREATE TEMPORARY TABLE (CTTAS)). And mention that this option is only applicable when storing in Parquet. 

And the documentation for CREATE TEMPORARY TABLE (CTTAS), the comment says:

An optional parameter that can only be used to create temporary tables with the Parquet data format. 

Which can mistakenly be understood as "only for temporary tables". Suggestion: erase the "to create temporary tables" part (not needed, as it is implied from the context of this page).

Last suggestion: In the documentation for the PARTITION BY clause, can add an example using the implicit column "filename" to demonstrate how the partitioning column puts each distinct value into a separate file. For example, add in the "Other Examples" section :

0: jdbc:drill:zk=local> select distinct r_regionkey, filename from mytable1;
+--------------+----------------+
| r_regionkey  |    filename    |
+--------------+----------------+
| 2            | 0_0_3.parquet  |
| 1            | 0_0_2.parquet  |
| 0            | 0_0_1.parquet  |
| 3            | 0_0_4.parquet  |
| 4            | 0_0_5.parquet  |
+--------------+----------------+