.. meta::
   :description: Manage metadata with the Hasura schema/metadata API
   :keywords: hasura, docs, schema/metadata API, API reference, metadata

.. _api_manage_metadata:

Schema/Metadata API Reference: Manage metadata
==============================================

.. contents:: Table of contents
  :backlinks: none
  :depth: 1
  :local:

Introduction
------------

APIs to manage Hasura metadata which is stored in ``hdb_catalog`` schema.

.. admonition:: Deprecation

  In versions ``v2.0.0`` and above, the schema/metadata API is deprecated in favour of the :ref:`schema API <schema_apis>` and the
  :ref:`metadata API <metadata_apis>`.

  Though for backwards compatibility, the schema/metadata APIs will continue to function.

.. _export_metadata:

export_metadata
---------------

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

.. code-block:: 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 :ref:`metadata files <metadata_format_v2>` generated by
the CLI.


.. _replace_metadata:

replace_metadata
----------------

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

.. code-block:: none

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

.. _replace_metadata_syntax:

Args syntax
^^^^^^^^^^^

If version is set to 1, then args should be the JSON object which is same as
the output of :ref:`export_metadata`.

For version 2, the following structure is used:

.. code-block:: none

    {
        allow_inconsistent_metadata: Boolean,
        metadata: metadata-object
    }

.. list-table::
   :header-rows: 1

   * - 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
     - :ref:`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:

.. code-block:: none

  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:

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.

.. code-block:: http

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

   {
       "type" : "reload_metadata",
       "args": {
           "reload_remote_schemas": true
       }
   }

.. _reload_metadata_args_syntax:

Args syntax
^^^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Key
     - Required
     - Schema
     - Description
   * - reload_remote_schemas
     - false
     - ``Boolean`` | [:ref:`RemoteSchemaName`]
     - If set to ``true``, all remote schemas' (including inconsistent ones) cached GraphQL schemas are refreshed (default: ``true``)

.. _clear_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.

.. code-block:: http

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

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

.. _get_inconsistent_metadata:

get_inconsistent_metadata
-------------------------

``get_inconsistent_metadata`` can be used to fetch all inconsistent metadata objects.

.. code-block:: http

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

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

Response:

.. code-block:: 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:

drop_inconsistent_metadata
--------------------------

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

.. code-block:: http

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

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