[SPARK-58520][SQL] Document dynamic table options in SQL reference

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

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

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)