Skip to main content
Version: v2.x

Metadata API Reference

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​

KeyRequiredSchemaDescription
typetrueStringType of the query
resource_versionfalseIntegerVersion of the resource that you are targeting for replacement
argstrueJSON ValueThe arguments to the query
versionfalseIntegerVersion of the API (inferred by args structure)

Request types​

The various types of queries are listed in the following table:

typeargsversionSynopsis
bulkQuery array1Execute multiple operations in a single query
pg_add_sourcepg_add_source_args1Add a Postgres database
pg_drop_sourcepg_drop_source_args1Remove a Postgres database
pg_track_tablepg_track_table_args1Add a Postgres table/view with configuration
pg_untrack_tablepg_untrack_table_args1Remove a Postgres table/view
pg_set_table_customizationpg_set_table_customization_args1Set table customization of an already tracked Postgres table
pg_set_table_is_enumpg_set_table_is_enum_args1Set a tracked Postgres table as an enum table
pg_track_functionpg_track_function_args1Add a Postgres SQL function with configuration
pg_untrack_functionpg_untrack_function_args1Remove a Postgres SQL function
pg_set_function_customizationpg_set_function_customization_args1Set function customization of an already tracked Postgres function
pg_create_function_permissionpg_create_function_permission_args1Create a Postgres function permission
pg_drop_function_permissionpg_drop_function_permission_args1Drop an existing Postgres function permission
pg_create_object_relationshippg_create_object_relationship_args1Define a new object relationship between Postgres tables/views
pg_create_array_relationshippg_create_array_relationship_args1Define a new array relationship between Postgres tables/views
pg_drop_relationshippg_drop_relationship_args1Drop an existing Postgres relationship
pg_rename_relationshippg_rename_relationship_args1Modify name of an existing Postgres relationship
pg_set_relationship_commentpg_set_relationship_comment_args1Set comment on an existing Postgres relationship
pg_add_computed_fieldpg_add_computed_field_args1Add a computed field to a Postgres table/view
pg_drop_computed_fieldpg_drop_computed_field_args1Drop a Postgres computed field
pg_create_insert_permissionpg_create_insert_permission_args1Specify insert permission for a Postgres table/view
pg_drop_insert_permissionpg_drop_insert_permission_args1Remove existing insert permission for a Postgres table/view
pg_create_select_permissionpg_create_select_permission_args1Specify select permission for a Postgres table/view
pg_drop_select_permissionpg_drop_select_permission_args1Remove existing select permission for a Postgres table/view
pg_create_update_permissionpg_create_update_permission_args1Specify update permission for a Postgres table/view
pg_drop_update_permissionpg_drop_update_permission_args1Remove existing update permission for a Postgres table/view
pg_create_delete_permissionpg_create_delete_permission_args1Specify delete permission for a Postgres table/view
pg_drop_delete_permissionpg_drop_delete_permission_args1Remove existing delete permission for a Postgres table/view
pg_set_permission_commentpg_set_permission_comment_args1Set comment on an existing permission for a Postgres table/view
pg_create_event_triggerpg_create_event_trigger_args1Create or replace an event trigger on a Postgres table
pg_delete_event_triggerpg_delete_event_trigger_args1Delete an existing event trigger on a Postgres table
pg_redeliver_eventpg_redeliver_event_args1Redeliver an existing event on a Postgres table
pg_invoke_event_triggerpg_invoke_event_trigger_args1Invoke a trigger with custom payload on a Postgres table
bigquery_track_tablebigquery_track_table_args1Add a BigQuery table/view with configuration
bigquery_untrack_tablebigquery_untrack_table_args1Remove a BigQuery table/view
bigquery_set_table_customizationbigquery_set_table_customization_args1Set table customization of an already tracked BigQuery table
bigquery_add_computed_fieldbigquery_add_computed_field_args1Add a computed field to a BigQuery table
bigquery_drop_computed_fieldbigquery_drop_computed_field_args1Drop a BigQuery computed field
mssql_add_sourcemssql_add_source_args1Add an MS SQL Server database
mssql_drop_sourcemssql_drop_source_args1Remove an MS SQL Server database
mssql_track_tablemssql_track_table_args1Add an MS SQL Server table/view with configuration
mssql_untrack_tablemssql_untrack_table_args1Remove an MS SQL Server table/view
mssql_create_object_relationshipmssql_create_object_relationship_args1Define a new object relationship between MS SQL Server tables/views
mssql_create_array_relationshipmssql_create_array_relationship_args1Define a new array relationship between MS SQL Server tables/views
mssql_drop_relationshipmssql_drop_relationship_args1Drop an existing MS SQL Server relationship
mssql_rename_relationshipmssql_rename_relationship_args1Modify name of an existing MS SQL Server relationship
mssql_set_relationship_commentmssql_set_relationship_comment_args1Set comment on an existing MS SQL Server relationship
mssql_set_table_customizationmssql_set_table_customization_args1Set table customization of an already tracked MS SQL Server table
mssql_create_insert_permissionmssql_create_insert_permission_args1Specify insert permission for an MS SQL Server table/view
mssql_drop_insert_permissionmssql_drop_insert_permission_args1Remove existing insert permission for an MS SQL Server table/view
mssql_create_select_permissionmssql_create_select_permission_args1Specify select permission for an MS SQL Server table/view
mssql_drop_select_permissionmssql_drop_select_permission_args1Remove existing select permission for an MS SQL Server table/view
mssql_create_update_permissionmssql_create_update_permission_args1Specify update permission for an MS SQL Server table/view
mssql_drop_update_permissionmssql_drop_update_permission_args1Remove existing update permission for an MS SQL Server table/view
mssql_create_delete_permissionmssql_create_delete_permission_args1Specify delete permission for an MS SQL Server table/view
mssql_drop_delete_permissionmssql_drop_delete_permission_args1Remove existing delete permission for an MS SQL Server table/view
mssql_set_permission_commentmssql_set_permission_comment_args1Set comment on an existing permission for an MS SQL Server table/view
create_cron_triggercreate_cron_trigger_args1Create a cron trigger
delete_cron_triggerdelete_cron_trigger_args1Delete an existing cron trigger
get_cron_triggersEmpty Object1Returns all the cron triggers
create_scheduled_eventcreate_scheduled_event_args1Create a new scheduled event
delete_scheduled_eventdelete_scheduled_event_args1Delete a scheduled event
add_remote_schemaadd_remote_schema_args1Add a remote GraphQL server as a remote schema
update_remote_schemaupdate_remote_schema_args1Update the details for a remote schema
remove_remote_schemaremove_remote_schema_args1Remove an existing remote schema
reload_remote_schemareload_remote_schema_args1Reload schema of an existing remote schema
add_remote_schema_permissionsadd_remote_schema_permissions1Add permissions to a role of an existing remote schema
drop_remote_schema_permissionsdrop_remote_schema_permissions1Drop existing permissions defined for a role for a remote schema
pg_create_remote_relationshippg_create_remote_relationship_args1Create a remote relationship on a Postgres table
pg_update_remote_relationshippg_update_remote_relationship_args1Update an existing remote relationship
pg_delete_remote_relationshippg_delete_remote_relationship_args1Delete an existing remote relationship
citus_create_remote_relationshipcitus_create_remote_relationship_args1Create a remote relationship on a citus table
citus_update_remote_relationshipcitus_update_remote_relationship_args1Update an existing remote relationship
citus_delete_remote_relationshipcitus_delete_remote_relationship_args1Delete an existing remote relationship
mssql_create_remote_relationshipmssql_create_remote_relationship_args1Create a remote relationship on an mssql table
mssql_update_remote_relationshipmssql_update_remote_relationship_args1Update an existing remote relationship
mssql_delete_remote_relationshipmssql_delete_remote_relationship_args1Delete an existing remote relationship
bigquery_create_remote_relationshipbigquery_create_remote_relationship_args1Create a remote relationship on a bigquery table
bigquery_update_remote_relationshipbigquery_update_remote_relationship_args1Update an existing remote relationship
bigquery_delete_remote_relationshipbigquery_delete_remote_relationship_args1Delete an existing remote relationship
create_remote_schema_remote_relationshipcreate_remote_schema_remote_relationship_args1Create a remote relationship on a remote schema's type
update_remote_schema_remote_relationshipupdate_remote_schema_remote_relationship_args1Update an existing remote relationship on a remote schema's type
delete_remote_schema_remote_relationshipdelete_remote_schema_remote_relationship_args1Delete an existing remote relationship on a remote schema's type
export_metadataEmpty Object1Export the current metadata
export_metadataEmpty Object2Export existing metadata with resource version included.
replace_metadatareplace_metadata_args1Import and replace existing metadata
replace_metadatareplace_metadata_args2Replace existing metadata with check against current resource_version.
reload_metadatareload_metadata_args1Reload changes to the underlying Postgres DB
clear_metadataEmpty Object1Clear/wipe-out the current metadata state form server
get_inconsistent_metadataEmpty Object1List all inconsistent metadata objects
drop_inconsistent_metadataEmpty Object1Drop all inconsistent metadata objects
create_query_collectioncreate_query_collection_args1Create a query collection
drop_query_collectiondrop_query_collection_args1Drop a query collection
add_query_to_collectionadd_query_to_collection_args1Add a query to a given collection
drop_query_from_collectiondrop_query_from_collection_args1Drop a query from a given collection
add_collection_to_allowlistadd_collection_to_allowlist_args1Add a collection to the allow-list
drop_collection_from_allowlistdrop_collection_from_allowlist_args1Drop a collection from the allow-list
set_custom_typesset_custom_types_args1Set custom GraphQL types
create_actioncreate_action_args1Create an action
drop_actiondrop_action_args1Drop an action
update_actionupdate_action_args1Update an action
create_action_permissioncreate_action_permission_args1Create an action permission
drop_action_permissiondrop_action_permission_args1Drop an action permission
create_rest_endpointcreate_rest_endpoint_args1Create a RESTified GraphQL Endpoint
drop_rest_endpointdrop_rest_endpoint_args1Drop a RESTified GraphQL Endpoint
add_inherited_roleadd_inherited_role_args1Add an inherited role
drop_inherited_roledrop_inherited_role_args1Drop an inherited role
set_graphql_introspection_optionsset_graphql_schema_introspection_options_args1Set graphql introspection options
add_host_to_tls_allowlistadd_host_to_tls_allowlist_args1Add an endpoint to the TLS Allowlist
drop_host_from_tls_allowlistdrop_host_from_tls_allowlist_args1Drop an endpoint from the TLS Allowlist

See:

Response structure​

Status codeDescriptionResponse structure
200SuccessRequest specific
400Bad request{ "path" : String, "error" : String}
401Unauthorized{"error" : String}
500Internal 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 config 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.