docs: document resetting metadata (close hasura#3874) (hasura#5961)

hasura#5961

docs/graphql/core/migrations/manage-metadata.rst

@@ -43,14 +43,18 @@ Exporting Hasura metadata
 
      1. Click on the settings (⚙) icon at the top right corner of the console screen.
      2. In the Hasura metadata actions page that opens, click on the ``Export Metadata`` button.
+
+        .. thumbnail:: /img/graphql/core/migrations/metadata-export.png
+           :alt: Export metadata
+
      3. This will prompt a file download for ``hasura_metadata_<timestamp>.json``. Save the file.
 
   .. tab:: API
 
-     The export can be done via the :ref:`Metadata API
-     <api_manage_metadata>`.
-     Response will be a JSON object with the Hasura metadata. Here is an example
-     using ``curl`` to save this as a file:
+     The export can be done via the :ref:`export_metadata metadata API <export_metadata>`.
+     Response will be a JSON object with the Hasura metadata.
+
+     Here is an example using ``curl`` to save this as a file:
 
      .. code-block:: bash
 
@@ -91,13 +95,17 @@ before.
 
      1. Click on the settings (⚙) icon at the top right corner of the console screen.
      2. Click on ``Import Metadata`` button.
+
+        .. thumbnail:: /img/graphql/core/migrations/metadata-import.png
+           :alt: Import metadata
+
      3. Choose a ``hasura_metadata.json`` file that was exported earlier.
      4. A notification should appear indicating the success or error.
 
   .. tab:: API
 
-     The exported JSON can be imported via the :ref:`Metadata API
-     <api_manage_metadata>`.
+     The exported JSON can be imported via the :ref:`replace_metadata metadata API <replace_metadata>`.
+
      Here is an example using ``curl``:
 
      .. code-block:: bash
@@ -137,12 +145,16 @@ when a new column has been added to a table via an external tool such as ``psql`
 
      1. Click on the settings (⚙) icon at the top right corner of the console screen.
      2. Click on ``Reload`` button.
+
+        .. thumbnail:: /img/graphql/core/migrations/metadata-reload.png
+           :alt: Reload metadata
+
      3. A notification should appear indicating the success.
 
   .. tab:: API
 
-     The reload of metadata can be done via the :ref:`Metadata API
-     <api_manage_metadata>`.
+     The reload of metadata can be done via the :ref:`reload_metadata metadata API <reload_metadata>`.
+
      Here is an example using ``curl``:
 
      .. code-block:: bash
@@ -158,6 +170,48 @@ when a new column has been added to a table via an external tool such as ``psql`
    all inconsistent objects manually or delete them. After that, you need to reload
    metadata again.
 
+
+.. _reset_metadata_manual:
+
+Resetting Hasura metadata
+-------------------------
+
+Resetting GraphQL engine's metadata is an irreversible process. It is recommended to first export the metadata
+so that it can be reapplied if needed or else that information will be lost and Hasura will have to be configured
+again from scratch (e.g. tracking tables, relationships, creating triggers, actions, etc.).
+
+.. rst-class:: api_tabs
+.. tabs::
+
+  .. tab:: CLI
+
+     Metadata can be reset with the :ref:`hasura metadata clear <hasura_metadata_clear>`
+     command.
+
+  .. tab:: Console
+
+     1. Click on the settings (⚙) icon at the top right corner of the console screen.
+     2. Click on ``Reset`` button.
+
+        .. thumbnail:: /img/graphql/core/migrations/metadata-reset.png
+           :alt: Reset metadata
+
+     3. A pop-up will appear prompting you to confirm the process.
+     4. A notification should appear indicating the success.
+
+  .. tab:: API
+
+   The reset of metadata can be done via the :ref:`clear_metadata metadata API <clear_metadata>`.
+
+   Here is an example using ``curl``:
+
+   .. code-block:: bash
+
+      curl -d'{"type": "clear_metadata", "args": {}}' http://localhost:8080/v1/query
+
+   If an admin secret is set, add ``-H 'X-Hasura-Admin-Secret: <your-admin-secret>'`` as the API is an
+   admin-only API.
+
 Managing Hasura metadata in CI/CD
 ---------------------------------