Metadata API Reference: Manage Metadata

Introduction

APIs for managing Hasura Metadata which is stored in the 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,
    allow_warnings: 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)
allow_warnings	false	Boolean	If set to false, any warnings will cause the metadata API call to fail (default: true)
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,
      "allow_warnings": 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"
}

Version 2 example with warnings allow_warnings=true

HTTP/1.1 200 OK

{
  "is_consistent": true,
  "inconsistent_objects": [],
  "warnings: [
    {
      "code": "illegal-event-trigger-name",
      "message": "The event trigger with name \"weird]name]\" may not work as expected, hasura suggests to use only alphanumeric, underscore and hyphens in an event trigger name",
      "type": "event_trigger",
      "name": "event_trigger weird]name] in table hasura.authors in source mssql"
    },
    ...
  ]
}

Version 2 example with warnings allow_warnings=false

HTTP/1.1 400 Bad Request

{
  "code": "metadata-warnings",
  "error": "failed due to metadata warnings",
  "internal": [
    {
      "code": "illegal-event-trigger-name",
      "message": "The event trigger with name \"weird]name]\" may not work as expected, hasura suggests to use only alphanumeric, underscore and hyphens in an event trigger name",
      "name": "event_trigger weird]name] in table hasura.authors in source mssql",
      "type": "event_trigger"
    }
  ],
  "path": "$.args"
}

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

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

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:

{
  "is_consistent": false,
  "inconsistent_objects": [
    {
      "type": "table",
      "name": "table public.article in source default",
      "definition": {
        "schema": "public",
        "name": "article"
      },
      "reason": "Inconsistent object: no such table/view exists in source: \"public.article\""
    },
    {
      "type": "array_relation",
      "name": "array_relation articles in table public.author in source default",
      "definition": {
        "name": "articles",
        "source": "default",
        "comment": null,
        "table": {
          "schema": "public",
          "name": "author"
        },
        "using": {
          "foreign_key_constraint_on": {
            "column": "author_id",
            "table": {
              "schema": "public",
              "name": "article"
            }
          }
        }
      },
      "reason": "Inconsistent object: in table \"public.author\": in relationship \"articles\": table \"public.article\" does not exist"
    }
  ]
}

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",
      "request_headers": [["myKey", "myValue"]],
      "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" },
      "request_headers": [["myKey", "myValue"]],
      "body": { "hello": "world" },
      "request_transform": {
        "body": "{{ $body.world }}",
        "template_engine": "Kriti"
      }
    }
}