.. 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 (v2.0 and above) ======================================================== .. 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 `. .. _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 ` 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": } .. _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": } } 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": {} }