Metadata API Reference: Manage metadata (v2.0 and above)¶
Table of contents
Introduction¶
APIs to manage Hasura metadata which is stored in hdb_catalog schema.
Supported from
The metadata API is supported for versions v2.0.0 and above and replaces the older
schema/metadata API.
export_metadata¶
export_metadata is used to export the current metadata from the server as a JSON file.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "export_metadata",
"version": 1 | 2
"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.
V2 Example:
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "export_metadata",
"version": 2,
"args": {}
}
Response:
{
"resource_version": 8,
"metadata": {
"version": 3,
"sources": [
{
"name": "default",
"tables": [
{
"table": {
...
replace_metadata¶
replace_metadata is used to replace/import metadata into Hasura. Existing
metadata will be replaced with the new one.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "replace_metadata",
"version": 1 | 2
"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
}
| Key | Required | Schema | Description |
|---|---|---|---|
| allow_inconsistent_metadata | false | Boolean | If set to true, metadata will be replaced with a warning in the response indicating which items are inconsistent (default: false) |
| metadata | true | export_metadata | The metadata that will replace the current metadata. |
If the version is not specified, then it is inferred from the format of args.
Request¶
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "replace_metadata",
"version": 2
"args": {
"allow_inconsistent_metadata": Boolean,
"metadata": <metadata-object>
}
}
Responses¶
Version 2 with inconsistencies and allow_inconsistent_metadata=false, or omitted corresponds with the response document in replace_metadata.
Version 2 example with inconsistencies and allow_inconsistent_metadata=true includes an is_consistent and inconsistent_objects corresponding to get_inconsistent_metadata.
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"
}
}, ...
]
}
Version 2 example with inconsistencies and allow_inconsistent_metadata=true:
HTTP/1.1 200 OK
{
"is_consistent": false,
"inconsistent_objects": [
{
"definition": {
"definition": {
"url": "http://localhost:5000/hello-graphql",
"forward_client_headers": false
},
"name": "test",
"permissions": [],
"comment": "testing replace metadata with remote schemas"
},
"reason": "HTTP exception occurred while sending the request to http://localhost:5000/hello-graphql",
"type": "remote_schema"
}, ...
Version 2 example with invalid resource_version:
HTTP/1.1 409 Conflict
{
"path": "$",
"error": "metadata resource version referenced (2) did not match current version",
"code": "conflict"
}
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/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "reload_metadata",
"args": {
"reload_remote_schemas": true
}
}
Args syntax¶
| Key | Required | Schema | Description |
|---|---|---|---|
| reload_remote_schemas | false | Boolean | If set to true, all remote schemas’ (including inconsistent ones) cached GraphQL schemas are refreshed (default: false) |
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/metadata 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/metadata 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/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "drop_inconsistent_metadata",
"args": {}
}
Thank you for subscribing to our newsletter!
