Add documentation for SQL functions

- Add documentation for CREATE FUNCTION, ALTER FUNCTION, and DROP
  FUNCTION statements.
- Add documentation for Function Namespace Managers configuration.

presto-docs/src/main/sphinx/admin.rst

@@ -11,4 +11,5 @@ Administration
     admin/spill
     admin/resource-groups
     admin/session-property-managers
+    admin/function-namespace-managers
     admin/dist-sort

presto-docs/src/main/sphinx/admin/function-namespace-managers.rst

@@ -0,0 +1,92 @@
+===========================
+Function Namespace Managers
+===========================
+
+.. warning::
+
+    This is an experimental feature being actively developed. The way
+    Function Namespace Managers are configured might be changed.
+
+Function namespace managers support storing and retrieving SQL
+functions, allowing the Presto engine to perform actions such as
+creating, altering, deleting functions.
+
+A function namespace is in the format of ``catalog.schema`` (e.g.
+``example.test``). It can be thought of as a schema for storing
+functions. However, it is not a full fledged schema as it does not
+support storing tables and views, but only functions.
+
+Each Presto function, whether built-in or user-defined, resides in
+a function namespace. All built-in functions reside in the
+``presto.default`` function namespace. The qualified function name of
+a function is the function namespace in which it reside followed by
+its function name (e.g. ``example.test.func``). Built-in functions can
+be referenced in queries with their function namespaces omitted, while
+user-defined functions needs to be referenced by its qualified function
+name. A function is uniquely identified by its qualified function name
+and parameter type list.
+
+Each function namespace manager binds to a catalog name and manages all
+functions within that catalog. Using the catalog name of an existing
+connector is discouraged, as the behavior is not defined nor tested,
+and will be disallowed in the future.
+
+Currently, those catalog names do not correspond to real catalogs.
+They cannot be specified as the catalog in a session, nor do they
+support :doc:`/sql/create-schema`, :doc:`/sql/alter-schema`,
+:doc:`/sql/drop-schema`, or :doc:`/sql/show-schemas`. Instead,
+namespaces can be added using the methods described below.
+
+
+Configuration
+-------------
+
+Presto currently stores all function namespace manager related
+information in MySQL.
+
+To instantiate a MySQL-based function namespace manager that manages
+catalog ``example``, administrator needs to first have a running MySQL
+server. Suppose the MySQL server can be reached at ``localhost:1080``,
+add a file ``etc/function-namespace/example.properties`` with the
+following contents::
+
+    function-namespace-manager.name=mysql
+    database-url=localhost:1080
+    function-namespaces-table-name=example_function_namespaces
+    functions-table-name=example_sql_functions
+
+When Presto first starts with the above MySQL function namespace
+manager configuration, two MySQL tables will be created if they do
+not exist.
+
+- ``example_function_namespaces`` stores function namespaces of
+  the catalog ``example``.
+- ``example_sql_functions`` stores SQL-invoked functions of the
+  catalog ``example``.
+
+Multiple function namespace managers can be instantiated by placing
+multiple properties files under ``etc/function-namespace``. They
+may be configured to use the same tables. If so, each manager will
+only create and interact with entries of the catalog to which it binds.
+
+To create a new function namespace, insert into the
+``example_function_namespaces`` table::
+
+    INSERT INTO example_function_namespaces (catalog_name, schema_name)
+    VALUES('example', 'test');
+
+
+Configuration Reference
+-----------------------
+
+``function-namespace-manager.name`` is the type of the function namespace manager to instantiate. Currently, only ``mysql`` is supported.
+
+The following table lists all configuration properties supported by the MySQL function namespace manager.
+
+=========================================== ==================================================================================================
+Name                                        Description
+=========================================== ==================================================================================================
+``database-url``                            The URL of the MySQL database used by the MySQL function namespace manager.
+``function-namespaces-table-name``          The name of the table that stores all the function namespaces managed by this manager.
+``functions-table-name``                    The name of the table that stores all the functions managed by this manager.
+=========================================== ==================================================================================================

presto-docs/src/main/sphinx/sql.rst

@@ -7,11 +7,13 @@ This chapter describes the SQL syntax used in Presto.
 .. toctree::
     :maxdepth: 1
 
+    sql/alter-function
     sql/alter-schema
     sql/alter-table
     sql/analyze
     sql/call
     sql/commit
+    sql/create-function
     sql/create-role
     sql/create-schema
     sql/create-table
@@ -22,6 +24,7 @@ This chapter describes the SQL syntax used in Presto.
     sql/describe
     sql/describe-input
     sql/describe-output
+    sql/drop-function
     sql/drop-role
     sql/drop-schema
     sql/drop-table

presto-docs/src/main/sphinx/sql/alter-function.rst

