Skip to main content
Version: v2.x

Schema / Metadata API Reference (Deprecated)

Deprecation

In versions v2.0.0 and above, the schema/metadata API is deprecated in favour of the schema API and the metadata API.

Though for backwards compatibility, the schema/metadata APIs will continue to function.

Introduction

The schema / metadata API provides the following features:

  1. Execute SQL on the underlying Postgres database, supports schema modifying actions.
  2. Modify Hasura metadata (permission rules and relationships).

This is primarily intended to be used as an admin API to manage the Hasura schema and metadata.

Endpoint

All requests are POST requests to the /v1/query endpoint.

Request structure

POST /v1/query HTTP/1.1

{
"type": "<query-type>",
"args": <args-object>
}

Request body

Query

KeyRequiredSchemaDescription
typetrueStringType of the query
argstrueJSON ValueThe arguments to the query
versionfalseIntegerVersion of the API (default: 1)

Request types

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

typeargsversionSynopsis
bulkQuery array1Execute multiple operations in a single query
run_sqlrun_sql_args1Run SQL directly on Postgres
track_tableTableName1Add a table/view
track_tabletrack_table_args2Add a table/view with configuration
set_table_customizationset_table_customization_args1Set table customization of an already tracked table
set_table_custom_fields (deprecated)set_table_custom_fields_args2Set custom fields of an already tracked table (deprecated)
untrack_tableuntrack_table_args1Remove a table/view
set_table_is_enumset_table_is_enum_args1Set a tracked table as an enum table
track_functionFunctionName1Add an SQL function
track_functiontrack_function_args2Add an SQL function with configuration
untrack_functionFunctionName1Remove an SQL function
create_object_relationshipcreate_object_relationship_args1Define a new object relationship
create_array_relationshipcreate_array_relationship_args1Define a new array relationship
drop_relationshipdrop_relationship_args1Drop an existing relationship
rename_relationshiprename_relationship_args1Modify name of an existing relationship
set_relationship_commentset_relationship_comment_args1Set comment on an existing relationship
add_computed_fieldadd_computed_field_args1Add a computed field
drop_computed_fielddrop_computed_field_args1Drop a computed field
create_insert_permissioncreate_insert_permission_args1Specify insert permission
drop_insert_permissiondrop_insert_permission_args1Remove existing insert permission
create_select_permissioncreate_select_permission_args1Specify select permission
drop_select_permissiondrop_select_permission_args1Remove existing select permission
create_update_permissioncreate_update_permission_args1Specify update permission
drop_update_permissiondrop_update_permission_args1Remove existing update permission
create_delete_permissioncreate_delete_permission_args1Specify delete permission
drop_delete_permissiondrop_delete_permission_args1Remove existing delete permission
set_permission_commentset_permission_comment_args1Set comment on an existing permission
create_event_triggercreate_event_trigger_args1Create or replace an event trigger
delete_event_triggerdelete_event_trigger_args1Delete an existing event trigger
redeliver_eventredeliver_event_args1Redeliver an existing event
invoke_event_triggerinvoke_event_trigger_args1Invoke a trigger with custom payload
create_cron_triggercreate_cron_trigger_args1Create a cron trigger
delete_cron_triggerdelete_cron_trigger_args1Delete an existing cron trigger
get_cron_triggersEmpty Object1Fetch all the cron triggers
create_scheduled_eventcreate_scheduled_event_args1Create a new 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
create_remote_relationshipcreate_remote_relationship_args1Create a remote relationship with an existing remote schema
update_remote_relationshipupdate_remote_relationship_args1Update an existing remote relationship
delete_remote_relationshipdelete_remote_relationship_args1Delete an existing remote relationship
export_metadataEmpty Object1Export the current metadata
replace_metadatareplace_metadata_args1Import and replace existing metadata
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_args3Create a RESTified GraphQL Endpoint
drop_rest_endpointdrop_rest_endpoint_args3Drop a RESTified GraphQL Endpoint

