.. meta:: :description: Manage custom functions with the Hasura metadata API :keywords: hasura, docs, metadata API, API reference, custom function .. _metadata_api_custom_functions: Metadata API Reference: Custom Functions ======================================== .. contents:: Table of contents :backlinks: none :depth: 1 :local: Introduction ------------ Track/untrack a custom SQL function in the Hasura GraphQL engine. Only tracked custom functions are available for querying/mutating/subscribing data over the GraphQL API. .. admonition:: Supported from The metadata API is supported for versions ``v2.0.0`` and above and replaces the older :ref:`schema/metadata API `. .. _metadata_pg_track_function: pg_track_function ----------------- ``pg_track_function`` is used to add a custom SQL function to the GraphQL schema. It supports more configuration options than v1, and also supports tracking functions as mutations. Also refer a note :ref:`here `. Track an SQL function called ``search_articles`` with a Hasura session argument: .. code-block:: http POST /v1/metadata HTTP/1.1 Content-Type: application/json X-Hasura-Role: admin { "type": "pg_track_function", "args": { "source": "default", "function": { "schema": "public", "name": "search_articles" }, "configuration": { "session_argument": "hasura_session" }, "comment": "This function helps search for articles" } } Track ``VOLATILE`` SQL function ``reset_widget`` as a mutation, so it appears as a top-level field under the ``mutation`` root field: .. code-block:: http POST /v1/metadata HTTP/1.1 Content-Type: application/json X-Hasura-Role: admin { "type": "pg_track_function", "args": { "function": { "schema": "public", "name": "reset_widget" }, "configuration": { "exposed_as": "mutation" }, "source": "default" } } If ``exposed_as`` is omitted, the location in the schema to expose the function will be inferred from the function's volatility, with ``VOLATILE`` functions appearing under the ``mutation`` root, and others ending up under ``query/subscription``. In most cases you will want ``VOLATILE`` functions to only be exposed as mutations, and only ``STABLE`` and ``IMMUTABLE`` functions to be queries. When tracking ``VOLATILE`` functions under the ``query`` root, the user needs to guarantee that the field is idempotent and side-effect free, in the context of the resulting GraphQL API. One such use case might be a function that wraps a simple query and performs some logging visible only to administrators. .. note:: It's easy to accidentally give an SQL function the wrong volatility (or for a function to end up with ``VOLATILE`` mistakenly, since it's the default). .. _metadata_pg_track_function_syntax: Args syntax ^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - Key - Required - Schema - Description * - function - true - :ref:`FunctionName ` - Name of the SQL function * - configuration - false - :ref:`Function Configuration ` - Configuration for the SQL function * - source - false - :ref:`SourceName ` - Name of the source database of the function (default: ``default``) * - comment - false - String - Comment for the function. This comment would replace the auto-generated comment for the function field in the GraphQL schema. .. _metadata_pg_untrack_function: pg_untrack_function ------------------- ``pg_untrack_function`` is used to remove a SQL function from the GraphQL schema. Remove an SQL function ``search_articles``: .. code-block:: http POST /v1/metadata HTTP/1.1 Content-Type: application/json X-Hasura-Role: admin { "type": "pg_untrack_function", "args": { "function": { "schema": "public", "name": "search_articles" }, "source": "default" } } .. _metadata_pg_untrack_function_syntax: Args syntax ^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - Key - Required - Schema - Description * - function - true - :ref:`FunctionName ` - Name of the SQL function * - source - false - :ref:`SourceName ` - Name of the source database of the function (default: ``default``) .. _metadata_pg_set_function_customization: pg_set_function_customization ----------------------------- ``pg_set_function_customization`` allows you to customize any given function with a custom name and custom root fields of an already tracked function. This will **replace** the already present customization. Set the configuration for a function called ``search_articles``: .. code-block:: http POST /v1/metadata HTTP/1.1 Content-Type: application/json X-Hasura-Role: admin { "type": "pg_set_function_customization", "args": { "function": "search_articles", "source": "default", "configuration": { "custom_root_fields": { "function": "FindArticles", "function_aggregate": "FindArticlesAgg" } } } } .. _metadata_pg_set_function_customization_syntax: Args syntax ^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - Key - Required - Schema - Description * - function - true - :ref:`FunctionName ` - Name of the function * - configuration - false - :ref:`Function Configuration ` - Configuration for the function * - source - false - :ref:`SourceName ` - Name of the source database of the function (default: ``default``) .. _metadata_pg_create_function_permission: pg_create_function_permission ----------------------------- ``pg_create_function_permission`` is used to add permission to an existing custom function. To add a function permission, the provided role should have select permissions to the target table of the function. .. code-block:: http POST /v1/metadata HTTP/1.1 Content-Type: application/json X-Hasura-Role: admin { "type": "pg_create_function_permission", "args": { "function": "get_articles", "source": "default", "role": "user" } } .. _metadata_pg_create_function_permission_syntax: Args syntax ^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - Key - Required - Schema - Description * - function - true - :ref:`FunctionName ` - Name of the SQL function * - role - true - :ref:`RoleName ` - Name of the role * - source - false - Text - Name of the source database of the function (default: ``default``) .. _metadata_pg_drop_function_permission: pg_drop_function_permission --------------------------- ``pg_drop_function_permission`` is used to drop an existing function permission. .. code-block:: http POST /v1/metadata HTTP/1.1 Content-Type: application/json X-Hasura-Role: admin { "type": "pg_drop_function_permission", "args": { "function": "get_articles", "role": "user", "source": "default" } } .. _metadata_pg_drop_function_permission_syntax: Args syntax ^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - Key - Required - Schema - Description * - function - true - :ref:`FunctionName ` - Name of the SQL function * - role - true - :ref:`RoleName ` - Name of the role * - source - false - Text - Name of the source database of the function (default: ``default``)