Schema/Metadata API Reference: Manage Metadata (Deprecated)

:::caution 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 {#schema-metadata-export-metadata}

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

http

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 {#schema-metadata-replace-metadata}

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

http

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 {#schema-metadata-replace-metadata-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:

json

{
    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`)
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.

Responses

Example with inconsistencies:

http

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 {#schema-metadata-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.

http

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:

json

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

If the Metadata is not consistent:

json

{
  "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 {#schema-metadata-reload-metadata-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`)

clear_metadata {#schema-metadata-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.

http

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

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

get_inconsistent_metadata {#schema-metadata-get-inconsistent-metadata}

get_inconsistent_metadata can be used to fetch all inconsistent Metadata objects.

http

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

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

Response:

json

[
  {
    "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 {#schema-metadata-drop-inconsistent-metadata}

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

http

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

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