This is an automated email from the ASF dual-hosted git repository.
gengliang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/spark.git
The following commit(s) were added to refs/heads/master by this push:
new 0e9e27d6a495 [SPARK-53766][DOC] Improve execute immediate docs
0e9e27d6a495 is described below
commit 0e9e27d6a495ffb44c6ef0ebb57c9bebe98f11e3
Author: Serge Rielau <[email protected]>
AuthorDate: Tue Sep 30 12:48:07 2025 -0700
[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]>
---
docs/sql-ref-syntax-aux-exec-imm.md | 61 ++++++++++++++++++++++++-------------
docs/sql-ref-syntax.md | 2 +-
2 files changed, 41 insertions(+), 22 deletions(-)
diff --git a/docs/sql-ref-syntax-aux-exec-imm.md
b/docs/sql-ref-syntax-aux-exec-imm.md
index 904a676605c8..be8f31d3118c 100644
--- a/docs/sql-ref-syntax-aux-exec-imm.md
+++ b/docs/sql-ref-syntax-aux-exec-imm.md
@@ -21,51 +21,62 @@ 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;
@@ -73,13 +84,21 @@ EXECUTE IMMEDIATE sqlStr USING arg1, arg2;
-- 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
```
\ No newline at end of file
diff --git a/docs/sql-ref-syntax.md b/docs/sql-ref-syntax.md
index 1837f22a57f3..3dc7d47c4f45 100644
--- a/docs/sql-ref-syntax.md
+++ b/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)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
