[SPARK-51765][DOCS][4.1] Document SQL Scripting Syntax

docs/_data/menu-sql.yaml

@@ -99,6 +99,10 @@
       url: sql-ref-literals.html
     - text: Null Semantics
       url: sql-ref-null-semantics.html
+    - text: Name Resolution
+      url: sql-ref-name-resolution.html
+    - text: SQL Scripting
+      url: sql-ref-scripting.html
     - text: SQL Syntax
       url: sql-ref-syntax.html
       subitems:
@@ -108,6 +112,8 @@
           url: sql-ref-syntax.html#dml-statements
         - text: Data Retrieval(Queries)
           url: sql-ref-syntax.html#data-retrieval-statements
+        - text: SQL Scripting Statements
+          url: sql-ref-syntax.html#sql-scripting-statements
         - text: Auxiliary Statements
           url: sql-ref-syntax.html#auxiliary-statements
         - text: Pipe Syntax

docs/control-flow/case-stmt.md

@@ -0,0 +1,102 @@
+---
+layout: global
+title: CASE statement
+displayTitle: CASE statement
+license: |
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+---
+
+Executes `thenStmtN` for the first `optN` that equals `expr` or `elseStmt` if no `optN` matches `expr`.
+This is called a _simple case statement_.
+
+Executes `thenStmtN` for the first `condN` evaluating to `true`, or `elseStmt` if no `condN` evaluates to `true`.
+This is called a _searched case statement_.
+
+For case expressions that yield result values, see `CASE expression`)
+
+This statement may only be used within a [compound statement](compound-stmt.html).
+
+## Syntax
+
+```
+CASE expr
+  { WHEN opt THEN { thenStmt ; } [...] } [...]
+  [ ELSE { elseStmt ; } [...] ]
+END CASE
+
+CASE
+  { WHEN cond THEN { thenStmt ; } [...] } [...]
+  [ ELSE { elseStmt ; } [...] ]
+END CASE
+```
+
+## Parameters
+
+- **`expr`**: Any expression for which a comparison is defined.
+- **`opt`**: An expression with a least common type with `expr` and all other `optN`.
+- **`thenStmt`**: A SQL Statement to execute if preceding condition is `true`.
+- **`elseStmt`**: A SQL Statement to execute if no condition is `true`.
+- **`cond`**: A `BOOLEAN` expression.
+
+Conditions are evaluated in order, and only the first set of `stmt` for which `opt` or `cond` evaluate to true will be executed.
+
+## Examples
+
+```SQL
+-- a simple case statement
+> BEGIN
+    DECLARE choice INT DEFAULT 3;
+    DECLARE result STRING;
+    CASE choice
+      WHEN 1 THEN
+        VALUES ('one fish');
+      WHEN 2 THEN
+        VALUES ('two fish');
+      WHEN 3 THEN
+        VALUES ('red fish');
+      WHEN 4 THEN
+        VALUES ('blue fish');
+      ELSE
+        VALUES ('no fish');
+    END CASE;
+  END;
+ red fish
+
+-- A searched case statement
+> BEGIN
+    DECLARE choice DOUBLE DEFAULT 3.9;
+    DECLARE result STRING;
+    CASE
+      WHEN choice < 2 THEN
+        VALUES ('one fish');
+      WHEN choice < 3 THEN
+        VALUES ('two fish');
+      WHEN choice < 4 THEN
+        VALUES ('red fish');
+      WHEN choice < 5 OR choice IS NULL THEN
+        VALUES ('blue fish');
+      ELSE
+        VALUES ('no fish');
+    END CASE;
+  END;
+ red fish
+```
+
+## Related articles
+
+- [SQL Scripting](../sql-ref-scripting.html)
+- [compound statement](compound-stmt.html)
+- [IF statement](if-stmt.html)

docs/control-flow/compound-stmt.md

