Schema/Metadata API Reference: Custom Functions¶

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.

track_function¶

track_function is used to add a custom SQL function to the query root field of the GraphQL schema. Also refer a note here.

Add an SQL function search_articles:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "track_function",
    "args": {
        "schema": "public",
        "name": "search_articles"
    }
}

track_function v2¶

Version 2 of 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 here.

Track an SQL function called search_articles with a Hasura session argument:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "track_function",
    "version": 2,
    "args": {
        "function": {
            "schema": "public",
            "name": "search_articles"
        },
        "configuration": {
            "session_argument": "hasura_session"
        }
    }
}

Track VOLATILE SQL function reset_widget as a mutation, so it appears as a top-level field under the mutation root field:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "track_function",
    "version": 2,
    "args": {
        "function": {
            "schema": "public",
            "name": "reset_widget"
        },
        "configuration": {
            "exposed_as": "mutation"
        }
    }
}

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.

pg_create_function_permission¶

pg_create_function_permission is used to add permission to an existing custom function. To add a function permission, the graphql-engine should have disabled inferring of function permissions and the provided role should have select permissions to the target table of the function.

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "pg_create_function_permission",
    "args": {
       "function": "get_articles",
       "role": "user"
    }
}

pg_drop_function_permission¶

pg_drop_function_permission is used to drop an existing function permission.

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"
    }
}

untrack_function¶

untrack_function is used to remove a SQL function from the GraphQL schema.

Remove an SQL function search_articles:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "untrack_function",
    "args": {
        "schema": "public",
        "name": "search_articles"
    }
}