From 4744b5a9469380eb92a4e97134b070b672e778ee Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Wed, 23 Aug 2023 13:44:50 -0400 Subject: [PATCH 1/3] Docs: Add query syntax to `COPY` docs --- docs/source/user-guide/sql/ddl.md | 3 +++ docs/source/user-guide/sql/dml.md | 32 +++++++++++++++++++++++++++++-- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/source/user-guide/sql/ddl.md b/docs/source/user-guide/sql/ddl.md index 0dcc4517b55ac..67a438954aa46 100644 --- a/docs/source/user-guide/sql/ddl.md +++ b/docs/source/user-guide/sql/ddl.md @@ -19,6 +19,9 @@ # DDL +DDL stands for "Data Definition Lanaguage" and relates to creating and +modifying catalog objects such as Tables. + ## CREATE DATABASE Create catalog with specified name. diff --git a/docs/source/user-guide/sql/dml.md b/docs/source/user-guide/sql/dml.md index 26f291c15a121..46195b92d09fc 100644 --- a/docs/source/user-guide/sql/dml.md +++ b/docs/source/user-guide/sql/dml.md @@ -19,14 +19,20 @@ # DML +DML stands for "Data Manipulation Lanaguage" and relates to inserting +and modifying data in tables. + + ## COPY -Copy a table to file(s). Supported file formats are `parquet`, `csv`, and `json`. +Copies the contents of a table or query to file(s). Supported file +formats are `parquet`, `csv`, and `json` and can be inferred based on +filename if writing to a single file. The `PER_THREAD_OUTPUT` option treats `file_name` as a directory and writes a file per thread within it. 
-COPY table_name TO 'file_name' [ ( option [, ... ] ) ]
+COPY [table_name | query] TO 'file_name' [ ( option [, ... ] ) ]
 
 where option can be one of:
     FORMAT format_name
@@ -35,6 +41,9 @@ where option can be one of:
     ROW_GROUP_LIMIT_BYTES integer
+ +Copy the contents of `source_table` to `file_name.json` in JSON format: + ```sql > COPY source_table TO 'file_name.json'; +-------+ @@ -42,7 +51,12 @@ where option can be one of: +-------+ | 2 | +-------+ +``` +Copy the contents of `source_table` to one or more Parquet formatted +files in the `dir_name` directory: + +```sql > COPY source_table TO 'dir_name' (FORMAT parquet, PER_THREAD_OUTPUT true); +-------+ | count | @@ -51,6 +65,20 @@ where option can be one of: +-------+ ``` + +Run the query `SELECT * from source ORDER BY time` and write the +results (maintaining the order) to a parquet file named +`output.parquet` with a maximum parquet row group size of 10MB: + +```sql +> COPY (SELECT * from source ORDER BY time) TO 'output.parquet' (ROW_GROUP_LIMIT_BYTES 10000000); ++-------+ +| count | ++-------+ +| 2 | ++-------+ +``` + ## INSERT Insert values into a table. From a2d9b73c9451c6b1eba8d06e1c92d40a6508f364 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Wed, 23 Aug 2023 13:45:55 -0400 Subject: [PATCH 2/3] prettier --- docs/source/user-guide/sql/dml.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/source/user-guide/sql/dml.md b/docs/source/user-guide/sql/dml.md index 46195b92d09fc..876abb61ac3bb 100644 --- a/docs/source/user-guide/sql/dml.md +++ b/docs/source/user-guide/sql/dml.md @@ -22,7 +22,6 @@ DML stands for "Data Manipulation Lanaguage" and relates to inserting and modifying data in tables. - ## COPY Copies the contents of a table or query to file(s). Supported file @@ -41,7 +40,6 @@ where option can be one of: ROW_GROUP_LIMIT_BYTES integer - Copy the contents of `source_table` to `file_name.json` in JSON format: ```sql @@ -65,7 +63,6 @@ files in the `dir_name` directory: +-------+ ``` - Run the query `SELECT * from source ORDER BY time` and write the results (maintaining the order) to a parquet file named `output.parquet` with a maximum parquet row group size of 10MB: From 5d651dea1ba4825fb9c3b663e440416573b3b4dd Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 24 Aug 2023 06:24:35 -0400 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Seth Paydar <29551413+spaydar@users.noreply.github.com> --- docs/source/user-guide/sql/ddl.md | 2 +- docs/source/user-guide/sql/dml.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/user-guide/sql/ddl.md b/docs/source/user-guide/sql/ddl.md index 67a438954aa46..f566b8342ec16 100644 --- a/docs/source/user-guide/sql/ddl.md +++ b/docs/source/user-guide/sql/ddl.md @@ -19,7 +19,7 @@ # DDL -DDL stands for "Data Definition Lanaguage" and relates to creating and +DDL stands for "Data Definition Language" and relates to creating and modifying catalog objects such as Tables. ## CREATE DATABASE diff --git a/docs/source/user-guide/sql/dml.md b/docs/source/user-guide/sql/dml.md index 876abb61ac3bb..9794fba4aa624 100644 --- a/docs/source/user-guide/sql/dml.md +++ b/docs/source/user-guide/sql/dml.md @@ -19,7 +19,7 @@ # DML -DML stands for "Data Manipulation Lanaguage" and relates to inserting +DML stands for "Data Manipulation Language" and relates to inserting and modifying data in tables. ## COPY @@ -31,7 +31,7 @@ filename if writing to a single file. The `PER_THREAD_OUTPUT` option treats `file_name` as a directory and writes a file per thread within it. 
-COPY [table_name | query] TO 'file_name' [ ( option [, ... ] ) ]
+COPY { table_name | query } TO 'file_name' [ ( option [, ... ] ) ]
 
 where option can be one of:
     FORMAT format_name