Metadata API Reference (v2.0 and above)¶
Table of contents
Introduction¶
The metadata API is primarily intended to be used as an admin API to manage the Hasura metadata.
Supported from
The metadata API is supported for versions v2.0.0 and above and replaces the older
schema/metadata API.
Endpoint¶
All requests are POST requests to the /v1/metadata endpoint.
Request structure¶
POST /v1/metadata HTTP/1.1
{
"type": <query-type>,
"version": <Integer> (optional),
"resource_version": <Integer> (optional),
"args": <args-object>
}
The structure of args depends on the type and version.
Request body¶
Query
Query¶
| Key | Required | Schema | Description |
|---|---|---|---|
| type | true | String | Type of the query |
| resource_version | false | Integer | Version of the resource that you are targeting for replacement |
| args | true | JSON Value | The arguments to the query |
| version | false | Integer | Version of the API (inferred by args structure) |
Request types¶
The various types of queries are listed in the following table:
type |
args |
version |
Synopsis |
|---|---|---|---|
| bulk | Query array | 1 | Execute multiple operations in a single query |
| pg_add_source | pg_add_source_args | 1 | Add a Postgres database |
| pg_drop_source | pg_drop_source_args | 1 | Remove a Postgres database |
| pg_track_table | pg_track_table_args | 1 | Add a Postgres table/view with configuration |
| pg_untrack_table | pg_untrack_table_args | 1 | Remove a Postgres table/view |
| pg_set_table_customization | pg_set_table_customization_args | 1 | Set table customization of an already tracked Postgres table |
| pg_set_table_is_enum | pg_set_table_is_enum_args | 1 | Set a tracked Postgres table as an enum table |
| pg_track_function | pg_track_function_args | 1 | Add a Postgres SQL function with configuration |
| pg_untrack_function | FunctionName | 1 | Remove a Postgres SQL function |
| pg_create_function_permission | pg_create_function_permission_args | 1 | Create a Postgres function permission |
| pg_drop_function_permission | pg_drop_function_permission_args | 1 | Drop an existing Postgres function permission |
| pg_create_object_relationship | pg_create_object_relationship_args | 1 | Define a new object relationship between Postgres tables/views |
| pg_create_array_relationship | pg_create_array_relationship_args | 1 | Define a new array relationship between Postgres tables/views |
| pg_drop_relationship | pg_drop_relationship_args | 1 | Drop an existing Postgres relationship |
| pg_rename_relationship | pg_rename_relationship_args | 1 | Modify name of an existing Postgres relationship |
| pg_set_relationship_comment | pg_set_relationship_comment_args | 1 | Set comment on an existing Postgres relationship |
| pg_add_computed_field | pg_add_computed_field_args | 1 | Add a computed field to a Postgres table/view |
| pg_drop_computed_field | pg_drop_computed_field_args | 1 | Drop a Postgres computed field |
| pg_create_insert_permission | pg_create_insert_permission_args | 1 | Specify insert permission for a Postgres table/view |
| pg_drop_insert_permission | pg_drop_insert_permission_args | 1 | Remove existing insert permission for a Postgres table/view |
| pg_create_select_permission | pg_create_select_permission_args | 1 | Specify select permission for a Postgres table/view |
| pg_drop_select_permission | pg_drop_select_permission_args | 1 | Remove existing select permission for a Postgres table/view |
| pg_create_update_permission | pg_create_update_permission_args | 1 | Specify update permission for a Postgres table/view |
| pg_drop_update_permission | pg_drop_update_permission_args | 1 | Remove existing update permission for a Postgres table/view |
| pg_create_delete_permission | pg_create_delete_permission_args | 1 | Specify delete permission for a Postgres table/view |
| pg_drop_delete_permission | pg_drop_delete_permission_args | 1 | Remove existing delete permission for a Postgres table/view |
| pg_set_permission_comment | pg_set_permission_comment_args | 1 | Set comment on an existing permission for a Postgres table/view |
| pg_create_event_trigger | pg_create_event_trigger_args | 1 | Create or replace an event trigger on a Postgres table |
| pg_delete_event_trigger | pg_delete_event_trigger_args | 1 | Delete an existing event trigger on a Postgres table |
| pg_redeliver_event | pg_redeliver_event_args | 1 | Redeliver an existing event on a Postgres table |
| pg_invoke_event_trigger | pg_invoke_event_trigger_args | 1 | Invoke a trigger with custom payload on a Postgres table |
| create_cron_trigger | create_cron_trigger_args | 1 | Create a cron trigger |
| delete_cron_trigger | delete_cron_trigger_args | 1 | Delete an existing cron trigger |
| create_scheduled_event | create_scheduled_event_args | 1 | Create a new scheduled event |
| add_remote_schema | add_remote_schema_args | 1 | Add a remote GraphQL server as a remote schema |
| remove_remote_schema | remove_remote_schema_args | 1 | Remove an existing remote schema |
| reload_remote_schema | reload_remote_schema_args | 1 | Reload schema of an existing remote schema |
| add_remote_schema_permissions | add_remote_schema_permissions | 1 | Add permissions to a role of an existing remote schema |
| drop_remote_schema_permissions | drop_remote_schema_permissions | 1 | Drop existing permissions defined for a role for a remote schema |
| create_remote_relationship | create_remote_relationship_args | 1 | Create a remote relationship with an existing remote schema |
| update_remote_relationship | update_remote_relationship_args | 1 | Update an existing remote relationship |
| delete_remote_relationship | delete_remote_relationship_args | 1 | Delete an existing remote relationship |
| export_metadata | Empty Object | 1 | Export the current metadata |
| export_metadata | Empty Object | 2 | Export existing metadata with resource version included. |
| replace_metadata | replace_metadata_args | 1 | Import and replace existing metadata |
| replace_metadata | replace_metadata_args | 2 | Replace existing metadata with check against current resource_version. |
| reload_metadata | Empty Object | 1 | Reload changes to the underlying Postgres DB |
| clear_metadata | Empty Object | 1 | Clear/wipe-out the current metadata state form server |
| get_inconsistent_metadata | Empty Object | 1 | List all inconsistent metadata objects |
| drop_inconsistent_metadata | Empty Object | 1 | Drop all inconsistent metadata objects |
| create_query_collection | create_query_collection_args | 1 | Create a query collection |
| drop_query_collection | drop_query_collection_args | 1 | Drop a query collection |
| add_query_to_collection | add_query_to_collection_args | 1 | Add a query to a given collection |
| drop_query_from_collection | drop_query_from_collection_args | 1 | Drop a query from a given collection |
| add_collection_to_allowlist | add_collection_to_allowlist_args | 1 | Add a collection to the allow-list |
| drop_collection_from_allowlist | drop_collection_from_allowlist_args | 1 | Drop a collection from the allow-list |
| set_custom_types | set_custom_types_args | 1 | Set custom GraphQL types |
| create_action | create_action_args | 1 | Create an action |
| drop_action | drop_action_args | 1 | Drop an action |
| update_action | update_action_args | 1 | Update an action |
| create_action_permission | create_action_permission_args | 1 | Create an action permission |
| drop_action_permission | drop_action_permission_args | 1 | Drop an action permission |
| create_rest_endpoint | create_rest_endpoint_args | 1 | Create a RESTified GraphQL Endpoint |
| drop_rest_endpoint | drop_rest_endpoint_args | 1 | Drop a RESTified GraphQL Endpoint |
See:
Response structure¶
| Status code | Description | Response structure |
|---|---|---|
200 |
Success | Request specific
|
400 |
Bad request | {
"path" : String,
"error" : String
}
|
401 |
Unauthorized | {
"error" : String
}
|
500 |
Internal server error | {
"error" : String
}
|
Disabling metadata API¶
Since this API can be used to make changes to the GraphQL schema, it can be disabled, especially in production deployments.
The enabled-apis flag or the HASURA_GRAPHQL_ENABLED_APIS env var can be used to
enable/disable this API. By default, the schema/metadata API is enabled. To disable it, you need
to explicitly state that this API is not enabled i.e. remove it from the list of enabled APIs.
# enable only graphql api, disable metadata and pgdump
--enabled-apis="graphql"
HASURA_GRAPHQL_ENABLED_APIS="graphql"
See GraphQL engine server flags reference for info on setting the above flag/env var.
Metadata Resource Versioning¶
Metadata is versioned with an optional resource_version field in operations and responses.
This is intended to allow for feedback when replacing metadata with modifications to an out-of-date copy.
The resource_version supplied must match the version returned otherwise a 409 error response is returned.
The version is incremented on any operation that modified metadata as well as reload_metadata.
Was this page helpful?
Thank you for your feedback!
Stay up to date with product & security news
Thank you for subscribing to our newsletter!