See:

Response structure

Status codeDescriptionResponse structure
200SuccessRequest specific
400Bad request{"path" : String, "error" : String}
401Unauthorized{"error" : String}
500Internal server error{"error" : String}

Error codes

Status CodeCodeError
400postgres-errorNot-NULL violation. null value in column <column-name> violates not-null constraint
400permission-deniedselect on <column/table> for role <role-name> is not allowed.
400not-existstable <table-name> does not exist
400not-existsno such table/view exists in source: <table-name>
400not-exists<field-name> does not exist
400already-trackedview/table already tracked: <table-name>
400access-deniedrestricted access: admin only
400not-supportedtable renames are not yet supported: <table-name>
400not-exists<column-name> does not exist
400already-existscannot add column <column-name> in table <table-name> as a relationship with the name already exists
400invalid-jsoninvalid json
400not-supportedcolumn renames are not yet supported: <table-name>.<column-name>
400invalid-headersmissing header: <header-name>
400dependency-errorcannot change type of column <column-name> in table <table-name> because of the following dependencies: <dependencies>
400invalid-headersX-Hasura-User-Id should be an integer
400dependency-errorcannot drop due to the following dependent objects: <dependencies>
400access-deniedYou have to be admin to access this endpoint
400parse-failedparsing dotted table failed: <table-name>
400access-deniednot authorised to access this tx
400already-existsmultiple declarations exist for the following <table-name>: <duplicates>
400not-existstx does not exists
400already-existscolumn/relationship of table <table-name> already exists
400already-initialisedthe state seems to be initialised already. \ \ you may need to migrate from this version: <catalog-version>
400constraint-errorno foreign constraint exists on the given column
400not-supportedunsupported version: <catalog-version>
400constraint-errormore than one foreign key constraint exists on the given column
400already-existsthe query template already exists <template-name>
400permission-error<permission-type>' permission on <table-name> for role <role-name> already exists
400permission-error<permission-type>' permission on <table-name> for role <role-name> does not exist
400unexpected-payloadUnknown operator: <operator-type>
400unexpected-payloadexpecting a string for column operator
400unexpected-payloadincompatible column types: '<column-name>', '<column-name>'
400unexpected-payloadExpecting 'constraint' or 'constraint_on' when the 'action' is 'update'
400unexpected-payloadconstraint' and 'constraint_on' cannot be set at a time
400unexpected-payloadupsert is not allowed for role '<role-name>'
400unexpected-payloadobjects should not be empty
400invalid-paramsmissing parameter: <param-name>
400unexpected-payloadcan't be empty
400<col-name> is a relationship and should be expanded
400unexpected-payload<column-name>' should be included in 'columns'
400unexpected-payload<column-name>' is an array relationship and can't be used in 'order_by'
400<column-name>' is a Postgres column and cannot be chained further
400unexpected-payloadorder_by array should not be empty
400unexpected-payloadwhen selecting an 'obj_relationship' 'where', 'order_by', 'limit' and 'offset' can't be used
400unexpected-payloadatleast one of $set, $inc, $mul has to be present
400permission-denied<permission-type> on <table-name> for role <role-name> is not allowed
400not-existsno such column exists: <column-name>
400permission-deniedrole <role-name> does not have permission to <permission-type> column <column-name>
400expecting a postgres column; but, <name> is relationship
400unexpected-payloadJSON column can not be part of where clause
400unexpected-payloadis of type <type-name>; this operator works only on column of types <[types]>
400postgres-errorquery execution failed
500unexpectedunexpected dependency of relationship: <dependency>
500unexpectedunexpected dependent object: <dependency>
500unexpectedfield already exists
500unexpectedfield does not exist
500unexpectedpermission does not exist
500postgres-errorpostgres transaction error
500postgres-errorconnection error
500postgres-errorpostgres query error
404not-foundNo such resource exists

Disabling schema / 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.