@@ -0,0 +1,164 @@
+---
+layout: global
+title: compound statement
+displayTitle: compound statement
+license: |
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+---
+
+Implements a SQL Script block that can contain a sequence of SQL statements, control-of-flow statements, local variable declarations, and exception handlers.
+
+## Syntax
+
+```
+[ label : ]
+      BEGIN
+      [ { declare_variable | declare_condition } ; [...] ]
+      [ declare_handler ; [...] ]
+      [ SQL_statement ; [...] ]
+      END [ label ]
+
+declare_variable
+  DECLARE variable_name [, ...] datatype [ DEFAULT default_expr ]
+
+declare_condition
+  DECLARE condition_name CONDITION [ FOR SQLSTATE [ VALUE ] sqlstate ]
+
+declare_handler
+  DECLARE handler_type HANDLER FOR condition_values handler_action
+
+handler_type
+  EXIT
+
+condition_values
+ { { SQLSTATE [ VALUE ] sqlstate | condition_name } [, ...] |
+   { SQLEXCEPTION | NOT FOUND } [, ...] }
+```
+
+## Parameters
+
+- **`label`**
+
+  An optional identifier is used to qualify variables defined within the compound and to leave the compound.
+  Both label occurrences must match, and the `END` label can only be specified if `label:` is specified.
+
+  `label` must not be specified for a top level compound statement.
+
+- **`NOT ATOMIC`**
+
+  Specifies that, if an SQL statement within the compound fails, previous SQL statements will not be rolled back.
+  This is the default and only behavior.
+
+- **`declare_variable`**
+
+  A local variable declaration for one or more variables
+
+  - **`variable_name`**
+
+    A name for the variable.
+    The name must not be qualified, and be unique within the compound statement.
+
+  - **`data_type`**
+
+    Any supported data type. If data_type is omitted, you must specify DEFAULT, and the type is derived from the default_expression.
+
+  - **`{ DEFAULT | = } default_expression`**
+
+    Defines the variable's initial value after declaration. default_expression must be castable to data_type. If no default is specified, the variable is initialized with NULL.
+
+- **`Declare_condition`**
+
+  A local condition declaration
+
+  - **`condition_name`**
+
+    The unqualified name of the condition is scoped to the compound statement.
+
+  - **`sqlstate`**
+
+    A `STRING` literal of 5 alphanumeric characters (case insensitive) consisting of A-Z and 0..9. The SQLSTATE must not start with ‘00’, ‘01’, or ‘XX’. Any SQLSTATE starting with ‘02’ will be caught by the predefined NOT FOUND exception as well. If not specified, the SQLSTATE is ‘45000’.
+
+- **`declare_handler`**
+
+  A declaration for an error handler.
+
+  - **`handler_type`**
+
+    - **`EXIT`**
+
+      Classifies the handler to exit the compound statement after the condition is handled.
+
+  - **`condition_values`**
+
+    Specifies to which sqlstates or conditions the handler applies.
+    Condition values must be unique within all handlers within the compound statement.
+    Specific condition values take precedence over `SQLEXCEPTION`.
+
+  - **`sqlstate`**
+
+    A `STRING` literal of 5 characters `'A'-'Z'` and `'0'-'9'` (case insensitive).
+
+  - **`condition_name`**
+
+    A condition defined within this compound, an outer compound statement, or a system-defined error class.
+
+  - **`SQLEXCEPTION`**
+
+    Applies to any user-facing error condition.
+
+  - **`NOT FOUND`**
+
+    Applies to any error condition with a SQLSTATE ‘02’ class.
+
+  - **`handler_action`**
+
+    A SQL statement to execute when any of the condition values occur.
+    To add multiple statements, use a nested compound statement.
+
+- **`SQL_statement`**
+
+  A SQL statement such as a DDL, DML, control statement, or compound statement.
+  Any `SELECT` or `VALUES` statement produces a result set that the invoker can consume.
+
+## Examples
+
+```SQL
+-- A compound statement with local variables, and exit hanlder and a nested compound.
+> BEGIN
+    DECLARE a INT DEFAULT 1;
+    DECLARE b INT DEFAULT 5;
+    DECLARE EXIT HANDLER FOR DIVIDE_BY_ZERO
+      div0: BEGIN
+        VALUES (15);
+      END div0;
+    SET a = 10;
+    SET a = b / 0;
+    VALUES (a);
+END;
+15
+```
+
+## Related articles
+
+- [SQL Scripting](../sql-ref-scripting.html)
+- [CASE Statement](../control-flow/case-stmt.html)
+- [IF Statement](../control-flow/if-stmt.html)
+- [LOOP Statement](../control-flow/loop-stmt.html)
+- [WHILE Statement](../control-flow/while-stmt.html)
+- [REPEAT Statement](../control-flow/repeat-stmt.html)
+- [FOR Statement](../control-flow/for-stmt.html)
+- [ITERATE Statement](../control-flow/iterate-stmt.html)
+- [LEAVE Statement](../control-flow/leave-stmt.html)

