ODIn/spark-instrumented-optimizer
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

[SPARK-33877][SQL] SQL reference documents for INSERT w/ a column list

Browse source 
We support a column list of INSERT for Spark v3.1.0 (See: SPARK-32976 (https://github.com/apache/spark/pull/29893)). So, this PR targets at documenting it in the SQL documents.

### What changes were proposed in this pull request?

improve doc
### Why are the changes needed?

### Does this PR introduce _any_ user-facing change?

doc
### How was this patch tested?

passing GA doc gen.

![image](https://user-images.githubusercontent.com/8326978/102954876-8994fa00-450f-11eb-81f9-931af6d1f69b.png)
![image](https://user-images.githubusercontent.com/8326978/102954900-99acd980-450f-11eb-9733-115ad37d2319.png)

![image](https://user-images.githubusercontent.com/8326978/102954935-af220380-450f-11eb-9aaa-fdae0725d41e.png)
![image](https://user-images.githubusercontent.com/8326978/102954949-bc3ef280-450f-11eb-8a0d-d7b688efa7bb.png)

Closes #30888 from yaooqinn/SPARK-33877.

Authored-by: Kent Yao <yaooqinn@hotmail.com>
Signed-off-by: Dongjoon Hyun <dhyun@apple.com>
This commit is contained in:
Kent Yao 2020-12-22 19:46:37 -08:00 committed by Dongjoon Hyun
parent ec1560af25
commit a3dd8dacee
2 changed files with 80 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
docs/sql-ref-syntax-dml-insert-into.md
View file

@ -26,7 +26,7 @@ The `INSERT INTO` statement inserts new rows into a table. The inserted rows can
### Syntax ### Syntax
```sql ```sql
INSERT INTO [ TABLE ] table_identifier [ partition_spec ] INSERT INTO [ TABLE ] table_identifier [ partition_spec ] [ ( column_list ) ]
{ VALUES ( { value | NULL } [ , ... ] ) [ , ( ... ) ] | query } { VALUES ( { value | NULL } [ , ... ] ) [ , ( ... ) ] | query }
``` ```
@ -40,11 +40,20 @@ INSERT INTO [ TABLE ] table_identifier [ partition_spec ]
* **partition_spec** * **partition_spec**
An optional parameter that specifies a comma separated list of key and value pairs An optional parameter that specifies a comma-separated list of key and value pairs
for partitions. for partitions.
**Syntax:** `PARTITION ( partition_col_name = partition_col_val [ , ... ] )` **Syntax:** `PARTITION ( partition_col_name = partition_col_val [ , ... ] )`
* **column_list**
An optional parameter that specifies a comma-separated list of columns belonging to the `table_identifier` table.
**Note:**The current behaviour has some limitations:
- All specified columns should exist in the table and not be duplicated from each other. It includes all columns except the static partition columns.
- The size of the column list should be exactly the size of the data from `VALUES` clause or query.
- The order of the column list is alterable and determines how the data from `VALUES` clause or query to be inserted by position.
* **VALUES ( { value `|` NULL } [ , ... ] ) [ , ( ... ) ]** * **VALUES ( { value `|` NULL } [ , ... ] ) [ , ( ... ) ]**
Specifies the values to be inserted. Either an explicitly specified value or a NULL can be inserted. Specifies the values to be inserted. Either an explicitly specified value or a NULL can be inserted.
@ -198,6 +207,34 @@ SELECT * FROM students;
+-------------+--------------------------+----------+ +-------------+--------------------------+----------+
``` ```
#### Insert with a column list
```sql
INSERT INTO students (address, name, student_id) VALUES
('Hangzhou, China', 'Kent Yao', 11215016);
SELECT * FROM students WHERE name = 'Kent Yao';
+---------+----------------------+----------+
| name| address|student_id|
+---------+----------------------+----------+
|Kent Yao | Hangzhou, China| 11215016|
+---------+----------------------+----------+
```
#### Insert with both a partition spec and a column list
```sql
INSERT INTO students PARTITION (student_id = 11215017) (address, name) VALUES
('Hangzhou, China', 'Kent Yao Jr.');
SELECT * FROM students WHERE student_id = 11215017;
+------------+----------------------+----------+
| name| address|student_id|
+------------+----------------------+----------+
|Kent Yao Jr.| Hangzhou, China| 11215017|
+------------+----------------------+----------+
```
### Related Statements ### Related Statements
* [INSERT OVERWRITE statement](sql-ref-syntax-dml-insert-overwrite-table.html) * [INSERT OVERWRITE statement](sql-ref-syntax-dml-insert-overwrite-table.html)

43
docs/sql-ref-syntax-dml-insert-overwrite-table.md
View file

@ -26,7 +26,7 @@ The `INSERT OVERWRITE` statement overwrites the existing data in the table using
### Syntax ### Syntax
```sql ```sql
INSERT OVERWRITE [ TABLE ] table_identifier [ partition_spec [ IF NOT EXISTS ] ] INSERT OVERWRITE [ TABLE ] table_identifier [ partition_spec [ IF NOT EXISTS ] ] [ ( column_list ) ]
{ VALUES ( { value | NULL } [ , ... ] ) [ , ( ... ) ] | query } { VALUES ( { value | NULL } [ , ... ] ) [ , ( ... ) ] | query }
``` ```
@ -40,11 +40,22 @@ INSERT OVERWRITE [ TABLE ] table_identifier [ partition_spec [ IF NOT EXISTS ] ]
* **partition_spec** * **partition_spec**
An optional parameter that specifies a comma separated list of key and value pairs An optional parameter that specifies a comma-separated list of key and value pairs
for partitions. for partitions.
**Syntax:** `PARTITION ( partition_col_name [ = partition_col_val ] [ , ... ] )` **Syntax:** `PARTITION ( partition_col_name [ = partition_col_val ] [ , ... ] )`
* **column_list**
An optional parameter that specifies a comma-separated list of columns belonging to the `table_identifier` table.
**Note**
The current behaviour has some limitations:
- All specified columns should exist in the table and not be duplicated from each other. It includes all columns except the static partition columns.
- The size of the column list should be exactly the size of the data from `VALUES` clause or query.
- The order of the column list is alterable and determines how the data from `VALUES` clause or query to be inserted by position.
* **VALUES ( { value `|` NULL } [ , ... ] ) [ , ( ... ) ]** * **VALUES ( { value `|` NULL } [ , ... ] ) [ , ( ... ) ]**
Specifies the values to be inserted. Either an explicitly specified value or a NULL can be inserted. Specifies the values to be inserted. Either an explicitly specified value or a NULL can be inserted.
@ -169,6 +180,34 @@ SELECT * FROM students;
+-----------+-------------------------+----------+ +-----------+-------------------------+----------+
``` ```
#### Insert with a column list
```sql
INSERT OVERWRITE students (address, name, student_id) VALUES
('Hangzhou, China', 'Kent Yao', 11215016);
SELECT * FROM students WHERE name = 'Kent Yao';
+---------+----------------------+----------+
| name| address|student_id|
+---------+----------------------+----------+
|Kent Yao | Hangzhou, China| 11215016|
+---------+----------------------+----------+
```
#### Insert with both a partition spec and a column list
```sql
INSERT OVERWRITE students PARTITION (student_id = 11215016) (address, name) VALUES
('Hangzhou, China', 'Kent Yao Jr.');
SELECT * FROM students WHERE student_id = 11215016;
+------------+----------------------+----------+
| name| address|student_id|
+------------+----------------------+----------+
|Kent Yao Jr.| Hangzhou, China| 11215016|
+------------+----------------------+----------+
```
### Related Statements ### Related Statements
* [INSERT INTO statement](sql-ref-syntax-dml-insert-into.html) * [INSERT INTO statement](sql-ref-syntax-dml-insert-into.html)