graphql-engine/docs/graphql/core/api-reference/metadata-api/manage-metadata.rst

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

.. _metadata_api_manage_metadata:

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:: Supported from

  The metadata API is supported for versions ``v2.0.0`` and above and replaces the older
  :ref:`schema/metadata API <schema_metadata_apis>`.

.. _metadata_export_metadata:

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

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

.. code-block:: none

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

V2 Example:

.. code-block:: http

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

   {
        "type": "export_metadata",
        "version": 2,
        "args": {}
   }

Response:

.. code-block:: none

    {
        "resource_version": 8,
        "metadata": {
            "version": 3,
            "sources": [
            {
                "name": "default",
                "tables": [
                {
                    "table": {
                     ...

.. _metadata_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/metadata HTTP/1.1
    Content-Type: application/json
    X-Hasura-Role: admin

    {
        "type" : "replace_metadata",
        "version": 1 | 2
        "args": <replace-metadata-args>
    }

.. _metadata_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:`metadata_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:`metadata_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
^^^^^^^

.. code-block:: none

    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 :ref:`replace_metadata`.

Version 2 example with inconsistencies and allow_inconsistent_metadata=true includes an ``is_consistent`` and ``inconsistent_objects`` corresponding to :ref:`get_inconsistent_metadata`.

.. 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"
        }
      }, ...
    ]
  }

Version 2 example with inconsistencies and allow_inconsistent_metadata=true:

.. code-block:: none

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

.. code-block:: http

    HTTP/1.1 409 Conflict

    {
      "path": "$",
      "error": "metadata resource version referenced (2) did not match current version",
      "code": "conflict"
    }

.. _metadata_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/metadata HTTP/1.1
   Content-Type: application/json
   X-Hasura-Role: admin

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

.. _metadata_reload_metadata_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``)
   * - reload_sources
     - false
     - ``Boolean`` | [:ref:`SourceName`]
     - If set to ``true``, all sources' (including inconsistent ones) cached GraphQL schemas are refreshed (default: ``true``)

.. _metadata_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/metadata HTTP/1.1
   Content-Type: application/json
   X-Hasura-Role: admin

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

.. _metadata_get_inconsistent_metadata:

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

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

.. code-block:: http

   POST /v1/metadata 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"
       }
   ]

.. _metadata_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/metadata HTTP/1.1
   Content-Type: application/json
   X-Hasura-Role: admin

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