docs/control-flow/for-stmt.md

@@ -0,0 +1,92 @@
+---
+layout: global
+title: FOR statement
+displayTitle: FOR statement
+license: |
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+---
+
+Repeat the execution of a list of statements for each row returned by query.
+
+This statement may only be used within a [compound statement](compound-stmt.html).
+
+## Syntax
+
+```
+[ label : ] FOR [ variable_name AS ] query
+  DO
+  { stmt ; } [...]
+  END FOR [ label ]
+```
+
+## Parameters
+
+- **label**
+
+  An optional label for the loop which is unique amongst all labels for statements within which the `FOR` statement is contained.
+  If an end label is specified, it must match the beginning label.
+  The label can be used to [LEAVE](leave-stmt.html) or [ITERATE](iterate-stmt.html) the loop.
+  To qualify loop column references, use the `variable_name`, not the `label`.
+
+- **variable_name**
+
+  An optional name you can use as a qualifier when referencing the columns in the cursor.
+
+- **stmt**
+
+  A SQL statement
+
+## Notes
+
+If the query operates on a table that is also modified within the loop's body, the semantics depend on the data source.
+For Delta tables, the query will remain unaffected.
+Spark does not guarantee the full execution of the query if the `FOR` loop completes prematurely due to a `LEAVE` statement or an error condition.
+When exceptions or side-effects occur during the execution of the query, Spark does not guarantee at which point in time within the loop these occur.
+Often `FOR` loops can be replaced with relational queries, which are typically more efficient.
+
+## Examples
+
+```SQL
+-- sum up all odd numbers from 1 through 10
+> BEGIN
+    DECLARE sum INT DEFAULT 0;
+    sumNumbers: FOR row AS SELECT num FROM range(1, 20) AS t(num) DO
+      IF num > 10 THEN
+         LEAVE sumNumbers;
+      ELSEIF num % 2 = 0 THEN
+        ITERATE sumNumbers;
+      END IF;
+      SET sum = sum + row.num;
+    END FOR sumNumbers;
+    VALUES (sum);
+  END;
+ 25
+
+-- Compare with the much more efficient relational computation:
+> SELECT sum(num) FROM range(1, 10) AS t(num) WHERE num % 2 = 1;
+ 25
+```
+
+## Related articles
+
+- [SQL Scripting](../sql-ref-scripting.html)
+- [CASE Statement](../control-flow/case-stmt.html)
+- [Compound Statement](../control-flow/compound-stmt.html)
+- [LOOP Statement](../control-flow/loop-stmt.html)
+- [WHILE Statement](../control-flow/while-stmt.html)
+- [REPEAT Statement](../control-flow/repeat-stmt.html)
+- [LEAVE Statement](../control-flow/leave-stmt.html)
+- [ITERATE Statement](../control-flow/iterate-stmt.html)