From 9b6a8b98246a528b311b9093e91f5352400bd0b6 Mon Sep 17 00:00:00 2001 From: panbingkun Date: Wed, 24 Jul 2024 12:21:33 +0900 Subject: [PATCH] [SPARK-48976][SQL][DOCS] Improve the docs related to `variable` ### What changes were proposed in this pull request? The pr aims to improve the docs related to `variable`, includes: - `docs/sql-ref-syntax-aux-set-var.md`, show the `primitive` error messages. - `docs/sql-ref-syntax-ddl-declare-variable.md`, add usage of `DECLARE OR REPLACE`. - `docs/sql-ref-syntax-ddl-drop-variable.md`, show the `primitive` error messages and fix `typo`. ### Why are the changes needed? Only improve docs. ### Does this PR introduce _any_ user-facing change? Yes, make end-user docs clearer. ### How was this patch tested? Manually test. ### Was this patch authored or co-authored using generative AI tooling? No. Closes #47460 from panbingkun/SPARK-48976. Authored-by: panbingkun Signed-off-by: Hyukjin Kwon --- docs/sql-ref-syntax-aux-set-var.md | 2 +- docs/sql-ref-syntax-ddl-declare-variable.md | 11 +++++++++++ docs/sql-ref-syntax-ddl-drop-variable.md | 7 ++++--- 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/sql-ref-syntax-aux-set-var.md b/docs/sql-ref-syntax-aux-set-var.md index 9ce9e68cd4fa3..5a61a970c03fd 100644 --- a/docs/sql-ref-syntax-aux-set-var.md +++ b/docs/sql-ref-syntax-aux-set-var.md @@ -85,7 +85,7 @@ SELECT var1, var2; -- Too many rows SET VAR (var1, var2) = (SELECT c1, CAST(c1 AS STRING) FROM VALUES(1), (2) AS t(c1)); -Error: ROW_SUBQUERY_TOO_MANY_ROWS +[ROW_SUBQUERY_TOO_MANY_ROWS] More than one row returned by a subquery used as a row. SQLSTATE: 21000 -- No rows SET VAR (var1, var2) = (SELECT c1, CAST(c1 AS STRING) FROM VALUES(1), (2) AS t(c1) WHERE 1=0); diff --git a/docs/sql-ref-syntax-ddl-declare-variable.md b/docs/sql-ref-syntax-ddl-declare-variable.md index f4daeb25579d1..518770c4496ea 100644 --- a/docs/sql-ref-syntax-ddl-declare-variable.md +++ b/docs/sql-ref-syntax-ddl-declare-variable.md @@ -72,6 +72,17 @@ DECLARE [ OR REPLACE ] [ VARIABLE ] -- The dense form of declaring a variable with default DECLARE five = 5; +-- Declare a defined variable +DECLARE five = 55; +[VARIABLE_ALREADY_EXISTS] Cannot create the variable `system`.`session`.`five` because it already exists. +Choose a different name, or drop or replace the existing variable. SQLSTATE: 42723 + +-- Use `DECLARE OR REPLACE` to declare a defined variable +DECLARE OR REPLACE five = 55; + +-- Explicitly declare the default value of a variable using the keyword `DEFAULT` +DECLARE VARIABLE size DEFAULT 6; + -- STRING variable initialialized to `NULL` DECLARE some_var STRING; ``` diff --git a/docs/sql-ref-syntax-ddl-drop-variable.md b/docs/sql-ref-syntax-ddl-drop-variable.md index c6cf66769246d..f58d944317d5e 100644 --- a/docs/sql-ref-syntax-ddl-drop-variable.md +++ b/docs/sql-ref-syntax-ddl-drop-variable.md @@ -54,10 +54,11 @@ DROP TEMPORARY VARIABLE var1; -- Try to drop temporary variable which is not present DROP TEMPORARY VARIABLE var1; -Error: VARIABLE_NOT_FOUND -The variable `system`.`session`.`var1` cannot be found. +[VARIABLE_NOT_FOUND] The variable `system`.`session`.`var1` cannot be found. Verify the spelling and correctness of the schema and catalog. +If you did not qualify the name with a schema and catalog, verify the current_schema() output, or qualify the name with the correct schema and catalog. +To tolerate the error on drop use DROP VARIABLE IF EXISTS. SQLSTATE: 42883 --- Drop temporart variable if it exists +-- Drop temporary variable if it exists DROP TEMPORARY VARIABLE IF EXISTS var1; ```