ContextQMD
Back to Graphql Engine

Metadata API Reference

docs/docs/api-reference/metadata-api/index.mdx

2.49.379.2 KB
Original Source

Metadata API Reference

Introduction

The Metadata API is primarily intended to be used as an admin API to manage the Hasura Metadata.

:::tip 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

http
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

<div className="parsed-literal"> <pre> <code> <a href="#metadata-query">Query</a> </code> </pre> </div>

Query {#metadata-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:

<div className="api-metadata-request-type-table">
typeargsversionSynopsis
bulkQuery array1Execute multiple operations in a single query
bulk_atomicQuery array1Execute multiple operations in a single transaction. Currently only supports logical model and native query tracking/untracking operations.
concurrent_bulkQuery array2Execute multiple read only operations in a single transaction
bulk_keep_goingQuery array1Like bulk, but subcommands can fail without the whole batch failing
pg_add_sourcepg_add_source_args1Add a Postgres database
pg_drop_sourcepg_drop_source_args1Remove a Postgres database
pg_get_source_tablespg_get_source_tables_args1List all tables available on a given Postgres database
pg_track_tablepg_track_table_args1Add a Postgres table/view with configuration
pg_track_tablespg_track_tables_args1Add multiple Postgres tables/views with configuration
pg_untrack_tablepg_untrack_table_args1Remove a Postgres table/view
pg_untrack_tablespg_untrack_tables_args1Remove multiple Postgres tables/views
pg_update_sourcepg_update_source_args1Update a Postgres database
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
pg_set_apollo_federation_configpg_set_apollo_federation_config_args1Set Apollo Federation configuration of an already tracked postgres table
pg_test_connection_templatepg_test_connection_template_args1Test connection template
pg_track_logical_modelpg_track_logical_model_args1Add a Logical Model
pg_untrack_logical_modelpg_untrack_logical_model_args1Remove a Logical Model
pg_create_logical_model_select_permissionpg_create_logical_model_select_permission_args1Add select permissions for a Logical Model
pg_drop_logical_model_select_permissionpg_drop_logical_model_select_permission_args1Remove select permissions for a Logical Model
pg_track_native_querypg_track_native_query_args1Add a Native Query
pg_untrack_native_querypg_untrack_native_query_args1Remove a Native Query
bigquery_track_tablebigquery_track_table_args1Add a BigQuery table/view with configuration
bigquery_track_tablesbigquery_track_tables_args1Add multiple BigQuery tables/views with configuration
bigquery_untrack_tablebigquery_untrack_table_args1Remove a BigQuery table/view
bigquery_untrack_tablesbigquery_untrack_tables_args1Remove multiple BigQuery tables/views
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
bigquery_set_apollo_federation_configbigquery_set_apollo_federation_config_args1Set Apollo Federation configuration of an already tracked bigquery table
bigquery_track_logical_modelbigquery_track_logical_model_args1Add a Logical Model
bigquery_untrack_logical_modelbigquery_untrack_logical_model_args1Remove a Logical Model
bigquery_create_logical_model_select_permissionbigquery_create_logical_model_select_permission_args1Add select permissions for a Logical Model
bigquery_drop_logical_model_select_permissionbigquery_drop_logical_model_select_permission_args1Remove select permissions for a Logical Model
bigquery_track_native_querybigquery_track_native_query_args1Add a Native Query
bigquery_untrack_native_querybigquery_untrack_native_query_args1Remove a Native Query
mssql_add_sourcemssql_add_source_args1Add an MS SQL Server database
mssql_drop_sourcemssql_drop_source_args1Remove an MS SQL Server database
mssql_get_source_tablesmssql_get_source_tables_args1List all tables available on a given MS SQL Server database
mssql_track_tablemssql_track_table_args1Add an MS SQL Server table/view with configuration
mssql_track_tablesmssql_track_tables_args1Add multiple MS SQL Server tables/views with configuration
mssql_untrack_tablemssql_untrack_table_args1Remove an MS SQL Server table/view
mssql_untrack_tablesmssql_untrack_tables_args1Remove multiple MS SQL Server tables/views
mssql_update_sourcemssql_update_source_args1Update an MS SQL Server database
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
mssql_set_apollo_federation_configmssql_set_apollo_federation_config_args1Set Apollo Federation configuration of an already tracked mssql table
mssql_track_logical_modelmssql_track_logical_model_args1Add a Logical Model
mssql_untrack_logical_modelmssql_untrack_logical_model_args1Remove a Logical Model
mssql_create_logical_model_select_permissionmssql_create_logical_model_select_permission_args1Add select permissions for a Logical Model
mssql_drop_logical_model_select_permissionmssql_drop_logical_model_select_permission_args1Remove select permissions for a Logical Model
mssql_track_native_querymssql_track_native_query_args1Add a Native Query
mssql_untrack_native_querymssql_untrack_native_query_args1Remove a Native Query
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
get_scheduled_eventsget_scheduled_events_args1API to fetch scheduled events
get_scheduled_event_invocationsget_scheduled_event_invocations_args1API to fetch scheduled event's invocations
create_scheduled_eventcreate_scheduled_event_args1Create a new scheduled event
delete_scheduled_eventdelete_scheduled_event_args1Delete a scheduled event
cleanup_event_trigger_logscleanup_event_trigger_logs_args1Manually delete Event Trigger logs
resume_event_trigger_cleanupsresume_event_trigger_cleanups_args1Resume log cleaner for Event Triggers
pause_event_trigger_cleanupspause_event_trigger_cleanups_args1Pause log cleaner for Event Triggers
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
rename_query_collectionrename_query_collection_args1Rename 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
</div> <!-- TODO: MSSQL_UNSUPPORTED | `mssql_set_table_is_enum` | `mssql_set_table_is_enum_args <mssql_set_table_is_enum_syntax>` | 1 | Set a tracked MS SQL Server table as an enum table | | `mssql_track_function` | `mssql_track_function_args <mssql_track_function_syntax>` | 1 | Add an MS SQL Server SQL function with configuration | | `mssql_untrack_function` | `FunctionName <FunctionName>` | 1 | Remove an MS SQL Server SQL function | | `mssql_create_function_permission` | `mssql_create_function_permission_args <mssql_create_function_permission_syntax>` | 1 | Create an MS SQL Server function permission | | `mssql_drop_function_permission` | `mssql_drop_function_permission_args <mssql_drop_function_permission_syntax>` | 1 | Drop an existing MS SQL Server function permission | | `mssql_add_computed_field` | `mssql_add_computed_field_args <mssql_add_computed_field_syntax>` | 1 | Add a computed field to an MS SQL Server table/view | | `mssql_drop_computed_field` | `mssql_drop_computed_field_args <mssql_drop_computed_field_syntax>` | 1 | Drop an MS SQL Server computed field | | `mssql_create_event_trigger` | `mssql_create_event_trigger_args <mssql_create_event_trigger_syntax>` | 1 | Create or replace an Event Trigger on an MS SQL Server table | | `mssql_delete_event_trigger` | `mssql_delete_event_trigger_args <mssql_delete_event_trigger_syntax>` | 1 | Delete an existing Event Trigger on an MS SQL Server table | | `mssql_redeliver_event` | `mssql_redeliver_event_args <mssql_redeliver_event_syntax>` | 1 | Redeliver an existing event on an MS SQL Server table | | `mssql_invoke_event_trigger` | `mssql_invoke_event_trigger_args <mssql_invoke_event_trigger_syntax>` | 1 | Invoke a trigger with custom payload on an MS SQL Server table | -->

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.

bash
# 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.