Metadata API Reference: Custom Functions¶
Table of contents
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.
Supported from
The metadata API is supported for versions v2.0.0
and above and replaces the older
schema/metadata 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.
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).
Args syntax¶
Key | Required | Schema | Description |
---|---|---|---|
function | true | FunctionName | Name of the SQL function |
configuration | false | Function Configuration | Configuration for the SQL function |
source | false | 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. |
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"
}
}
Args syntax¶
Key | Required | Schema | Description |
---|---|---|---|
function | true | FunctionName | Name of the SQL function |
source | false | SourceName | Name of the source database of the function (default: 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"
}
}
}
}
Args syntax¶
Key | Required | Schema | Description |
---|---|---|---|
function | true | FunctionName | Name of the function |
configuration | false | Function Configuration | Configuration for the function |
source | false | SourceName | Name of the source database of the function (default: default ) |
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"
}
}
Args syntax¶
Key | Required | Schema | Description |
---|---|---|---|
function | true | FunctionName | Name of the SQL function |
role | true | RoleName | Name of the role |
source | false | Text | Name of the source database of the function (default: default ) |
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"
}
}
Args syntax¶
Key | Required | Schema | Description |
---|---|---|---|
function | true | FunctionName | Name of the SQL function |
role | true | RoleName | Name of the role |
source | false | Text | Name of the source database of the function (default: default ) |