From ccd51f2caf7d171ee46021eeeaf9339084dfd664 Mon Sep 17 00:00:00 2001 From: marcus Date: Mon, 3 Aug 2026 10:19:07 -0700 Subject: [PATCH] [SPARK-58520][SQL] Document dynamic table options in SQL reference --- docs/sql-ref-syntax-dml-insert-table.md | 21 +++++++++++++++++++-- docs/sql-ref-syntax-dml-merge-into.md | 22 +++++++++++++++++++++- docs/sql-ref-syntax-qry-select.md | 21 +++++++++++++++++++++ 3 files changed, 61 insertions(+), 3 deletions(-) diff --git a/docs/sql-ref-syntax-dml-insert-table.md b/docs/sql-ref-syntax-dml-insert-table.md index 4f78e6d81aee0..dd811f5d443bb 100644 --- a/docs/sql-ref-syntax-dml-insert-table.md +++ b/docs/sql-ref-syntax-dml-insert-table.md @@ -26,10 +26,14 @@ The `INSERT` statement inserts new rows into a table or overwrites the existing ### Syntax ```sql -INSERT [ WITH SCHEMA EVOLUTION ] [ INTO | OVERWRITE ] [ TABLE ] table_identifier [ partition_spec ] [ ( column_list ) | [BY NAME] ] +INSERT [ WITH SCHEMA EVOLUTION ] [ INTO | OVERWRITE ] [ TABLE ] table_identifier + [ WITH ( option_key = option_value [ , ... ] ) ] [ partition_spec ] + [ ( column_list ) | [BY NAME] ] { VALUES ( { value | NULL } [ , ... ] ) [ , ( ... ) ] | query } -INSERT [ WITH SCHEMA EVOLUTION ] INTO [ TABLE ] table_identifier [ BY NAME ] REPLACE WHERE boolean_expression query +INSERT [ WITH SCHEMA EVOLUTION ] INTO [ TABLE ] table_identifier + [ WITH ( option_key = option_value [ , ... ] ) ] [ BY NAME ] + REPLACE WHERE boolean_expression query ``` ### Parameters @@ -46,6 +50,11 @@ INSERT [ WITH SCHEMA EVOLUTION ] INTO [ TABLE ] table_identifier [ BY NAME ] REP **Syntax:** `[ database_name. ] table_name` +* **WITH ( option_key = option_value [ , ... ] )** + + Specifies dynamic table options for this `INSERT` operation. These options are passed to the + data source connector when writing to the table. The supported options depend on the connector. + * **partition_spec** An optional parameter that specifies a comma-separated list of key and value pairs @@ -88,6 +97,14 @@ INSERT [ WITH SCHEMA EVOLUTION ] INTO [ TABLE ] table_identifier [ BY NAME ] REP #### Insert Into +##### Insert Using Dynamic Table Options + +```sql +-- Option names and values are specific to the table's data source connector. +INSERT INTO students WITH (`write.split-size` = 10) + VALUES ('Amy Smith', '123 Park Ave, San Jose', 111111); +``` + ##### Single Row Insert Using a VALUES Clause ```sql diff --git a/docs/sql-ref-syntax-dml-merge-into.md b/docs/sql-ref-syntax-dml-merge-into.md index 1ae72ca63b7fe..25d30c401dd66 100644 --- a/docs/sql-ref-syntax-dml-merge-into.md +++ b/docs/sql-ref-syntax-dml-merge-into.md @@ -33,7 +33,9 @@ apply. All of these row-level changes are performed as a single atomic operation ```sql MERGE [ WITH SCHEMA EVOLUTION ] INTO target_table [ [ AS ] target_alias ] - USING { source_table | ( source_query ) } [ [ AS ] source_alias ] + [ WITH ( target_option_key = target_option_value [ , ... ] ) ] + USING { source_table [ WITH ( source_option_key = source_option_value [ , ... ] ) ] | + ( source_query ) } [ [ AS ] source_alias ] ON merge_condition [ WHEN MATCHED [ AND matched_condition ] THEN matched_action ] [ ... ] [ WHEN NOT MATCHED [ BY TARGET ] [ AND not_matched_condition ] THEN not_matched_action ] [ ... ] @@ -69,6 +71,13 @@ not_matched_by_source_action The source of the merge, specified either as a table or as a parenthesized query. An optional alias may be provided with or without the `AS` keyword. +* **WITH ( option_key = option_value [ , ... ] )** + + Specifies dynamic table options for this `MERGE` operation. Options following the target table + are passed to the data source connector for the write operation. Options following the source + table are passed to the connector when reading the source. The supported options depend on the + connector. + * **merge_condition** A boolean expression, introduced by the `ON` keyword, that determines how rows from the source @@ -149,6 +158,17 @@ SELECT * FROM source; +--+------+-----+ ``` +#### Merge Using Dynamic Table Options + +```sql +-- Option names and values are specific to each table's data source connector. +MERGE INTO target t WITH (`write.split-size` = 10) + USING source WITH (`split-size` = 5) s + ON t.pk = s.pk + WHEN MATCHED THEN UPDATE SET * + WHEN NOT MATCHED THEN INSERT *; +``` + #### Update Matched Rows and Insert New Rows ```sql diff --git a/docs/sql-ref-syntax-qry-select.md b/docs/sql-ref-syntax-qry-select.md index a97ee766f2163..4f75388600a1e 100644 --- a/docs/sql-ref-syntax-qry-select.md +++ b/docs/sql-ref-syntax-qry-select.md @@ -53,6 +53,12 @@ SELECT [ hints , ... ] [ ALL | DISTINCT ] { [ [ named_expression | regex_column_ [ QUALIFY boolean_expression ] ``` +A table relation in `from_item` can include dynamic table options: + +```sql +table_identifier [ WITH ( option_key = option_value [ , ... ] ) ] [ [ AS ] table_alias ] +``` + ### Parameters * **with_query** @@ -97,6 +103,11 @@ SELECT [ hints , ... ] [ ALL | DISTINCT ] { [ [ named_expression | regex_column_ * [UNNEST relation](sql-ref-syntax-qry-select-unnest.html) * [ [LATERAL](sql-ref-syntax-qry-select-lateral-subquery.html) ] ( Subquery ) * [File](sql-ref-syntax-qry-select-file.html) + +* **WITH ( option_key = option_value [ , ... ] )** + + Specifies dynamic table options for a table relation. These options are passed to the data + source connector when reading the table. The supported options depend on the connector. * **PIVOT** @@ -191,6 +202,16 @@ SELECT [ hints , ... ] [ ALL | DISTINCT ] { [ [ named_expression | regex_column_ Specifies a hive-style transform query specification to transform the input by forking and running user-specified command or script. +### Examples + +#### Select Using Dynamic Table Options + +```sql +-- Option names and values are specific to the table's +-- data source connector. +SELECT * FROM students WITH (`split-size` = 5); +``` + ### Related Statements * [WHERE Clause](sql-ref-syntax-qry-select-where.html)