Add documentation for SQL routines

docs/src/main/sphinx/admin/properties-sql-environment.md

@@ -0,0 +1,53 @@
+# SQL environment properties
+
+SQL environment properties allow you to globally configure parameters relevant
+to all SQL queries and the context they are processed in.
+
+## `sql.forced-session-time-zone`
+
+- **Type:** [](prop-type-string)
+
+Force the time zone for any query processing to the configured value, and
+therefore override the time zone of the client. The time zone must be specified
+as a string such as `UTC` or [other valid
+values](timestamp-p-with-time-zone-data-type).
+
+## `sql.default-catalog`
+
+- **Type:** [](prop-type-string)
+
+Set the default catalog for all clients. Any default catalog configuration
+provided by a client overrides this default.
+
+## `sql.default-schema`
+
+- **Type:** [](prop-type-string)
+
+Set the default schema for all clients. Must be set to a schema name that is
+valid for the default catalog. Any default schema configuration provided by a
+client overrides this default.
+
+## `sql.default-function-catalog`
+
+- **Type:** [](prop-type-string)
+
+Set the default catalog for [SQL routine](/routines) storage for all clients.
+The connector used in the catalog must support [](sql-routine-management). Any
+usage of a fully qualified name for a routine overrides this default.
+
+## `sql.default-function-schema`
+
+- **Type:** [](prop-type-string)
+
+Set the default schema for SQL routine storage for all clients. Must be set to a
+schema name that is valid for the default function catalog. Any usage of a fully
+qualified name for a routine overrides this default.
+
+## `sql.path`
+
+- **Type:** [](prop-type-string)
+
+Define the default collection of paths to functions or table functions in
+specific catalogs and schemas. Paths are specified as
+`catalog_name.schema_name`. Multiple paths must be separated by commas. Find
+more details about the path in [](/sql/set-path).

docs/src/main/sphinx/admin/properties.md

@@ -17,6 +17,7 @@ properties, refer to the {doc}`connector documentation </connector/>`.
 General <properties-general>
 Resource management <properties-resource-management>
 Query management <properties-query-management>
+SQL environment <properties-sql-environment>
 Spilling <properties-spilling>
 Exchange <properties-exchange>
 Task <properties-task>

docs/src/main/sphinx/connector/hive.md

@@ -384,6 +384,7 @@ configured object storage system and metadata stores:
   - {ref}`sql-view-management`; see also
     {ref}`Hive-specific view management <hive-sql-view-management>`
 
+- [](sql-routine-management)
 - {ref}`sql-security-operations`: see also
   {ref}`SQL standard-based authorization for object storage <hive-sql-standard-based-authorization>`
 

docs/src/main/sphinx/connector/memory.md

@@ -67,6 +67,7 @@ statements, the connector supports the following features:
 - {doc}`/sql/create-schema`
 - {doc}`/sql/drop-schema`
 - {doc}`/sql/comment`
+- [](sql-routine-management)
 
 ### DROP TABLE
 

docs/src/main/sphinx/index.md

@@ -13,6 +13,7 @@ connector
 functions
 language
 sql
+routines
 develop
 glossary
 appendix

docs/src/main/sphinx/language/sql-support.md

@@ -116,6 +116,15 @@ connector to connector:
 - {doc}`/sql/drop-view`
 - {doc}`/sql/alter-view`
 
+(sql-routine-management)=
+### Routine management
+
+The following statements are used to manage [catalog routines](routine-catalog):
+
+- [](/sql/create-function)
+- [](/sql/drop-function)
+- [](/sql/show-functions)
+
 (sql-security-operations)=
 
 ## Security operations

docs/src/main/sphinx/language/types.md

@@ -271,12 +271,13 @@ SELECT cast(TIMESTAMP '2020-06-10 15:55:23.383345' as TIMESTAMP(12));
 `TIMESTAMP WITH TIME ZONE` is an alias for `TIMESTAMP(3) WITH TIME ZONE`
 (millisecond precision).
 
+(timestamp-p-with-time-zone-data-type)=
 ### `TIMESTAMP(P) WITH TIME ZONE`
 
 Instant in time that includes the date and time of day with `P` digits of
-precision for the fraction of seconds and with a time zone. Values of this
-type are rendered using the time zone from the value.
-Time zones can be expressed in the following ways:
+precision for the fraction of seconds and with a time zone. Values of this type
+are rendered using the time zone from the value. Time zones can be expressed in
+the following ways:
 
 - `UTC`, with `GMT`, `Z`, or `UT` usable as aliases for UTC.
 - `+hh:mm` or `-hh:mm` with `hh:mm` as an hour and minute offset from UTC.

docs/src/main/sphinx/routines.md

