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,
        "recreate_event_triggers": true
    }
}

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)
recreate_event_triggers false Boolean | [SourceName] If set to true, all sources’ (including inconsistent ones) cached event triggers and their corresponding SQL triggers present in the source database will be recreated. When an array of SourceName is provided, the event triggers will only be recreated for those sources. (default: false i.e. no sources’ event triggers will be recreated)

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"
      }
    }
}

The webhook_url can be provided in an Environment Variable supplied in an object with the from_env key:

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

{
    "type" : "test_webhook_transform",
    "args" : {
      "webhook_url": {"from_env": "url_env_var" },
      "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.