Metadata API Reference: Manage metadata

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,
        "reload_sources": false
    }
}

Args syntax

Key Required Schema Description
reload_remote_schemas false Boolean | [RemoteSchemaName] If set to true, all remote schemas’ (including inconsistent ones) cached GraphQL schemas are refreshed (default: true)
reload_sources false Boolean | [SourceName] If set to true, all sources’ (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/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": {}
}

test_webhook_transform

test_webhook_transform can be used to test out request transformations using mock data.

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

{
    "type" : "test_webhook_transform",
    "args" : {
      "webhook_url": "http://localhost:1234",
      "body": { "hello": "world" },
      "request_transform": {
        "body": "{{ $body.world }}",
        "template_engine": "Kriti"
      }
    }
}
« previous | next »
Want to contribute or report missing content?

Powered by Sphinx. | Copyright © 2021 Hasura.