@@ -0,0 +1,43 @@
+==============
+ALTER FUNCTION
+==============
+
+Synopsis
+--------
+
+.. code-block:: none
+
+    ALTER FUNCTION qualified_function_name [ ( parameter_type[, ...] ) ]
+    RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT
+
+
+Description
+-----------
+
+Alter the definition of an existing function.
+
+Parameter type list must be specified if multiple signatures exist
+for the specified function name. If exactly one signature exists for
+the specified function name, parameter type list can be omitted.
+
+Currently, only modifying the null-call clause is supported.
+
+
+Examples
+--------
+
+Change the null-call clause of a function ``example.default.tan(double)``::
+
+    ALTER FUNCTION prod.default.tan(double)
+    CALLED ON NULL INPUT
+
+If only one function exists for ``example.default.tan``, parameter type list may be omitted::
+
+    ALTER FUNCTION prod.default.tan
+    CALLED ON NULL INPUT
+
+
+See Also
+--------
+
+:doc:`create-function`, :doc:`drop-function`, :doc:`show-functions`

presto-docs/src/main/sphinx/sql/create-function.rst

@@ -0,0 +1,84 @@
+===============
+CREATE FUNCTION
+===============
+
+Synopsis
+--------
+
+.. code-block:: none
+
+    CREATE [ OR REPLACE ] FUNCTION
+    qualified_function_name (
+      parameter_name parameter_type
+      [, ...]
+    )
+    RETURNS return_type
+    [ COMMENT function_description ]
+    [ LANGUAGE SQL ]
+    [ DETERMINISTIC | NOT DETERMINISTIC ]
+    [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]
+    [ RETURN expression ]
+
+
+Description
+-----------
+
+Create a new function with the specified definition.
+
+Each function is uniquely identified by its qualified function name
+and its parameter type list. ``qualified_function_name`` needs to be in
+the format of ``catalog.schema.function_name``.
+
+In order to create a function, the corresponding function namespace
+(in the format ``catalog.schema``) must first be managed by a function
+namespace manager (See :doc:`/admin/function-namespace-managers`).
+
+The optional ``OR REPLACE`` clause causes the query to quietly replace
+the existing function if a function with the identical signature (function
+name with parameter type list) exists.
+
+The ``return_type`` needs to match the actual type of the routine body
+``expression``, without performing type coercion.
+
+A set of routine characteristics can be specified to decorate the
+function and specify its behavior. Each kind of routine characteristic
+can be specified at most once.
+
+============================ ======================== ================================================================
+Routine Characteristic       Default Value            Description
+============================ ======================== ================================================================
+Language clause              SQL                      The language in which the function is defined.
+Deterministic characteristic NOT DETERMINISTIC        Whether the function is deterministic. ``NOT DETERMINISTIC``
+                                                      means that the function is possibly non-deterministic.
+Null-call clause             CALLED ON NULL INPUT     The behavior of the function in which ``null`` is supplied as
+                                                      the value of at least one argument.
+============================ ======================== ================================================================
+
+
+Examples
+--------
+
+Create a new function ``example.default.tan(double)``::
+
+    CREATE FUNCTION example.default.tan(x double)
+    RETURNS double
+    DETERMINISTIC
+    RETURNS NULL ON NULL INPUT
+    RETURN sin(x) / cos(x)
+
+Create the table ``example.default.tan(double)`` if it does not already
+exist, adding a function description and explicitly listing all the supported
+routine characteristics::
+
+    CREATE OR REPLACE FUNCTION example.default.tan(x double)
+    RETURNS double
+    COMMENT 'tangent trigonometric function'
+    LANGUAGE SQL
+    DETERMINISTIC
+    RETURNS NULL ON NULL INPUT
+    RETURN sin(x) / cos(x)
+
+See Also
+--------
+
+:doc:`alter-function`, :doc:`drop-function`, :doc:`show-functions`

presto-docs/src/main/sphinx/sql/drop-function.rst

@@ -0,0 +1,45 @@
+=============
+DROP FUNCTION
+=============
+
+Synopsis
+--------
+
+.. code-block:: none
+
+    DROP FUNCTION [ IF EXISTS ] qualified_function_name [ ( parameter_type[, ...] ) ]
+
+
+Description
+-----------
+
+Drop an existing function.
+
+The optional ``IF EXISTS`` clause causes the ``NOT_FOUND`` error
+to be suppressed if the function does not exists.
+
+Each ``DROP FUNCTION`` statement can only drop one function
+at a time. If multiple functions are matched by not specifying
+the parameter type list, the query would fail.
+
+
+Examples
+--------
+
+Drop the function ``example.default.tan(double)``::
+
+    DROP FUNCTION example.default.tan(double)
+
+If only one function exists for ``example.default.tan``, parameter type list may be omitted::
+
+    DROP FUNCTION example.default.tan
+
+Drop the function ``example.default.tan(double)`` if it exists::
+
+    DROP FUNCTION IF EXISTS example.default.tan(double)
+
+
+See Also
+--------
+
+:doc:`create-function`, :doc:`alter-function`, :doc:`show-functions`