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.

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 here.

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

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

{
    "type": "pg_track_function",
    "args": {
        "function": {
            "schema": "public",
            "name": "search_articles"
        },
        "source": "default",
        "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:

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

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_untrack_function¶

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

Remove an SQL function search_articles:

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

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:

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

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.

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

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",
       "source": "default"
    }
}