mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 04:24:35 +03:00
626467fbe8
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3531 GitOrigin-RevId: b066920a07abd045cff4d413a00c388d7e208d4d
330 lines
7.9 KiB
ReStructuredText
330 lines
7.9 KiB
ReStructuredText
.. 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 <schema_metadata_apis>`.
|
|
|
|
.. _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 <function_req_note>`.
|
|
|
|
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 <FunctionName>`
|
|
- Name of the SQL function
|
|
* - configuration
|
|
- false
|
|
- :ref:`Function Configuration <function_configuration>`
|
|
- Configuration for the SQL function
|
|
* - source
|
|
- false
|
|
- :ref:`SourceName <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 <FunctionName>`
|
|
- Name of the SQL function
|
|
* - source
|
|
- false
|
|
- :ref:`SourceName <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 <FunctionName>`
|
|
- Name of the function
|
|
* - configuration
|
|
- false
|
|
- :ref:`Function Configuration <function_configuration>`
|
|
- Configuration for the function
|
|
* - source
|
|
- false
|
|
- :ref:`SourceName <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 <FunctionName>`
|
|
- Name of the SQL function
|
|
* - role
|
|
- true
|
|
- :ref:`RoleName <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 <FunctionName>`
|
|
- Name of the SQL function
|
|
* - role
|
|
- true
|
|
- :ref:`RoleName <RoleName>`
|
|
- Name of the role
|
|
* - source
|
|
- false
|
|
- Text
|
|
- Name of the source database of the function (default: ``default``)
|