Skip to main content
Version: v2.x

Schema/Metadata API Reference: Manage metadata (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

APIs to manage Hasura metadata which is stored in hdb_catalog schema.

export_metadata

export_metadata is used to export the current metadata from the server as a JSON file.

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type" : "export_metadata",
"args": {}
}

Response:

The response JSON will be the metadata object. The structure of the metadata object is just a JSON version of the metadata files generated by the CLI.

replace_metadata

replace_metadata is used to replace/import metadata into Hasura. Existing metadata will be replaced with the new one.

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type" : "replace_metadata",
"version": 1 | 2 (optional),
"args": <replace-metadata-args>
}

Args syntax

If version is set to 1, then args should be the JSON object which is same as the output of export_metadata.

For version 2, the following structure is used:

{
allow_inconsistent_metadata: Boolean,
metadata: metadata-object
}
KeyRequiredSchemaDescription
allow_inconsistent_metadatafalseBooleanIf set to true, metadata will be replaced with a warning in the response indicating which items are inconsistent (default: false)
metadatatrueexport_metadataThe metadata that will replace the current metadata.

If the version is not specified, then it is inferred from the format of args.

Responses

Example with inconsistencies:

HTTP/1.1 400 Bad Request

{
"internal": [
{
"type": "remote_schema",
"reason": "HTTP exception occurred while sending the request to http://localhost:5000/hello-graphql",
"definition": {
"definition": {
"url": "http://localhost:5000/hello-graphql",
"forward_client_headers": false
},
"name": "test",
"permissions": [],
"comment": "testing replace metadata with remote schemas"
}
}, ...
]
}

reload_metadata

reload_metadata should be used when there is a change in underlying Postgres database that Hasura should be aware of. Example: a new column is added to a table using psql and this column should now be added to the GraphQL schema.

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type" : "reload_metadata",
"args": {
"reload_remote_schemas": true
}
}

Response:

If the metadata is consistent:

{
"is_consistent": true,
"message": "success"
}

If the metadata is not consistent:

{
"is_consistent": false,
"message": "success",
"inconsistent_objects": [
{
"definition": {
"schema": "public",
"name": "article"
},
"name": "table article in source default",
"reason": "Inconsistent object: no such table/view exists in source: \"article\"",
"type": "table"
}
]
}

Args syntax

KeyRequiredSchemaDescription
reload_remote_schemasfalseBoolean | [RemoteSchemaName]If set to true, all remote schemas' (including inconsistent ones) cached GraphQL schemas are refreshed (default: true)

clear_metadata

clear_metadata can be used to reset the state of Hasura -- clean the current state by forgetting the tables tracked, relationships, permissions, event triggers etc.

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type" : "clear_metadata",
"args": {}
}

get_inconsistent_metadata

get_inconsistent_metadata can be used to fetch all inconsistent metadata objects.

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type": "get_inconsistent_metadata",
"args": {}
}

Response:

[
{
"definition": {
"using": {
"foreign_key_constraint_on": {
"column": "author_id",
"table": "article"
}
},
"name": "articles",
"comment": null,
"table": "author"
},
"reason": "table \"article\" does not exist",
"type": "array_relation"
},
{
"definition": {
"using": {
"foreign_key_constraint_on": "author_id"
},
"name": "author",
"comment": null,
"table": "article"
},
"reason": "table \"article\" does not exist",
"type": "object_relation"
},
{
"definition": "article",
"reason": "no such table/view exists in source : \"article\"",
"type": "table"
}
]

drop_inconsistent_metadata

drop_inconsistent_metadata can be used to purge all inconsistent objects from the metadata.

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type": "drop_inconsistent_metadata",
"args": {}
}