[SPARK-53766][DOC] Improve execute immediate docs

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

Improve documentation for EXECUTE IMMEDIATE

### Why are the changes needed?

EXECUTE IMMEDIATE has been reworked to support more inputs. The existing docs are also a bit terse.

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

No

### How was this patch tested?

Build the docs

### Was this patch authored or co-authored using generative AI tooling?

No

Closes #52494 from srielau/execute-immediate-docs.

Authored-by: Serge Rielau <[email protected]>
Signed-off-by: Gengliang Wang <[email protected]>

Author: srielau

docs/sql-ref-syntax-aux-exec-imm.md

@@ -21,65 +21,84 @@ license: |
 
 ### Description
 
-Executes a sql statement provided as a `STRING`, optionally passing `arg_exprN` to parameter markers and assigning the results to `var_nameN`.
+Executes a SQL statement provided as a `STRING`.
+The statement optionally passes arguments to parameter markers and assigns the results to variables.
 
 ### Syntax
 
 ```sql
 EXECUTE IMMEDIATE sql_string
-        [ INTO var_name [, …]  ]
-        [ USING { (arg_expr [ AS ] [alias] [, …] ) | arg_expr [ AS ] [alias] [, …] } ]
+        [ INTO var_name [, ...] ]
+        [ USING { arg_expr [ AS ] [alias] } [, ...] ]
 ```
 
+For compatibility with other SQL dialects, `EXECUTE IMMEDIATE` also supports `USING ( { arg_expr [ AS ] [alias] } [, ...] )`
+
 ### Parameters
 
 * **sql_string**
 
-  A STRING expression producing a well-formed SQL statement.
+  A constant expression of type `STRING`, producing a well-formed SQL statement.
+
+* **INTO var_name [, ...]**
+
+  Optionally returns the results of a single row query into SQL variables.
+  If the query returns no rows the result is `NULL`.
+
+  If the statement is not a query, Spark raises `INVALID_STATEMENT_FOR_EXECUTE_INTO` error.
+
+  If the query returns more than one row, Spark raises `ROW_SUBQUERY_TOO_MANY_ROWS` error.
 
-* **INTO var_name [, …]**
+  * **var_name**
 
-    Optionally returns the results of a single row query into SQL variables.
-    If the query returns no rows the result is NULL.
-    - `var_name`
     A SQL variable. A variable may not be referenced more than once.
 
-* **USING arg_expr [, …]**
+* **USING { arg_expr [ AS ] [alias] } [, ...]**
 
-  Optionally, if sql_string contains parameter markers, binds in values to the parameters.
-  - `arg_expr`
-  An expression that binds to a parameter marker.
-  If the parameter markers are unnamed the binding is by position.
-  For unnamed parameter markers, binding is by name.
-  - `alias`
-    Overrides the name used to bind `arg_expr` to a named parameter marker
+  Optionally, if `sql_string` contains parameter markers, binds in values to the parameters.
 
-  Each named parameter marker must be matched once. Not all arg_expr must be matched.
+  * **arg_expr**
 
+    A constant expression that binds to a parameter marker.
+    If the parameter markers are unnamed, the binding is by position.
+    For named parameter markers, binding is by name.
+
+  * **alias**
+
+    Overrides the name used to bind `arg_expr` to a named parameter marker.
+    Each named parameter marker must be matched once. Not all `arg_expr` must be matched.
 
 ### Examples
 
 ```sql
 -- A self-contained execution using a literal string
-EXECUTE IMMEDIATE 'SELECT SUM(col1) FROM VALUES(?), (?)' USING 5, 6;
+EXECUTE IMMEDIATE 'SELECT SUM(c1) FROM VALUES(?), (?) AS t(c1)' USING 5, 6;
  11
 
 -- A SQL string composed in a SQL variable
-DECLARE sqlStr = 'SELECT SUM(col1) FROM VALUES(?), (?)';
+DECLARE sqlStr = 'SELECT SUM(c1) FROM VALUES(?), (?) AS t(c1)';
 DECLARE arg1 = 5;
 DECLARE arg2 = 6;
 EXECUTE IMMEDIATE sqlStr USING arg1, arg2;
  11
 
 -- Using the INTO clause
 DECLARE sum INT;
+DECLARE sqlStr = 'SELECT SUM(c1) FROM VALUES(:first), (:second) AS t(c1)';
 EXECUTE IMMEDIATE sqlStr INTO sum USING arg1, arg2;
 SELECT sum;
  11
 
 -- Using named parameter markers
-SET VAR sqlStr = 'SELECT SUM(col1) FROM VALUES(:first), (:second)';
-EXECUTE IMMEDIATE sqlStr INTO sum USING 5 AS first, arg2 AS second;
+DECLARE sum INT;
+DECLARE sqlStr = 'SELECT SUM(c1) FROM VALUES(:first), (:second) AS t(c1)';
+EXECUTE IMMEDIATE sqlStr INTO sum USING (5 AS first, arg2 AS second);
 SELECT sum;
  11
+
+-- Using constant expressions
+DECLARE foo = 'sum';
+EXECUTE IMMEDIATE 'SELECT ' || foo || '(c1) FROM VALUES(?), (?) AS t(c1)'
+   USING 5 + 6, 7 + length('hello');
+ 33
 ```

docs/sql-ref-syntax.md

@@ -101,6 +101,7 @@ ability to generate logical and physical plan for a given query using
  * [DESCRIBE FUNCTION](sql-ref-syntax-aux-describe-function.html)
  * [DESCRIBE QUERY](sql-ref-syntax-aux-describe-query.html)
  * [DESCRIBE TABLE](sql-ref-syntax-aux-describe-table.html)
+ * [EXECUTE IMMEDIATE](sql-ref-syntax-aux-exec-imm.html)
  * [LIST FILE](sql-ref-syntax-aux-resource-mgmt-list-file.html)
  * [LIST JAR](sql-ref-syntax-aux-resource-mgmt-list-jar.html)
  * [REFRESH](sql-ref-syntax-aux-cache-refresh.html)
@@ -109,7 +110,6 @@ ability to generate logical and physical plan for a given query using
  * [RESET](sql-ref-syntax-aux-conf-mgmt-reset.html)
  * [SET](sql-ref-syntax-aux-conf-mgmt-set.html)
  * [SET VAR](sql-ref-syntax-aux-set-var.html)
- * [EXECUTE IMMEDIATE](sql-ref-syntax-aux-exec-imm.html)
  * [SHOW COLUMNS](sql-ref-syntax-aux-show-columns.html)
  * [SHOW CREATE TABLE](sql-ref-syntax-aux-show-create-table.html)
  * [SHOW DATABASES](sql-ref-syntax-aux-show-databases.html)