1
0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-20 22:11:45 +03:00
graphql-engine/docs/graphql/core/api-reference/schema-metadata-api/manage-metadata.rst
Rakesh Emmadi edf5a0661e server: support mssql views
GitOrigin-RevId: 50e2fc1d64a67a9284ae62d2401ca6f9627ebdab
2021-03-05 10:53:38 +00:00

267 lines
6.0 KiB
ReStructuredText

.. 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
- If set to ``true``, all remote schemas' (including inconsistent ones) cached GraphQL schemas are refreshed (default: ``false``)
.. _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": {}
}