@@ -0,0 +1,23 @@
+# SQL routines
+
+A SQL routine is a custom, user-defined function authored by a user of Trino in
+a client and written in SQL. More details are available in the following sections:
+
+```{toctree}
+:maxdepth: 1
+
+Introduction <routines/introduction>
+Examples <routines/examples>
+routines/begin
+routines/case
+routines/declare
+routines/function
+routines/if
+routines/iterate
+routines/leave
+routines/loop
+routines/repeat
+routines/return
+routines/set
+routines/while
+```

docs/src/main/sphinx/routines/begin.md

@@ -0,0 +1,57 @@
+# BEGIN
+
+## Synopsis
+
+```text
+BEGIN
+  [ DECLARE ... ]
+  statements
+END
+```
+
+## Description
+
+Marks the start and end of a block in a [SQL routine](/routines/introduction).
+`BEGIN` can be used wherever a statement can be used to group multiple
+statements together and to declare variables local to the block. A typical use
+case is as first statement within a [](/routines/function). Blocks can also be
+nested.
+
+After the `BEGIN` keyword, you can add variable declarations using
+[/routines/declare] statements, followed by one or more statements that define
+the main body of the routine, separated by `;`. The following statements can be
+used:
+
+* [](/routines/case)
+* [](/routines/if)
+* [](/routines/iterate)
+* [](/routines/leave)
+* [](/routines/loop)
+* [](/routines/repeat)
+* [](/routines/return)
+* [](/routines/set)
+* [](/routines/while)
+* Nested [](/routines/begin) blocks
+
+## Examples
+
+The following example computes the value `42`:
+
+```sql
+FUNCTION meaning_of_life()
+  RETURNS tinyint
+  BEGIN
+    DECLARE a tinyint DEFAULT 6;
+    DECLARE b tinyint DEFAULT 7;
+    RETURN a * b;
+  END
+```
+
+Further examples of varying complexity that cover usage of the `BEGIN` statement
+in combination with other statements are available in the [SQL routines examples
+documentation](/routines/examples).
+
+## See also
+
+* [](/routines/introduction)
+* [](/routines/function)

docs/src/main/sphinx/routines/case.md

@@ -0,0 +1,61 @@
+# CASE
+
+## Synopsis
+
+Simple case:
+
+```text
+CASE
+  WHEN condition THEN statements
+  [ ... ]
+  [ ELSE statements ]
+END CASE
+```
+
+Searched case:
+
+```text
+CASE expression
+  WHEN expression THEN statements
+  [ ... ]
+  [ ELSE statements ]
+END
+```
+
+## Description
+
+The `CASE` statement is an optional construct to allow conditional processing
+in [SQL routines](/routines/introduction).
+
+The `WHEN` clauses are evaluated sequentially, stopping after the first match,
+and therefore the order of the statements is significant. The statements of the
+`ELSE` clause are executed if none of the `WHEN` clauses match.
+
+Unlike other languages like C or Java, SQL does not support case fall through,
+so processing stops at the end of the first matched case.
+
+One or more `WHEN` clauses can be used.
+
+## Examples
+
+The following example shows a simple `CASE` statement usage:
+
+```sql
+FUNCTION simple_case(a bigint)
+  RETURNS varchar
+  BEGIN
+    CASE a
+      WHEN 0 THEN RETURN 'zero';
+      WHEN 1 THEN RETURN 'one';
+      ELSE RETURN 'more than one or negative';
+    END CASE;
+  END
+```
+
+Further examples of varying complexity that cover usage of the `CASE` statement
+in combination with other statements are available in the [SQL routines examples
+documentation](/routines/examples).
+
+## See also
+
+* [](/routines/introduction)

docs/src/main/sphinx/routines/declare.md

@@ -0,0 +1,52 @@
+# DECLARE
+
+## Synopsis
+
+```text
+DECLARE identifier [, ...] type [ DEFAULT expression ]
+```
+
+## Description
+
+Use the `DECLARE` statement directly after the [](/routines/begin) keyword in
+[](/routines) to define one or more variables with an `identifier` as name. Each
+statement must specify the [data type](/language/types) of the variable with
+`type`. It can optionally include a default, initial value defined by an
+`expression`. The default value is `NULL` if not specified.
+
+## Examples
+
+A simple declaration of the variable `x` with the `tinyint` data type and the
+implicit default value of `null`:
+
+```sql
+DECLARE x tinyint;
+```
+
+A declaration of multiple string variables with length restricted to 25
+characters:
+
+```sql
+DECLARE first_name, last_name, middle_name varchar(25);
+```
+
+A declaration of a fixed-precision decimal number with a default value:
+
+```sql
+DECLARE uptime_requirement decimal DEFAULT 99.999;
+```
+
+A declaration with a default value from an expression:
+
+```sql
+DECLARE start_time timestamp(3) with time zone DEFAULT now();
+```
+
+Further examples of varying complexity that cover usage of the `DECLARE`
+statement in combination with other statements are available in the [SQL
+routines examples documentation](/routines/examples).
+
+## See also
+
+* [](/routines/introduction)
+* [](/language/types)