docs: add api reference for new metadata api endpoint

GitOrigin-RevId: e86aa47899a030707adf14b1ea235644fc48d726

docs/graphql/core/api-reference/index.rst

@@ -171,3 +171,4 @@ See details at :ref:`explain_api_reference`.
   PG Dump API <pgdump>
   Config API <config>
   Explain API <explain>
+  Common syntax definitions <syntax-defs>

docs/graphql/core/api-reference/metadata-api/actions.rst

@@ -0,0 +1,279 @@
+.. meta::
+   :description: Manage actions with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, actions
+
+.. _metadata_api_actions:
+
+Metadata API Reference: Actions (v1.4 and above)
+================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+**actions** are user defined mutations with custom business logic.
+
+.. _metadata_create_action:
+
+create_action
+-------------
+
+``create_action`` is used to define an action. There shouldn't be an existing action with the same name.
+
+Create a synchronous action with name ``create_user``:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+      "type":"create_action",
+      "args":{
+         "name":"create_user",
+         "definition":{
+            "kind":"synchronous",
+            "arguments":[
+               {
+                  "name":"username",
+                  "type":"String!"
+               },
+               {
+                  "name":"email",
+                  "type":"String!"
+               }
+            ],
+            "output_type":"User",
+            "handler":"https://action.my_app.com/create-user",
+            "timeout":60
+         },
+         "comment": "Custom action to create user"
+      }
+   }
+
+
+.. _metadata_create_action_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`ActionName <ActionName>`
+     - Name of the action
+   * - definition
+     - true
+     - :ref:`ActionDefinition`
+     - Definition of the action
+   * - comment
+     - false
+     - text
+     - comment
+
+.. note::
+
+   The ``GraphQL Types`` used in creating an action must be defined before via :ref:`Custom Types <metadata_api_custom_types>`
+
+.. _metadata_drop_action:
+
+drop_action
+-----------
+
+``drop_action`` is used to remove an action. Permissions defined on the actions are also dropped automatically.
+
+Drop an action ``create_user``:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+      "type":"drop_action",
+      "args":{
+         "name":"create_user",
+         "clear_data": true
+      }
+   }
+
+.. _metadata_drop_action_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`ActionName <ActionName>`
+     - Name of the action
+   * - clear_data
+     - false
+     - boolean
+     - If set to ``true`` and action kind is ``asynchronous``, related data is deleted from catalog. (default: ``true``)
+
+.. _metadata_update_action:
+
+update_action
+-------------
+
+``update_action`` is used to update the definition of the action. Definition thus provided is
+replaced with existing one.
+
+Update an action ``create_user`` by making it's kind to ``asynchronous``:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+      "type":"update_action",
+      "args":{
+         "name":"create_user",
+         "definition":{
+            "kind":"asynchronous",
+            "arguments":[
+               {
+                  "name":"username",
+                  "type":"String!"
+               },
+               {
+                  "name":"email",
+                  "type":"String!"
+               }
+            ],
+            "output_type":"User",
+            "handler":"https://action.my_app.com/create-user"
+         }
+      }
+   }
+
+
+.. _metadata_update_action_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`ActionName <ActionName>`
+     - Name of the action
+   * - definition
+     - true
+     - :ref:`ActionDefinition`
+     - Definition of the action to be replaced
+
+.. _metadata_create_action_permission:
+
+create_action_permission
+------------------------
+
+``create_action_permission`` is used to define a permission to make action visible for a role.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+     "type": "create_action_permission",
+     "args": {
+       "action": "create_user",
+       "role": "user"
+     }
+   }
+
+.. _metadata_create_action_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - action
+     - true
+     - :ref:`ActionName <ActionName>`
+     - Name of the action
+   * - role
+     - true
+     - :ref:`RoleName <RoleName>`
+     - Name of the role
+   * - comment
+     - false
+     - text
+     - comment
+
+.. _metadata_drop_action_permission:
+
+drop_action_permission
+----------------------
+
+``drop_action_permission`` is used to drop a permission defined on an action.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+     "type": "drop_action_permission",
+     "args": {
+       "action": "create_user",
+       "role": "user"
+     }
+   }
+
+.. _metadata_drop_action_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`ActionName <ActionName>`
+     - Name of the action
+   * - role
+     - true
+     - :ref:`RoleName <RoleName>`
+     - Name of the role

docs/graphql/core/api-reference/metadata-api/computed-field.rst

@@ -0,0 +1,154 @@
+.. meta::
+   :description: Manage computed fields with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, computed field
+
+.. _metadata_api_computed_field:
+
+Metadata API Reference: Computed Fields (v1.4 and above)
+========================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+**computed field** is an extra field added to a table, its value is
+computed via an SQL function which has the table row type as an input argument.
+Currenty, the Hasura GraphQL engine supports functions returning
+`base types <https://www.postgresql.org/docs/current/extend-type-system.html#id-1.8.3.5.9>`__ or
+`table row types <https://www.postgresql.org/docs/current/rowtypes.html#ROWTYPES-DECLARING>`__
+as computed fields.
+
+.. _pg_add_computed_field:
+
+pg_add_computed_field
+---------------------
+
+``pg_add_computed_field`` is used to define a computed field in a table.
+There cannot be an existing column or relationship or computed field with
+the same name.
+
+Create a ``computed field`` called ``full_name`` on an ``author`` *table*, using
+an SQL function called ``author_full_name``:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type":"pg_add_computed_field",
+       "args":{
+           "table":{
+               "name":"author",
+               "schema":"public"
+           },
+           "source": "default",
+           "name":"full_name",
+           "definition":{
+               "function":{
+                   "name":"author_full_name",
+                   "schema":"public"
+               },
+               "table_argument":"author_row"
+           }
+       }
+   }
+
+.. _pg_add_computed_field_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName <TableName>`
+     - Name of the table
+   * - name
+     - true
+     - :ref:`ComputedFieldName <ComputedFieldName>`
+     - Name of the new computed field
+   * - definition
+     - true
+     - :ref:`ComputedFieldDefinition`
+     - The computed field definition
+   * - comment
+     - false
+     - text
+     - comment
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_drop_computed_field:
+
+pg_drop_computed_field
+----------------------
+
+``pg_drop_computed_field`` is used to drop a computed field of a table. If
+there are other objects dependent on this computed field, like permissions, the request will fail and report the
+dependencies unless ``cascade`` is set to ``true``. If ``cascade`` is set to ``true``, the dependent objects
+are also dropped.
+
+Drop a computed field ``full_name`` from a table ``author``:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type":"pg_drop_computed_field",
+       "args":{
+           "table":{
+               "name":"author",
+               "schema":"public"
+           },
+           "source": "default",
+           "name":"full_name",
+           "cascade": false
+       }
+   }
+
+.. _pg_drop_computed_field_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName <TableName>`
+     - Name of the table
+   * - name
+     - true
+     - :ref:`ComputedFieldName <ComputedFieldName>`
+     - Name of the computed field
+   * - cascade
+     - false
+     - Boolean
+     - When set to ``true``, all the dependent items (if any) on this computed fields are also dropped
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+

docs/graphql/core/api-reference/metadata-api/custom-functions.rst

@@ -4,8 +4,8 @@
 
 .. _metadata_api_custom_functions:
 
-Metadata API Reference: Custom Functions
+Metadata API Reference: Custom Functions (v1.4 and above)
-========================================
+=========================================================
 
 .. contents:: Table of contents
   :backlinks: none
@@ -19,7 +19,146 @@ Track/untrack a custom SQL function in the Hasura GraphQL engine.
 
 Only tracked custom functions are available for querying/mutating/subscribing data over the GraphQL API.
 
-.. TODO: add other existing APIs
+.. _pg_track_function:
+
+pg_track_function
+-----------------
+
+``pg_track_function`` is used to add a custom SQL function to the GraphQL schema.
+It supports more configuration options than v1, and also supports tracking
+functions as mutations.
+Also refer a note :ref:`here <function_req_note>`.
+
+Track an SQL function called ``search_articles`` with a Hasura session argument:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_track_function",
+       "args": {
+           "function": {
+               "schema": "public",
+               "name": "search_articles"
+           },
+           "source": "default",
+           "configuration": {
+               "session_argument": "hasura_session"
+           }
+       }
+   }
+
+Track ``VOLATILE`` SQL function ``reset_widget`` as a mutation, so it appears
+as a top-level field under the ``mutation`` root field:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_track_function",
+       "args": {
+           "function": {
+               "schema": "public",
+               "name": "reset_widget"
+           },
+           "configuration": {
+               "exposed_as": "mutation"
+           }
+       }
+   }
+
+If ``exposed_as`` is omitted, the location in the schema to expose the function
+will be inferred from the function's volatility, with ``VOLATILE`` functions
+appearing under the ``mutation`` root, and others ending up under
+``query/subscription``.
+
+In most cases you will want ``VOLATILE`` functions to only be exposed as
+mutations, and only ``STABLE`` and ``IMMUTABLE`` functions to be queries.
+When tracking ``VOLATILE`` functions under the ``query`` root, the user needs
+to guarantee that the field is idempotent and side-effect free, in the context
+of the resulting GraphQL API.
+
+One such use case might be a function that wraps a simple query and performs
+some logging visible only to administrators.
+
+.. note::
+
+   It's easy to accidentally give an SQL function the wrong volatility (or for a
+   function to end up with ``VOLATILE`` mistakenly, since it's the default).
+
+.. _pg_track_function_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - function
+     - true
+     - :ref:`FunctionName <FunctionName>`
+     - Name of the SQL function
+   * - configuration
+     - false
+     - :ref:`Function Configuration <function_configuration>`
+     - Configuration for the SQL function
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the function (default: ``default``)
+
+.. _pg_untrack_function:
+
+pg_untrack_function
+-------------------
+
+``pg_untrack_function`` is used to remove a SQL function from the GraphQL schema.
+
+Remove an SQL function ``search_articles``:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_untrack_function",
+       "args": {
+           "schema": "public",
+           "name": "search_articles",
+           "source": "default"
+       }
+   }
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`FunctionName <FunctionName>`
+     - Name of the SQL function
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the function (default: ``default``)
 
 .. _pg_create_function_permission:
 
@@ -40,11 +179,12 @@ target table of the function.
        "type": "pg_create_function_permission",
        "args": {
           "function": "get_articles",
+          "source": "default",
           "role": "user"
        }
    }
 
-.. _pg_create_function_permission_args_syntax:
+.. _pg_create_function_permission_syntax:
 
 Args syntax
 ^^^^^^^^^^^
@@ -67,7 +207,7 @@ Args syntax
    * - source
      - false
      - Text
-     - Name of the source of the SQL function
+     - Name of the source database of the function (default: ``default``)
 
 .. _pg_drop_function_permission:
 
@@ -86,11 +226,12 @@ pg_drop_function_permission
        "type": "pg_drop_function_permission",
        "args": {
           "function": "get_articles",
-          "role": "user"
+          "role": "user",
+          "source": "default"
        }
    }
 
-.. _pg_drop_function_permission_args_syntax:
+.. _pg_drop_function_permission_syntax:
 
 Args syntax
 ^^^^^^^^^^^
@@ -113,4 +254,4 @@ Args syntax
    * - source
      - false
      - Text
-     - Name of the source of the SQL function
+     - Name of the source database of the function (default: ``default``)

docs/graphql/core/api-reference/metadata-api/custom-types.rst

@@ -0,0 +1,106 @@
+.. meta::
+   :description: Define custom types with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, custom types
+
+.. _metadata_api_custom_types:
+
+Metadata API Reference: Custom Types (v1.4 and above)
+=====================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+**Custom Types** are user-defined GraphQL types which help to define :ref:`Actions <api_actions>`.
+
+.. _metadata_set_custom_types:
+
+set_custom_types
+----------------
+
+``set_custom_types`` is used to set user-defined GraphQL types. This API will replace the given types with existing ones.
+
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+     "type": "set_custom_types",
+     "args": {
+       "scalars": [],
+       "enums": [],
+       "input_objects": [
+         {
+           "name": "User",
+           "fields": [
+             {
+               "name": "username",
+               "type": "String!"
+             },
+             {
+               "name": "password",
+               "type": "String!"
+             }
+           ]
+         }
+       ],
+       "objects": [
+         {
+           "name": "UserId",
+           "fields": [
+             {
+               "name": "id",
+               "type": "Int!"
+             }
+           ],
+           "relationships": [
+             {
+               "name": "posts",
+               "type": "array",
+               "remote_table": "post",
+               "field_mapping": {
+                 "id": "user_id"
+               }
+             }
+           ]
+         }
+       ]
+     }
+   }
+
+
+.. _metadata_set_custom_types_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - input_objects
+     - false
+     - Array of :ref:`InputObjectType`
+     - Set of GraphQL ``Input Object``
+   * - objects
+     - false
+     - Array of :ref:`ObjectType`
+     - Set of GraphQL ``Object``
+   * - scalars
+     - false
+     - Array of :ref:`ScalarType`
+     - Set of GraphQL ``Scalar``
+   * - enums
+     - false
+     - Array of :ref:`EnumType`
+     - Set of GraphQL ``Enum``

docs/graphql/core/api-reference/metadata-api/event-triggers.rst

@@ -0,0 +1,258 @@
+.. meta::
+   :description: Manage event triggers with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, event trigger
+
+.. _metadata_api_event_triggers:
+
+Metadata API Reference: Event Triggers (v1.4 and above)
+=======================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Event triggers are used to capture database changes and send them to a configured webhook.
+
+.. _pg_create_event_trigger:
+
+pg_create_event_trigger
+-----------------------
+
+``pg_create_event_trigger`` is used to create a new event trigger or replace an existing event trigger.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_create_event_trigger",
+       "args" : {
+           "name": "sample_trigger",
+           "table": {
+              "name": "users",
+              "schema": "public"
+           },
+           "source": "default",
+           "webhook": "https://httpbin.org/post",
+           "insert": {
+               "columns": "*",
+               "payload": ["username"]
+           },
+           "update": {
+               "columns": ["username", "real_name"],
+               "payload": "*"
+           },
+           "delete": {
+               "columns": "*"
+           },
+           "headers":[
+             {
+                 "name": "X-Hasura-From-Val",
+                 "value": "myvalue"
+             },
+             {
+                 "name": "X-Hasura-From-Env",
+                 "value_from_env": "EVENT_WEBHOOK_HEADER"
+             }
+           ],
+           "replace": false
+       }
+   }
+
+.. _pg_create_event_trigger_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`TriggerName <TriggerName>`
+     - Name of the event trigger
+   * - table
+     - true
+     - :ref:`QualifiedTable <QualifiedTable>`
+     - Object with table name and schema
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+   * - webhook
+     - false
+     - String
+     - Full url of webhook (*)
+   * - webhook_from_env
+     - false
+     - String
+     - Environment variable name of webhook (must exist at boot time) (*)
+   * - insert
+     - false
+     - :ref:`OperationSpec`
+     - Specification for insert operation
+   * - update
+     - false
+     - :ref:`OperationSpec`
+     - Specification for update operation
+   * - delete
+     - false
+     - :ref:`OperationSpec`
+     - Specification for delete operation
+   * - headers
+     - false
+     - [ :ref:`HeaderFromValue <HeaderFromValue>` | :ref:`HeaderFromEnv <HeaderFromEnv>` ]
+     - List of headers to be sent with the webhook
+   * - retry_conf
+     - false
+     - :ref:`RetryConf`
+     - Retry configuration if event delivery fails
+   * - replace
+     - false
+     - Boolean
+     - If set to true, the event trigger is replaced with the new definition
+   * - enable_manual
+     - false
+     - Boolean
+     - If set to true, the event trigger can be invoked manually 
+
+(*) Either ``webhook`` or ``webhook_from_env`` are required.
+
+.. _pg_delete_event_trigger:
+
+pg_delete_event_trigger
+-----------------------
+
+``pg_delete_event_trigger`` is used to delete an event trigger.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_delete_event_trigger",
+       "args" : {
+           "name": "sample_trigger",
+           "source": "default"
+       }
+   }
+
+.. _pg_delete_event_trigger_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`TriggerName <TriggerName>`
+     - Name of the event trigger
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the trigger (default: ``default``)
+
+.. _pg_redeliver_event:
+
+pg_redeliver_event
+------------------
+
+``redeliver_event`` is used to redeliver an existing event. For example, if an event is marked as error (
+say it did not succeed after retries), you can redeliver it using this API. Note that this will reset the count of retries so far.
+If the event fails to deliver, it will be retried automatically according to its ``retry_conf``.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_redeliver_event",
+       "args" : {
+           "event_id": "ad4f698f-a14e-4a6d-a01b-38cd252dd8bf"
+       }
+   }
+
+.. _pg_redeliver_event_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - event_id
+     - true
+     - String
+     - UUID of the event
+
+
+.. _pg_invoke_event_trigger:
+
+pg_invoke_event_trigger
+-----------------------
+
+``invoke_event_trigger`` is used to invoke an event trigger with custom payload.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_invoke_event_trigger",
+       "args" : {
+           "name": "sample_trigger",
+           "source": "default",
+           "payload": {}
+       }
+   }
+
+.. _pg_invoke_event_trigger_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`TriggerName <TriggerName>`
+     - Name of the event trigger
+   * - payload
+     - true
+     - JSON
+     - Some JSON payload to send to trigger
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the trigger (default: ``default``)

docs/graphql/core/api-reference/metadata-api/index.rst

@@ -48,9 +48,9 @@ Request body
 
 .. parsed-literal::
 
-   Query_
+   :ref:`Query <metadata_query>`
 
-.. _Query:
+.. _metadata_query:
 
 Query
 *****
@@ -93,30 +93,342 @@ The various types of queries are listed in the following table:
      - Synopsis
 
    * - **bulk**
-     - :ref:`Query <Query>` array
+     - :ref:`Query <metadata_query>` array
      - 1
      - Execute multiple operations in a single query
 
-   * - :ref:`pg_create_function_permission`
+   * - :ref:`pg_add_source <pg_add_source>`
-     - :ref:`pg_create_function_permission_args <pg_create_function_permission_args_syntax>`
+     - :ref:`pg_add_source_args <pg_add_source_syntax>`
      - 1
-     - Create a function permission
+     - Add a Postgres database
+
+   * - :ref:`pg_drop_source <pg_drop_source>`
+     - :ref:`pg_drop_source_args <pg_drop_source_syntax>`
+     - 1
+     - Remove a Postgres database
+
+   * - :ref:`pg_track_table <pg_track_table>`
+     - :ref:`pg_track_table_args <pg_track_table_syntax>`
+     - 1
+     - Add a Postgres table/view with configuration
+
+   * - :ref:`pg_untrack_table`
+     - :ref:`pg_untrack_table_args <pg_untrack_table_syntax>`
+     - 1
+     - Remove a Postgres table/view
+
+   * - :ref:`pg_set_table_customization <pg_set_table_customization>`
+     - :ref:`pg_set_table_customization_args <pg_set_table_customization_syntax>`
+     - 1
+     - Set table customization of an already tracked Postgres table
+
+   * - :ref:`pg_set_table_is_enum`
+     - :ref:`pg_set_table_is_enum_args <pg_set_table_is_enum_syntax>`
+     - 1
+     - Set a tracked Postgres table as an enum table
+
+   * - :ref:`pg_track_function`
+     - :ref:`pg_track_function_args <pg_track_function_syntax>`
+     - 1
+     - Add a Postgres SQL function with configuration
+
+   * - :ref:`pg_untrack_function`
+     - :ref:`FunctionName <FunctionName>`
+     - 1
+     - Remove a Postgres SQL function
+
+   * - :ref:`pg_create_function_permission`
+     - :ref:`pg_create_function_permission_args <pg_create_function_permission_syntax>`
+     - 1
+     - Create a Postgres function permission
 
    * - :ref:`pg_drop_function_permission`
-     - :ref:`pg_drop_function_permission_args <pg_drop_function_permission_args_syntax>`
+     - :ref:`pg_drop_function_permission_args <pg_drop_function_permission_syntax>`
      - 1
-     - Drop an existing function permission
+     - Drop an existing Postgres function permission
 
-   * - :ref:`export_metadata`
+   * - :ref:`pg_create_object_relationship`
-     - :ref:`export_metadata_examples`
+     - :ref:`pg_create_object_relationship_args <pg_create_object_relationship_syntax>`
+     - 1
+     - Define a new object relationship between Postgres tables/views
+
+   * - :ref:`pg_create_array_relationship`
+     - :ref:`pg_create_array_relationship_args <pg_create_array_relationship_syntax>`
+     - 1
+     - Define a new array relationship between Postgres tables/views
+
+   * - :ref:`pg_drop_relationship`
+     - :ref:`pg_drop_relationship_args <pg_drop_relationship_syntax>`
+     - 1
+     - Drop an existing Postgres relationship
+
+   * - :ref:`pg_rename_relationship`
+     - :ref:`pg_rename_relationship_args <pg_rename_relationship_syntax>`
+     - 1
+     - Modify name of an existing Postgres relationship
+
+   * - :ref:`pg_set_relationship_comment`
+     - :ref:`pg_set_relationship_comment_args <pg_set_relationship_comment_syntax>`
+     - 1
+     - Set comment on an existing Postgres relationship
+
+   * - :ref:`pg_add_computed_field`
+     - :ref:`pg_add_computed_field_args <pg_add_computed_field_syntax>`
+     - 1
+     - Add a computed field to a Postgres table/view
+
+   * - :ref:`pg_drop_computed_field`
+     - :ref:`pg_drop_computed_field_args <pg_drop_computed_field_syntax>`
+     - 1
+     - Drop a Postgres computed field
+
+   * - :ref:`pg_create_insert_permission`
+     - :ref:`pg_create_insert_permission_args <pg_create_insert_permission_syntax>`
+     - 1
+     - Specify insert permission for a Postgres table/view
+
+   * - :ref:`pg_drop_insert_permission`
+     - :ref:`pg_drop_insert_permission_args <pg_drop_insert_permission_syntax>`
+     - 1
+     - Remove existing insert permission for a Postgres table/view
+
+   * - :ref:`pg_create_select_permission`
+     - :ref:`pg_create_select_permission_args <pg_create_select_permission_syntax>`
+     - 1
+     - Specify select permission for a Postgres table/view
+
+   * - :ref:`pg_drop_select_permission`
+     - :ref:`pg_drop_select_permission_args <pg_drop_select_permission_syntax>`
+     - 1
+     - Remove existing select permission for a Postgres table/view
+
+   * - :ref:`pg_create_update_permission`
+     - :ref:`pg_create_update_permission_args <pg_create_update_permission_syntax>`
+     - 1
+     - Specify update permission for a Postgres table/view
+
+   * - :ref:`pg_drop_update_permission`
+     - :ref:`pg_drop_update_permission_args <pg_drop_update_permission_syntax>`
+     - 1
+     - Remove existing update permission for a Postgres table/view
+
+   * - :ref:`pg_create_delete_permission`
+     - :ref:`pg_create_delete_permission_args <pg_create_delete_permission_syntax>`
+     - 1
+     - Specify delete permission for a Postgres table/view
+
+   * - :ref:`pg_drop_delete_permission`
+     - :ref:`pg_drop_delete_permission_args <pg_drop_delete_permission_syntax>`
+     - 1
+     - Remove existing delete permission for a Postgres table/view
+
+   * - :ref:`pg_set_permission_comment`
+     - :ref:`pg_set_permission_comment_args <pg_set_permission_comment_syntax>`
+     - 1
+     - Set comment on an existing permission for a Postgres table/view
+
+   * - :ref:`pg_create_event_trigger`
+     - :ref:`pg_create_event_trigger_args <pg_create_event_trigger_syntax>`
+     - 1
+     - Create or replace an event trigger on a Postgres table
+
+   * - :ref:`pg_delete_event_trigger`
+     - :ref:`pg_delete_event_trigger_args <pg_delete_event_trigger_syntax>`
+     - 1
+     - Delete an existing event trigger on a Postgres table
+
+   * - :ref:`pg_redeliver_event`
+     - :ref:`pg_redeliver_event_args <pg_redeliver_event_syntax>`
+     - 1
+     - Redeliver an existing event on a Postgres table
+
+   * - :ref:`pg_invoke_event_trigger`
+     - :ref:`pg_invoke_event_trigger_args <pg_invoke_event_trigger_syntax>`
+     - 1
+     - Invoke a trigger with custom payload on a Postgres table
+
+   * - :ref:`metadata_create_cron_trigger`
+     - :ref:`create_cron_trigger_args <metadata_create_cron_trigger_syntax>`
+     - 1
+     - Create a cron trigger
+
+   * - :ref:`metadata_delete_cron_trigger`
+     - :ref:`delete_cron_trigger_args <metadata_delete_cron_trigger_syntax>`
+     - 1
+     - Delete an existing cron trigger
+
+   * - :ref:`metadata_create_scheduled_event`
+     - :ref:`create_scheduled_event_args <metadata_create_scheduled_event_syntax>`
+     - 1
+     - Create a new scheduled event
+
+   * - :ref:`metadata_add_remote_schema`
+     - :ref:`add_remote_schema_args <metadata_add_remote_schema_syntax>`
+     - 1
+     - Add a remote GraphQL server as a remote schema
+
+   * - :ref:`metadata_remove_remote_schema`
+     - :ref:`remove_remote_schema_args <metadata_remove_remote_schema_syntax>`
+     - 1
+     - Remove an existing remote schema
+
+   * - :ref:`metadata_reload_remote_schema`
+     - :ref:`reload_remote_schema_args <metadata_reload_remote_schema_syntax>`
+     - 1
+     - Reload schema of an existing remote schema
+
+   * - :ref:`metadata_add_remote_schema_permissions`
+     - :ref:`add_remote_schema_permissions <metadata_add_remote_schema_permissions_syntax>`
+     - 1
+     - Add permissions to a role of an existing remote schema
+
+   * - :ref:`metadata_drop_remote_schema_permissions`
+     - :ref:`drop_remote_schema_permissions <metadata_drop_remote_schema_permissions_syntax>`
+     - 1
+     - Drop existing permissions defined for a role for a remote schema
+
+   * - :ref:`metadata_create_remote_relationship`
+     - :ref:`create_remote_relationship_args <metadata_create_remote_relationship_syntax>`
+     - 1
+     - Create a remote relationship with an existing remote schema
+
+   * - :ref:`metadata_update_remote_relationship`
+     - :ref:`update_remote_relationship_args <metadata_update_remote_relationship_syntax>`
+     - 1
+     - Update an existing remote relationship
+
+   * - :ref:`metadata_delete_remote_relationship`
+     - :ref:`delete_remote_relationship_args <metadata_delete_remote_relationship_syntax>`
+     - 1
+     - Delete an existing remote relationship
+
+   * - :ref:`metadata_export_metadata`
+     - :ref:`Empty Object`
+     - 1
+     - Export the current metadata
+
+   * - :ref:`metadata_export_metadata`
+     - :ref:`Empty Object`
      - 2
      - Export existing metadata with resource version included.
 
-   * - :ref:`replace_metadata`
+   * - :ref:`metadata_replace_metadata`
-     - :ref:`replace_metadata_examples`
+     - :ref:`replace_metadata_args <metadata_replace_metadata_syntax>`
+     - 1
+     - Import and replace existing metadata
+
+
+   * - :ref:`metadata_replace_metadata`
+     - :ref:`replace_metadata_args <metadata_replace_metadata_syntax>`
      - 2
      - Replace existing metadata with check against current resource_version.
 
+   * - :ref:`metadata_reload_metadata`
+     - :ref:`Empty Object`
+     - 1
+     - Reload changes to the underlying Postgres DB
+
+   * - :ref:`metadata_clear_metadata`
+     - :ref:`Empty Object`
+     - 1
+     - Clear/wipe-out the current metadata state form server
+
+   * - :ref:`metadata_get_inconsistent_metadata`
+     - :ref:`Empty Object`
+     - 1
+     - List all inconsistent metadata objects
+
+   * - :ref:`metadata_drop_inconsistent_metadata`
+     - :ref:`Empty Object`
+     - 1
+     - Drop all inconsistent metadata objects
+
+   * - :ref:`metadata_create_query_collection`
+     - :ref:`create_query_collection_args <metadata_create_query_collection_syntax>`
+     - 1
+     - Create a query collection
+
+   * - :ref:`metadata_drop_query_collection`
+     - :ref:`drop_query_collection_args <metadata_drop_query_collection_syntax>`
+     - 1
+     - Drop a query collection
+
+   * - :ref:`metadata_add_query_to_collection`
+     - :ref:`add_query_to_collection_args <metadata_add_query_to_collection_syntax>`
+     - 1
+     - Add a query to a given collection
+
+   * - :ref:`metadata_drop_query_from_collection`
+     - :ref:`drop_query_from_collection_args <metadata_drop_query_from_collection_syntax>`
+     - 1
+     - Drop a query from a given collection
+
+   * - :ref:`metadata_add_collection_to_allowlist`
+     - :ref:`add_collection_to_allowlist_args <metadata_add_collection_to_allowlist_syntax>`
+     - 1
+     - Add a collection to the allow-list
+
+   * - :ref:`metadata_drop_collection_from_allowlist`
+     - :ref:`drop_collection_from_allowlist_args <metadata_drop_collection_from_allowlist_syntax>`
+     - 1
+     - Drop a collection from the allow-list
+
+   * - :ref:`metadata_set_custom_types`
+     - :ref:`set_custom_types_args <metadata_set_custom_types_syntax>`
+     - 1
+     - Set custom GraphQL types
+
+   * - :ref:`metadata_create_action`
+     - :ref:`create_action_args <metadata_create_action_syntax>`
+     - 1
+     - Create an action
+
+   * - :ref:`metadata_drop_action`
+     - :ref:`drop_action_args <metadata_drop_action_syntax>`
+     - 1
+     - Drop an action
+
+   * - :ref:`metadata_update_action`
+     - :ref:`update_action_args <metadata_update_action_syntax>`
+     - 1
+     - Update an action
+
+   * - :ref:`metadata_create_action_permission`
+     - :ref:`create_action_permission_args <metadata_create_action_permission_syntax>`
+     - 1
+     - Create an action permission
+
+   * - :ref:`metadata_drop_action_permission`
+     - :ref:`drop_action_permission_args <metadata_drop_action_permission_syntax>`
+     - 1
+     - Drop an action permission
+
+   * - :ref:`metadata_create_rest_endpoint`
+     - :ref:`create_rest_endpoint_args <metadata_create_rest_endpoint_syntax>`
+     - 1
+     - Create a RESTified GraphQL Endpoint
+
+   * - :ref:`metadata_drop_rest_endpoint`
+     - :ref:`drop_rest_endpoint_args <metadata_drop_rest_endpoint_syntax>`
+     - 1
+     - Drop a RESTified GraphQL Endpoint
+
+**See:**
+
+- :ref:`Tables/Views <metadata_api_tables_views>`
+- :ref:`Custom SQL Functions <metadata_api_custom_functions>`
+- :ref:`Relationships <metadata_api_relationship>`
+- :ref:`Computed Fields <metadata_api_computed_field>`
+- :ref:`Permissions <metadata_api_permission>`
+- :ref:`Remote Schema Permissions <metadata_remote_schema_api_permission>`
+- :ref:`Event Triggers <metadata_api_event_triggers>`
+- :ref:`Remote Schemas <metadata_api_remote_schemas>`
+- :ref:`Query Collections <metadata_api_query_collections>`
+- :ref:`Custom Types <metadata_api_custom_types>`
+- :ref:`Actions <metadata_api_actions>`
+- :ref:`Manage Metadata <metadata_api_manage_metadata>`
+
+
 Response structure
 ------------------
 
@@ -191,86 +503,23 @@ The ``resource_version`` supplied must match the version returned otherwise a 40
 
 The version is incremented on any operation that modified metadata as well as ``reload_metadata``.
 
+.. toctree::
+  :maxdepth: 1
+  :hidden:
 
-
+  Databases <source>
-.. _export_metadata_examples:
+  Tables/Views <table-view>
-
+  Custom Functions <custom-functions>
-Export Metadata Examples
+  Relationships <relationship>
-------------------------
+  Permissions <permission>
-
+  Remote Schema Permissions <remote-schema-permissions>
-``export_metadata`` is used to export the current metadata from the server as a JSON file.
+  Computed Fields <computed-field>
-
+  Event Triggers <event-triggers>
-V1 Example: See :ref:`export_metadata`
+  Scheduled Triggers <scheduled-triggers>
-
+  Remote Schemas <remote-schemas>
-V2 Example:
+  Remote Relationships <remote-relationships>
-
+  Query Collections <query-collections>
-.. code-block:: http
+  RESTified GraphQL Endpoints <restified-endpoints>
-
+  Custom Types <custom-types>
-   POST /v1/metadata HTTP/1.1
+  Actions <actions>
-   Content-Type: application/json
+  Manage Metadata <manage-metadata>
-   X-Hasura-Role: admin
-
-   {
-        "type": "export_metadata",
-        "version": 2,
-        "args": {}
-   }
-
-Response:
-
-.. code-block:: json
-
-    {
-    "resource_version": 8,
-    "metadata": {
-        "version": 3,
-        "sources": [
-        {
-            "name": "default",
-            "tables": [
-            {
-                "table": {
-
-.. _replace_metadata_examples:
-
-Replace Metadata Examples
--------------------------
-
-``replace_metadata`` is used to replace the current metadata with a JSON object.
-
-V1 Example: See :ref:`replace_metadata_syntax_v1`
-
-Version 2 example with inconsistencies and allow_inconsistent_metadata=true:
-
-    HTTP/1.1 200 OK
-
-.. code-block:: json
-
-    {
-    "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``:
-
-    HTTP/1.1 409 Conflict
-
-.. code-block:: json
-
-    {
-      "path": "$",
-      "error": "metadata resource version referenced (2) did not match current version",
-      "code": "conflict"
-    }

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

@@ -4,8 +4,8 @@
 
 .. _metadata_api_manage_metadata:
 
-Metadata API Reference: Manage metadata
+Metadata API Reference: Manage metadata (v1.4 and above)
-=======================================
+========================================================
 
 .. contents:: Table of contents
   :backlinks: none
@@ -17,9 +17,62 @@ Introduction
 
 APIs to manage Hasura metadata which is stored in ``hdb_catalog`` schema.
 
-.. TODO: add other existing APIs
+.. _metadata_export_metadata:
 
-.. _replace_metadata_v2:
+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
 ----------------
@@ -29,7 +82,7 @@ metadata will be replaced with the new one.
 
 .. code-block:: none
 
-    POST /v1/query HTTP/1.1
+    POST /v1/metadata HTTP/1.1
     Content-Type: application/json
     X-Hasura-Role: admin
 
@@ -39,13 +92,14 @@ metadata will be replaced with the new one.
         "args": <replace-metadata-args>
     }
 
-For version 1, this API corresponds to the legacy API documented under  :ref:`replace_metadata` in the ``/v1/query`` endpoint.
+.. _metadata_replace_metadata_syntax:
-
-.. _replace_metadata_syntax_v2:
 
 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
@@ -68,7 +122,7 @@ For version 2, the following structure is used:
      - 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`
+     - :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``.
@@ -119,3 +173,172 @@ Version 2 example with inconsistencies and allow_inconsistent_metadata=true incl
       }, ...
     ]
   }
+
+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
+       }
+   }
+
+.. _metadata_reload_metadata_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``)
+
+.. _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 postgres : \"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": {}
+   }

docs/graphql/core/api-reference/metadata-api/permission.rst

@@ -0,0 +1,636 @@
+.. meta::
+   :description: Manage permissions with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, permission
+
+.. _metadata_api_permission:
+
+Metadata API Reference: Permissions (v1.4 and above)
+====================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+The permission layer is designed to restrict the operations that can be
+performed by various users. Permissions can be defined on various operations
+(insert/select/update/delete) at a role level granularity. By default, the ``admin``
+role has unrestricted access to all operations.
+
+.. admonition:: Variables in rules
+
+   All ``X-Hasura-*`` header values can be used in the permission rules. These
+   values can come with the request and can be validated using webhook or can be
+   sent with the JWT token.
+
+.. _pg_create_insert_permission:
+
+pg_create_insert_permission
+---------------------------
+
+An insert permission is used to enforce constraints on the data that is being
+inserted.
+
+Let's look at an example, a permission for the ``user`` role to insert into the
+``article`` table. What is the constraint that we would like to enforce here? *A
+user can only insert articles for themselves* .
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_create_insert_permission",
+       "args" : {
+           "table" : "article",
+           "source": "default",
+           "role" : "user",
+           "permission" : {
+               "check" : {
+                   "author_id" : "X-HASURA-USER-ID"
+               },
+               "set":{
+                   "id":"X-HASURA-USER-ID"
+               },
+               "columns":["name","author_id"]
+           }
+       }
+   }
+
+This reads as follows - for the ``user`` role:
+
+* For every row that is being inserted into the *article* table, allow insert only if the ``check`` passes i.e. that the ``author_id`` column value is the same as the value in the request header ``X-HASURA-USER-ID``".
+
+* If the above ``check`` passes, then access for insert will be limited to columns ``name`` and ``author_id`` only.
+
+* When this insert happens, the value of the column ``id`` will be automatically ``set`` to the value of the resolved session variable ``X-HASURA-USER-ID``.
+
+
+The argument for ``check`` is a boolean expression which has the same syntax as the ``where`` clause in the ``select`` query, making it extremely expressive. 
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_create_insert_permission",
+       "args" : {
+           "table" : "article",
+           "source": "default",
+           "role" : "user",
+           "permission" : {
+               "check" : {
+                   "author_id" : "X-HASURA-USER-ID",
+                   "$or" : [
+                       {
+                           "category" : "editorial",
+                           "is_reviewed" : false
+                       },
+                       {
+                           "category" : { "$neq" : "editorial"}
+                       }
+                   ]
+               }
+           }
+       }
+   }
+
+In the above definition, the row is allowed to be inserted if the ``author_id``
+is the same as the request's user id and ``is_reviewed`` is ``false`` when the
+``category`` is "editorial".
+
+.. _pg_create_insert_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role
+   * - permission
+     - true
+     - :ref:`InsertPermission`
+     - The permission definition
+   * - comment
+     - false
+     - text
+     - Comment
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_drop_insert_permission:
+
+pg_drop_insert_permission
+-------------------------
+
+The ``pg_drop_insert_permission`` API is used to drop an existing insert permission for a role on a table.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_drop_insert_permission",
+       "args" : {
+           "table" : "article",
+           "source": "default",
+           "role" : "user"
+       }
+   }
+
+.. _pg_drop_insert_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_create_select_permission:
+
+pg_create_select_permission
+---------------------------
+
+A select permission is used to restrict access to only the specified columns and rows.
+
+Let's look at an example, a permission for the ``user`` role to select from the
+``article`` table: all columns can be read, as well as the rows that have been published or
+authored by the user themselves.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_create_select_permission",
+       "args" : {
+           "table" : "article",
+           "role" : "user",
+           "source": "default",
+           "permission" : {
+               "columns" : "*",
+               "filter" : {
+                   "$or" : [
+                       { "author_id" : "X-HASURA-USER-ID" },
+                       { "is_published" : true }
+                   ]
+                },
+                "limit": 10,
+                "allow_aggregations": true
+           }
+       }
+   }
+
+This reads as follows - For the ``user`` role:
+
+* Allow selecting rows where the ``check`` passes i.e. ``is_published`` is ``true`` or the ``author_id`` matches the value of the session variable ``X-HASURA-USER-ID``.
+
+* Allow selecting all columns (because the ``columns`` key is set to  ``*``).
+
+* ``limit`` the numbers of rows returned by a query to the ``article`` table by the ``user`` role to a maximum of 10.
+
+* Allow aggregate queries.
+
+.. _pg_create_select_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role
+   * - permission
+     - true
+     - :ref:`SelectPermission`
+     - The permission definition
+   * - comment
+     - false
+     - text
+     - Comment
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_drop_select_permission:
+
+pg_drop_select_permission
+-------------------------
+
+The ``pg_drop_select_permission`` is used to drop an existing select permission for a role on a table.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_drop_select_permission",
+       "args" : {
+           "table" : "article",
+           "role" : "user",
+           "source": "default"
+       }
+   }
+
+.. _pg_drop_select_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_create_update_permission:
+
+pg_create_update_permission
+---------------------------
+
+An update permission is used to restrict the columns and rows that can be
+updated. Its structure is quite similar to the select permission.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_create_update_permission",
+       "args" : {
+           "table" : "article",
+           "source": "default",
+           "role" : "user",
+           "permission" : {
+               "columns" : ["title", "content", "category"],
+               "filter" : {
+                   "author_id" : "X-HASURA-USER-ID"
+               },
+               "check" : {
+                   "content" : {
+                     "_ne": ""
+                   }
+               },
+               "set":{
+                   "updated_at" : "NOW()"
+               }
+           }
+       }
+   }
+
+This reads as follows - for the ``user`` role:
+
+* Allow updating only those rows where the ``filter`` passes i.e. the value of the ``author_id`` column of a row matches the value of the session variable ``X-HASURA-USER-ID``.
+
+* If the above ``filter`` passes for a given row, allow updating only the ``title``, ``content`` and ``category`` columns (*as specified in the* ``columns`` *key*).
+
+* After the update happens, verify that the ``check`` condition holds for the updated row i.e. that the value in the ``content`` column is not empty.
+
+* When this update happens, the value of the column ``updated_at`` will be automatically ``set`` to the current timestamp.
+
+.. note::
+
+   It is important to deny updates to columns that will determine the row
+   ownership. In the above example, the ``author_id`` column determines the
+   ownership of a row in the ``article`` table. Columns such as this should
+   never be allowed to be updated.
+
+.. _pg_create_update_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role
+   * - permission
+     - true
+     - :ref:`UpdatePermission`
+     - The permission definition
+   * - comment
+     - false
+     - text
+     - Comment
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_drop_update_permission:
+
+pg_drop_update_permission
+-------------------------
+
+The ``pg_drop_update_permission`` API is used to drop an existing update permission for a role on a table.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_drop_update_permission",
+       "args" : {
+           "table" : "article",
+           "source": "default",
+           "role" : "user"
+       }
+   }
+
+.. _pg_drop_update_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_create_delete_permission:
+
+pg_create_delete_permission
+---------------------------
+
+A delete permission is used to restrict the rows that can be deleted.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_create_delete_permission",
+       "args" : {
+           "table" : "article",
+           "source": "default",
+           "role" : "user",
+           "permission" : {
+               "filter" : {
+                   "author_id" : "X-HASURA-USER-ID"
+               }
+           }
+       }
+   }
+
+This reads as follows:
+
+"``delete`` for the ``user`` role on the ``article`` table is allowed on rows where
+``author_id`` is the same as the request header ``X-HASURA-USER-ID`` value."
+
+.. _pg_create_delete_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role
+   * - permission
+     - true
+     - :ref:`DeletePermission`
+     - The permission definition
+   * - comment
+     - false
+     - text
+     - Comment
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_drop_delete_permission:
+
+pg_drop_delete_permission
+-------------------------
+
+The ``pg_drop_delete_permission`` API is used to drop an existing delete permission for a role on a table.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "pg_drop_delete_permission",
+       "args" : {
+           "table" : "article",
+           "role" : "user",
+           "source": "default"
+       }
+   }
+
+.. _pg_drop_delete_permission_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_set_permission_comment:
+
+pg_set_permission_comment
+-------------------------
+
+``pg_set_permission_comment`` is used to set/update the comment on a permission.
+Setting the comment to ``null`` removes it.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   Authorization: Bearer <auth-token> # optional if cookie is set
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_set_permission_comment",
+       "args": {
+           "table": "article",
+           "source": "default",
+           "role": "user",
+           "type" : "update",
+           "comment" : "can only modify his/her own rows"
+       }
+   }
+
+.. _pg_set_permission_comment_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - role
+     - true
+     - :ref:`RoleName`
+     - The role in the permission
+   * - type
+     - true
+     - permission type (one of select/update/delete/insert)
+     - The type of the permission
+   * - comment
+     - false
+     - Text
+     - Comment
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+

docs/graphql/core/api-reference/metadata-api/query-collections.rst

@@ -0,0 +1,277 @@
+.. meta::
+   :description: Manage query collections with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, query collection
+
+.. _metadata_api_query_collections:
+
+Metadata API Reference: Query collections (v1.4 and above)
+==========================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Group queries using query collections.
+
+Create/drop query collections and add/drop a query to a collection using the following query types.
+
+.. _metadata_create_query_collection:
+
+create_query_collection
+-----------------------
+
+``create_query_collection`` is used to define a collection.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "create_query_collection",
+       "args": {
+            "name": "my_collection",
+            "comment": "an optional comment",
+            "definition": {
+                "queries": [
+                    {"name": "query_1", "query": "query { test {id name}}"}
+                 ]
+            }
+        }
+   }
+
+.. _metadata_create_query_collection_syntax:
+
+Args Syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`CollectionName`
+     - Name of the query collection
+   * - definition
+     - true
+     - :ref:`CollectionQuery` array
+     - List of queries
+   * - comment
+     - false
+     - text
+     - Optional comment
+
+
+.. _metadata_drop_query_collection:
+
+drop_query_collection
+---------------------
+
+``drop_query_collection`` is used to drop a collection
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "drop_query_collection",
+       "args": {
+            "collection": "my_collection",
+            "cascade": false
+        }
+   }
+
+.. _metadata_drop_query_collection_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - collection
+     - true
+     - :ref:`CollectionName`
+     - Name of the query collection
+   * - cascade
+     - true
+     - boolean
+     - When set to ``true``, the collection (if present) is removed from the allowlist
+
+.. _metadata_add_query_to_collection:
+
+add_query_to_collection
+-----------------------
+
+``add_query_to_collection`` is used to add a query to a given collection.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "add_query_to_collection",
+       "args": {
+            "collection_name": "my_collection",
+            "query_name": "query_2",
+            "query": "query {test {name}}"
+        }
+   }
+
+.. _metadata_add_query_to_collection_syntax:
+
+Args Syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - collection_name
+     - true
+     - :ref:`CollectionName`
+     - Name of the query collection
+   * - query_name
+     - true
+     - :ref:`QueryName`
+     - Name of the query
+   * - query
+     - true
+     - text
+     - The GraphQL query text
+
+.. _metadata_drop_query_from_collection:
+
+drop_query_from_collection
+--------------------------
+
+``drop_query_from_collection`` is used to remove a query from a given collection.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "drop_query_from_collection",
+       "args": {
+            "collection_name": "my_collection",
+            "query_name": "query_2"
+        }
+   }
+
+.. _metadata_drop_query_from_collection_syntax:
+
+Args Syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - collection_name
+     - true
+     - :ref:`CollectionName`
+     - Name of the query collection
+   * - query_name
+     - true
+     - :ref:`QueryName`
+     - Name of the query
+
+.. _metadata_add_collection_to_allowlist:
+
+add_collection_to_allowlist
+---------------------------
+
+``add_collection_to_allowlist`` is used to add a collection to the allow-list.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "add_collection_to_allowlist",
+       "args": {
+            "collection": "my_collection"
+        }
+   }
+
+.. _metadata_add_collection_to_allowlist_syntax:
+
+Args Syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - collection
+     - true
+     - :ref:`CollectionName`
+     - Name of a query collection to be added to the allow-list
+
+.. _metadata_drop_collection_from_allowlist:
+
+drop_collection_from_allowlist
+------------------------------
+
+``drop_collection_from_allowlist`` is used to remove a collection from the allow-list.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "drop_collection_from_allowlist",
+       "args": {
+            "collection": "my_collection_1"
+        }
+   }
+
+.. _metadata_drop_collection_from_allowlist_syntax:
+
+Args Syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - collection
+     - true
+     - :ref:`CollectionName`
+     - Name of a query collection to be removed from the allow-list

docs/graphql/core/api-reference/metadata-api/relationship.rst

@@ -0,0 +1,436 @@
+.. meta::
+   :description: Use relationships with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, relationship
+
+.. _metadata_api_relationship:
+
+Metadata API Reference: Relationships (v1.4 and above)
+======================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+When retrieving data from tables, it is very helpful if we can also
+fetch the related data alongside the columns. This is where relationships come
+in. They can be considered as pseudo columns for a table to access the related
+data.
+
+For a simple ``article/author`` schema, the following relationships exist:
+
+- ``author`` of an ``article``
+- ``articles`` of an ``author``
+
+There are two kinds of relationships:
+
+- one-to-one or ``object relationships`` (e.g. ``author``).
+- one-to-many or ``array relationships`` (e.g. ``articles``).
+
+.. _pg_create_object_relationship:
+
+pg_create_object_relationship
+-----------------------------
+
+``create_object_relationship`` is used to create an object relationship on a
+table. There cannot be an existing column or relationship with the same name. 
+
+There are 2 ways in which you can create an object relationship.
+
+1. Using foreign key constraint on a column
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create an ``object relationship`` ``author`` on ``article`` *table*,  *using* the
+*foreign_key_constraint_on* the ``author_id`` column:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_create_object_relationship",
+       "args": {
+           "table": "article",
+           "name": "author",
+           "source": "default",
+           "using": {
+               "foreign_key_constraint_on" : "author_id"
+           }
+       }
+   }
+
+
+.. _pg_manual_obj_relationship:
+
+2. Manual configuration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This is an advanced feature which is mostly used to define relationships on or
+to views. We cannot rely on foreign key constraints as they are not valid to or
+from views. So, when using manual configuration, we have to specify the remote
+table and how columns in this table are mapped to the columns of the
+remote table. 
+
+Let's say we have a view called ``article_detail`` which has three columns
+``article_id`` and ``view_count`` and ``average_rating``. We can now define an
+object relationship called ``article_detail`` on the ``article`` table as
+follows: 
+ 
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_create_object_relationship",
+       "args": {
+           "table": "article",
+           "name": "article_detail",
+           "source": "default",
+           "using": {
+               "manual_configuration" : {
+                   "remote_table" : "article_detail",
+                   "column_mapping" : {
+                       "id" : "article_id"
+                   }
+               }
+           }
+       }
+   }
+
+.. note::
+
+   It is easy to make mistakes while using ``manual_configuration``.
+   One simple check is to ensure that foreign key constraint semantics are valid
+   on the columns being used in ``column_mapping``. In the previous example, if
+   it was allowed, a foreign key constraint could have been defined on
+   ``article`` table's ``id`` column to ``article_detail`` view's ``article_id``
+   column.
+
+.. _pg_create_object_relationship_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName <TableName>`
+     - Name of the table
+   * - name
+     - true
+     - :ref:`RelationshipName <RelationshipName>`
+     - Name of the new relationship
+   * - using
+     - true
+     - :ref:`ObjRelUsing`
+     - Use one of the available ways to define an object relationship
+   * - comment
+     - false
+     - text
+     - comment
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_create_array_relationship:
+
+pg_create_array_relationship
+----------------------------
+
+``create_array_relationship`` is used to create an array relationship on a
+table. There cannot be an existing column or relationship with the same name. 
+
+There are 2 ways in which you can create an array relationship.
+
+1. Using foreign key constraint on a column
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create an ``array relationship`` ``articles`` on ``author`` *table*,  *using* the
+*foreign_key_constraint_on* the ``author_id`` column of the ``article`` table:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_create_array_relationship",
+       "args": {
+           "table": "author",
+           "name": "articles",
+           "source": "default",
+           "using": {
+               "foreign_key_constraint_on" : {
+                   "table" : "article",
+                   "column" : "author_id"
+               }
+           }
+       }
+   }
+
+
+2. Manual configuration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This is an advanced feature which is mostly used to define relationships on or
+to views. We cannot rely on foreign key constraints as they are not valid to or
+from views. So, when using manual configuration, we have to specify the remote
+table and how columns in this table are mapped to the columns of the
+remote table.
+
+Let's say we have a view called ``article_detail`` which has four columns
+``author_id``, ``article_id``, ``view_count`` and ``average_rating``. We can now define an
+array relationship called ``article_details`` on the ``author`` table as
+follows:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_create_array_relationship",
+       "args": {
+           "table": "author",
+           "name": "article_details",
+           "source": "default",
+           "using": {
+               "manual_configuration" : {
+                   "remote_table" : "article_detail",
+                   "column_mapping" : {
+                       "id" : "author_id"
+                   }
+               }
+           }
+       }
+   }
+
+.. note::
+
+   It is easy to make mistakes while using ``manual_configuration``.
+   One simple check is to ensure that foreign key constraint semantics are valid
+   on the columns being used in ``column_mapping``. In the previous example, if
+   it was allowed, a foreign key constraint could have been defined on the
+   ``author`` table's ``id`` column to ``article_detail`` view's ``author_id``
+   column.
+
+.. _pg_create_array_relationship_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - name
+     - true
+     - :ref:`RelationshipName`
+     - Name of the new relationship
+   * - using
+     - true
+     - :ref:`ArrRelUsing`
+     - Use one of the available ways to define an array relationship
+   * - comment
+     - false
+     - text
+     - comment
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_drop_relationship:
+
+pg_drop_relationship
+--------------------
+
+``pg_drop_relationship`` is used to drop a relationship (both object and array) on
+a table. If there are other objects dependent on this relationship like
+permissions and query templates, etc., the request will fail and report the dependencies
+unless ``cascade`` is set to ``true``. If ``cascade`` is set to ``true``, the
+dependent objects are also dropped. 
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_drop_relationship",
+       "args": {
+           "table": "article",
+           "source": "default",
+           "relationship": "article_detail"
+       }
+   }
+
+.. _pg_drop_relationship_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - relationship
+     - true
+     - :ref:`RelationshipName`
+     - Name of the relationship that needs to be dropped
+   * - cascade
+     - false
+     - Boolean
+     - When set to ``true``, all the dependent items on this relationship are also dropped
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. note::
+
+   Be careful when using ``cascade``. First, try running the request without
+   ``cascade`` or ``cascade`` set to ``false``.
+
+.. _pg_set_relationship_comment:
+
+pg_set_relationship_comment
+---------------------------
+
+``pg_set_relationship_comment`` is used to set/update the comment on a
+relationship. Setting the comment to ``null`` removes it.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_set_relationship_comment",
+       "args": {
+           "table": "article",
+           "source": "default",
+           "name": "article_detail",
+           "comment" : "has extra information about an article like count etc."
+       }
+   }
+
+.. _pg_set_relationship_comment_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - relationship
+     - true
+     - :ref:`RelationshipName`
+     - The relationship
+   * - comment
+     - false
+     - Text
+     - Comment
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+
+.. _pg_rename_relationship:
+
+pg_rename_relationship
+----------------------
+
+``pg_rename_relationship`` is used to modify the name of an existing relationship.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_rename_relationship",
+       "args": {
+           "table": "article",
+           "name": "article_details",
+           "source": "default",
+           "new_name": "article_detail"
+       }
+   }
+
+.. _pg_rename_relationship_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName`
+     - Name of the table
+   * - name
+     - true
+     - :ref:`RelationshipName`
+     - The relationship
+   * - new_name
+     - true
+     - :ref:`RelationshipName`
+     - New relationship name
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)

docs/graphql/core/api-reference/metadata-api/remote-relationships.rst

@@ -0,0 +1,190 @@
+.. meta::
+   :description: Manage remote relationships with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, remote joins, remote relationships
+
+Metadata API Reference: Remote Relationships (v1.4 and above)
+=============================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Remote Relationships allow you to join tables with remote schemas.
+
+.. _metadata_create_remote_relationship:
+
+create_remote_relationship
+--------------------------
+
+``create_remote_relationship`` is used to create a new remote relationship with an existing remote schema.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+      "type":"create_remote_relationship",
+      "args":{
+         "name": "sample_remote_relationship",
+         "table": "users",
+         "hasura_fields": ["id"],
+         "remote_schema": "my-remote-schema",
+         "remote_field": {
+           "messages": {
+              "arguments": {
+                 "id":"$id"
+              }
+           }
+         }
+      }
+   }
+
+.. _metadata_create_remote_relationship_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`RemoteRelationshipName`
+     - Name of the remote relationship
+   * - table
+     - true
+     - :ref:`QualifiedTable <QualifiedTable>`
+     - Object with table name and schema
+   * - hasura_fields
+     - true
+     - [:ref:`PGColumn <PGColumn>`]
+     - Column(s) in the table that is used for joining with remote schema field. All join keys in ``remote_field`` must appear here.
+   * - remote_schema
+     - true
+     - :ref:`RemoteSchemaName <RemoteSchemaName>`
+     - Name of the remote schema to join with
+   * - remote_field
+     - true
+     - :ref:`RemoteField`
+     - The schema tree ending at the field in remote schema which needs to be joined with.
+
+.. _metadata_update_remote_relationship:
+
+update_remote_relationship
+--------------------------
+
+``update_remote_relationship`` is used to update an existing remote relationship.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+     "type": "update_remote_relationship",
+     "args": {
+        "name": "sample_remote_relationship",
+        "table": "users",
+        "hasura_fields": ["id"],
+        "remote_schema": "my-remote-schema",
+        "remote_field": {
+          "posts": {
+             "arguments": {
+                "id": "$id",
+                "likes": {
+                   "lte":"1000"
+                }
+             }
+          }
+        }
+     }
+   }
+
+.. _metadata_update_remote_relationship_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`RemoteRelationshipName`
+     - Name of the remote relationship
+   * - table
+     - true
+     - :ref:`QualifiedTable <QualifiedTable>`
+     - Object with table name and schema
+   * - hasura_fields
+     - true
+     - [:ref:`PGColumn <PGColumn>`]
+     - Column(s) in the table that is used for joining with remote schema field. All join keys in ``remote_field`` must appear here.
+   * - remote_schema
+     - true
+     - :ref:`RemoteSchemaName <RemoteSchemaName>`
+     - Name of the remote schema to join with
+   * - remote_field
+     - true
+     - :ref:`RemoteField`
+     - The schema tree ending at the field in remote schema which needs to be joined with.
+
+.. _metadata_delete_remote_relationship:
+
+delete_remote_relationship
+--------------------------
+
+``delete_remote_relationship`` is used to delete an existing remote relationship.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "delete_remote_relationship",
+       "args" : {
+          "table":{
+             "name":"users",
+             "schema":"public"
+          },
+          "name":"sample_remote_relationship"
+       }
+   }
+
+.. _metadata_delete_remote_relationship_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`QualifiedTable <QualifiedTable>`
+     - Object with table name and schema
+   * - name
+     - true
+     - :ref:`RemoteRelationshipName`
+     - Name of the remote relationship

docs/graphql/core/api-reference/metadata-api/remote-schema-permissions.rst

@@ -0,0 +1,385 @@
+.. meta::
+   :description: Manage remote schema permissions with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, remote schema permissions, permission
+
+.. _metadata_remote_schema_api_permission:
+
+Metadata API Reference: Remote Schema Permissions (v1.4 and above)
+==================================================================
+
+.. contents:: Table of contents
+   :backlinks: none
+   :depth: 1
+   :local:
+
+Introduction
+------------
+
+Remote schema permissions can be defined to:
+
+1. Expose only certain parts of the remote schema to a role
+2. Preset arguments with static values or session variables for any field.
+
+By default, the ``admin`` role has unrestricted access to
+the  remote schema.
+
+.. _metadata_add_remote_schema_permissions:
+
+add_remote_schema_permissions
+-----------------------------
+
+This API takes the schema `(GraphQL IDL format) <http://spec.graphql.org/June2018/#sec-Type-System>`__
+which should be a subset of the remote schema and the role for which this restricted schema is exposed.
+The schema also accepts a custom ``@preset`` directive for setting argument presets.
+
+
+Suppose the following is the schema document of the  remote.
+
+.. code-block:: graphql
+
+  type User {
+    user_id: Int
+    name: String
+    phone: String
+    userMessages(whered: MessageWhereInpObj, includes: IncludeInpObj): [Message]
+  }
+
+  interface Communication {
+    id: Int!
+    msg: String!
+  }
+
+  type Message implements Communication {
+    id: Int!
+    name: String!
+    msg: String!
+    errorMsg: String
+  }
+
+  input MessageWhereInpObj {
+    id: IntCompareObj
+    name: StringCompareObj
+  }
+
+  input IntCompareObj {
+    eq : Int
+    gt : Int
+    lt : Int
+  }
+
+  input StringCompareObj {
+    eq : String
+  }
+
+  input IncludeInpObj {
+    id: [Int]
+    name: [String]
+  }
+
+  type Query {
+    hello: String
+    messages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message]
+    user(user_id: Int!): User
+    users(user_ids: [Int]!): [User]
+    message(id: Int!) : Message
+  }
+
+  type mutation_root {
+    insert_user: (name: String!, phone: String!): User
+  }
+
+  schema {
+    query: Query
+    mutation: mutation_root
+  }
+
+Let's say we want to impose some restrictions on the ``user`` role:
+
+1. Expose only the ``user_id``, ``name`` and the ``user_messages`` field in the ``User`` object.
+2. Add a preset value to the ``user_id`` argument of the ``user`` field defined in the ``Query`` object.
+   We want the value of the preset to come from a session variable called ``x-hasura-user-id``.
+3. Allow filtering of the messages only by ``name`` in the ``where`` argument
+   of the ``user_messages`` field.
+4. Allow only the fields ``hello``, ``messages`` and the ``user`` top level node in the ``Query`` object.
+5. Expose only the ``query_root`` and not allow mutations for the role.
+
+The schema document, implementing the above restrictions will look like:
+
+.. code-block:: graphql
+
+  type User {
+    user_id: Int
+    name: String
+    userMessages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message]
+  }
+
+  interface Communication {
+    id: Int!
+    msg: String!
+  }
+
+  type Message implements Communication {
+    id: Int!
+    name: String!
+    msg: String!
+    errorMsg: String
+  }
+
+  input MessageWhereInpObj {
+    name: StringCompareObj
+  }
+
+  input IntCompareObj {
+    eq : Int
+    gt : Int
+    lt : Int
+  }
+
+  input StringCompareObj {
+    eq : String
+  }
+
+  input IncludeInpObj {
+    id: [Int]
+    name: [String]
+  }
+
+  type Query {
+    hello: String
+    messages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message]
+    user(user_id: Int! @preset(value: "x-hasura-user-id")): User
+  }
+
+  schema {
+    query: Query
+  }
+
+To add the remote schema permission for the role ``user``, the following
+API should be called with the schema document.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "add_remote_schema_permissions",
+       "args" : {
+           "remote_schema" : "user_messages",
+           "role" : "user",
+           "definition" : {
+               "schema" : "type User {     user_id: Int     name: String     userMessages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message]   }    interface Communication {     id: Int!     msg: String!   }    type Message implements Communication {     id: Int!     name: String!     msg: String!     errorMsg: String   }    input MessageWhereInpObj {     name: StringCompareObj   }    input IntCompareObj {     eq : Int     gt : Int     lt : Int   }    input StringCompareObj {     eq : String   }    input IncludeInpObj {     id: [Int]     name: [String]   }    type Query {     hello: String     messages(where: MessageWhereInpObj, includes: IncludeInpObj): [Message]     user(user_id: Int! @preset(value: \"x-hasura-user-id\")): User   }    schema {     query: Query  }"
+           },
+          "comment":"remote schema permissions for role: user"
+       }
+   }
+
+Argument Presets
+^^^^^^^^^^^^^^^^
+
+Argument presets can be used to automatically inject input values for fields
+during execution. This way the field is executed with limited input values. Argument
+presets are of two types:
+
+1. Static Value
+2. :ref:`Session Variable <dynamic_session_variables>`
+
+A preset value can be added to an input value via the ``@preset`` directive.
+
+.. code-block:: graphql
+
+   type User {
+     name String
+     id   Int
+   }
+
+   type Query {
+     user(user_id: Int! @preset(value: 1))
+   }
+
+When an input field has a preset defined, it will be removed from the exposed schema. So, following
+the above example, the user won't be able to specify the ``user_id`` argument while querying
+the ``user`` field and whenever the role executes the ``user`` field, the preset value will
+get added before querying the remote schema.
+
+A preset value can also reference a session variable. When the preset value has a
+session variable, then its value is resolved and then added before querying the remote schema.
+
+.. note::
+   By default, if the input value preset contains a :ref:`session variable value <dynamic_session_variables>`,
+   then its value will be resolved when the query is executed. To treat the session
+   variable value as a literal value (avoiding resolving of the session variable
+   value) can be done by specifying ``static`` as ``true`` while defining the preset.
+
+   For example:
+
+   .. code-block:: graphql
+
+      type Query {
+        hello(text: String! @preset(value: "x-hasura-hello", static: true))
+      }
+
+   In this case, ``"x-hasura-hello"`` will be the argument to the ``hello`` field
+   whenever it's queried.
+
+Remote Relationship Permissions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Permissions for remote relationships are derived from the role's remote schema permissions.
+When permissions for a given remote relationship cannot be derived from the remote schema
+permissions of a given role, that remote relationship will not be accessible to that role.
+
+Cases when the remote relationship cannot be derived are:
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+1. There are no remote schema permissions configured for the role for the remote join's remote schema.
+2. The remote join field is not accessible to the role.
+3. Any of the type (both output and input types) used in the remote join field is not accessible to the role.
+
+When a remote field's argument contains a preset and the same argument
+is used for creating a remote relationship, then the **remote presets will be
+overridden by the remote join configuration**. For example:
+
+Let's say we have a table called ``customer`` and we have a remote schema called
+``payments`` and we have a remote relationship ``customer_transactions_history`` defined
+which joins ``customer`` to ``transactions`` field of the ``payments`` field.
+
+Suppose, the ``payments`` remote schema is defined in the following way:
+
+.. code-block:: graphql
+
+   type Transaction {
+     customer_id    Int!
+     amount         Int!
+     time           String!
+     merchant       String!
+   }
+
+   type Query {
+     transactions(customer_id: String!, limit: Int): [Transaction]
+   }
+
+And, the ``customer`` table is defined in the following manner.
+
+.. code-block:: sql
+
+   CREATE TABLE customer (
+     id SERIAL PRIMARY KEY,
+     name TEXT NOT NULL
+   );
+
+The remote relationship is defined to join the ``id`` field from the
+``customer`` table to the ``customer_id`` argument of the ``transactions``
+field.
+
+We only allow the ``user`` role to access the ``amount`` and ``time`` fiels of
+the ``Transaction`` object, and introduce a preset for the ``limit`` argument
+of the ``transaction`` field, resulting in the following schema being presented.
+
+.. code-block:: graphql
+
+   type Transaction {
+     amount   Int!
+     time     String!
+   }
+
+   type Query {
+     transactions(customer_id: String!, limit: Int @preset(value: 10)): [Transaction]
+   }
+
+Two changes have been made for the ``user`` role:
+
+1. The ``merchant`` and ``customer_id`` fields are not accessible in the ``Transaction`` object.
+2. The ``limit`` argument has a preset of 10.
+
+Now, consider the following query:
+
+.. code-block:: graphql
+
+   query {
+     customer {
+       name
+       customer_transactions_history {
+         amount
+         time
+       }
+     }
+   }
+
+The ``user`` role won't be able to provide the value for the ``limit`` argument in
+the ``customer_transactions_history`` field because the ``limit`` has a preset set
+and the value will be added by the graphql-engine before it queries the remote schema.
+
+.. _metadata_add_remote_schema_permissions_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - remote_schema
+     - true
+     - :ref:`RemoteSchemaName`
+     - Name of the remote schema
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role
+   * - definition
+     - true
+     - :ref:`RemoteSchemaPermission`
+     - The remote schema permission definition
+   * - comment
+     - false
+     - text
+     - Comment
+
+.. _metadata_drop_remote_schema_permissions:
+
+drop_remote_schema_permissions
+------------------------------
+
+The ``drop_remote_schema_permissions`` API is used to drop an existing delete permission for a role on a remote schema.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "drop_remote_schema_permissions",
+       "args" : {
+           "remote_schema" : "user_messages",
+           "role" : "user"
+       }
+   }
+
+.. _metadata_drop_remote_schema_permissions_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`RemoteSchemaName`
+     - Name of the remote schema
+   * - role
+     - true
+     - :ref:`RoleName`
+     - Role

docs/graphql/core/api-reference/metadata-api/remote-schemas.rst

@@ -0,0 +1,142 @@
+.. meta::
+   :description: Manage remote schemas with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, remote schema
+
+.. _metadata_api_remote_schemas:
+
+Metadata API Reference: Remote schemas (v1.4 and above)
+=======================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Add/Remove a remote GraphQL server as remote schema in Hasura GraphQL engine.
+
+.. _metadata_add_remote_schema:
+
+add_remote_schema
+-----------------
+
+``add_remote_schema`` is used to add a remote GraphQL server as remote schema. GraphQL engine stitches it's schema with existing.
+
+An example request as follows:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "add_remote_schema",
+       "args": {
+           "name": "my remote schema",
+           "definition": {
+               "url": "https://remote-server.com/graphql",
+               "headers": [{"name": "X-Server-Request-From", "value": "Hasura"}],
+               "forward_client_headers": false,
+               "timeout_seconds": 60
+           },
+           "comment": "some optional comment"
+       }
+   }
+
+
+.. _metadata_add_remote_schema_syntax:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`RemoteSchemaName`
+     - Name of the remote schema
+   * - definition
+     - true
+     - :ref:`RemoteSchemaDef`
+     - Definition for the remote schema
+   * - comment
+     - false
+     - Text
+     - comment
+
+.. _metadata_remove_remote_schema:
+
+remove_remote_schema
+--------------------
+
+``remove_remote_schema`` is used to delete a remote schema. GraphQL engine de-stitches it's schema.
+
+An example request as follows:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "remove_remote_schema",
+       "args": {
+           "name": "my remote schema"
+       }
+   }
+
+.. _metadata_remove_remote_schema_syntax:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`RemoteSchemaName`
+     - Name of the remote schema
+
+.. _metadata_reload_remote_schema:
+
+reload_remote_schema
+--------------------
+
+``reload_remote_schema`` is used to refresh schema of the remote server. GraphQL engine refetches schema from server and stitches.
+
+An example request as follows:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "reload_remote_schema",
+       "args": {
+           "name": "my remote schema"
+       }
+   }
+
+.. _metadata_reload_remote_schema_syntax:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`RemoteSchemaName`
+     - Name of the remote schema

docs/graphql/core/api-reference/metadata-api/restified-endpoints.rst

@@ -0,0 +1,116 @@
+.. meta::
+   :description: Manage RESTified endpoints with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, RESTified endpoints
+
+.. _metadata_api_restified_endpoints:
+
+Metadata API Reference: RESTified GraphQL Endpoints (v1.4 and above)
+====================================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Add/Remove a RESTified GraphQL endpoint to Hasura GraphQL engine.
+
+.. _metadata_create_rest_endpoint:
+
+create_rest_endpoint
+--------------------
+
+``create_rest_endpoint`` is used to associate a URL template with a query.
+
+An example request as follows:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "create_rest_endpoint",
+       "args": {
+           "name": "example-name",
+           "url": "example",
+           "methods": ["POST","PUT","PATCH"],
+           "definition": {
+               "query": {
+                 "query_name": "example_mutation",
+                 "collection_name": "test_collection"
+               }
+           },
+           "comment": "some optional comment"
+       }
+   }
+
+
+.. _metadata_create_rest_endpoint_syntax:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - Text
+     - A unique identifier for the endpoint
+   * - url
+     - true
+     - :ref:`EndpointUrl`
+     - URL of the REST endpoint
+   * - methods
+     - true
+     - :ref:`EndpointMethods`
+     - Non-Empty case sensitive list of supported HTTP Methods
+   * - definition
+     - true
+     - :ref:`EndpointDef`
+     - Definition for the REST endpoint
+   * - comment
+     - false
+     - Text
+     - comment
+
+.. _metadata_drop_rest_endpoint:
+
+drop_rest_endpoint
+------------------
+
+``drop_rest_endpoint`` is used to delete an existing RESTified GraphQL Endpoint.
+
+An example request as follows:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "drop_rest_endpoint",
+       "args": {
+           "url": "my simple rest endpoint"
+       }
+   }
+
+.. _metadata_drop_rest_endpoint_syntax:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - url
+     - true
+     - :ref:`EndpointUrl`
+     - URL of the RESTified endpoint

docs/graphql/core/api-reference/metadata-api/scheduled-triggers.rst

@@ -0,0 +1,201 @@
+.. meta::
+   :description: Manage scheduled triggers with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, scheduled trigger
+
+Metadata API Reference: Scheduled Triggers (v1.4 and above)
+===========================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Scheduled triggers are used to invoke webhooks based on a timestamp or cron.
+
+.. _metadata_create_cron_trigger:
+
+create_cron_trigger
+-------------------
+
+``create_cron_trigger`` is used to create a new cron trigger.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "create_cron_trigger",
+       "args" : {
+           "name": "sample_cron",
+           "webhook": "https://httpbin.org/post",
+           "schedule":  "* * * * *",
+           "payload": {
+               "key1": "value1",
+               "key2": "value2"
+           },
+           "include_in_metadata":false,
+           "comment":"sample_cron commment"
+       }
+   }
+
+.. _metadata_create_cron_trigger_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`TriggerName <TriggerName>`
+     - Name of the cron trigger
+   * - webhook
+     - true
+     - :ref:`WebhookURL <WebhookURL>`
+     - URL of the webhook
+   * - schedule
+     - true
+     - Cron Expression
+     - Cron expression at which the trigger should be invoked.
+   * - payload
+     - false
+     - JSON
+     - Any JSON payload which will be sent when the webhook is invoked.
+   * - headers
+     - false
+     - [ :ref:`HeaderFromValue <HeaderFromValue>` | :ref:`HeaderFromEnv <HeaderFromEnv>` ]
+     - List of headers to be sent with the webhook
+   * - retry_conf
+     - false
+     - :ref:`RetryConfST`
+     - Retry configuration if scheduled invocation delivery fails
+   * - include_in_metadata
+     - true
+     - Boolean
+     - Flag to indicate whether a trigger should be included in the metadata. When a cron
+       trigger is included in the metadata, the user will be able to export it when the
+       metadata of the graphql-engine is exported.
+   * - comment
+     - false
+     - Text
+     - Custom comment.
+   * - replace
+     - false
+     - Bool
+     - When replace is set to ``true``, the cron trigger will be updated(if exists) and when it's ``false`` or the
+       field is omitted, then a new cron trigger will be created.
+
+.. _metadata_delete_cron_trigger:
+
+delete_cron_trigger
+-------------------
+
+``delete_cron_trigger`` is used to delete an existing cron trigger. The scheduled events associated with the cron trigger will also be deleted.
+
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "delete_cron_trigger",
+       "args" : {
+           "name": "sample_cron"
+       }
+   }
+
+.. _metadata_delete_cron_trigger_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`TriggerName <TriggerName>`
+     - Name of the cron trigger
+
+.. _metadata_create_scheduled_event:
+
+create_scheduled_event
+----------------------
+
+``create_scheduled_event`` is used to create a scheduled event.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "create_scheduled_event",
+       "args" : {
+           "webhook": "https://httpbin.org/post",
+           "schedule_at": "2019-09-09T22:00:00Z",
+           "payload": {
+               "key1": "value1",
+               "key2": "value2"
+           },
+           "headers" : [{
+               "name":"header-key",
+               "value":"header-value"
+           }],
+           "comment":"sample scheduled event comment"
+       }
+   }
+
+.. _metadata_create_scheduled_event_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - webhook
+     - true
+     - :ref:`WebhookURL <WebhookURL>`
+     - URL of the webhook
+   * - schedule_at
+     - true
+     - Timestamp (ISO8601 format)
+     - The time at which the invocation should be invoked.
+   * - payload
+     - false
+     - JSON
+     - Any JSON payload which will be sent when the webhook is invoked.
+   * - headers
+     - false
+     - [ :ref:`HeaderFromValue <HeaderFromValue>` | :ref:`HeaderFromEnv <HeaderFromEnv>` ]
+     - List of headers to be sent with the webhook
+   * - retry_conf
+     - false
+     - :ref:`RetryConfST`
+     - Retry configuration if scheduled event delivery fails
+   * - comment
+     - false
+     - Text
+     - Custom comment.

docs/graphql/core/api-reference/metadata-api/source.rst

@@ -0,0 +1,113 @@
+.. meta::
+   :description: Manage databases with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, database, source
+
+.. _metadata_api_sources:
+
+Metadata API Reference: Databases (v1.4 and above)
+==================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Add/remove databases in Hasura GraphQL engine.
+
+.. _pg_add_source:
+
+pg_add_source
+-------------
+
+``pg_add_source`` is used to connect a Postgres database to Hasura.
+
+Add a database with name ``pg1``:
+
+.. code-block:: http
+
+  POST /v1/metadata HTTP/1.1
+  Content-Type: application/json
+  X-Hasura-Role: admin
+
+  {
+    "type": "pg_add_source",
+    "args": {
+      "name": "pg1",
+      "configuration": {
+        "connection_info": {
+          "database_url": "<db-connection-string>",
+          "pool_settings": {
+            "max_connections": 50,
+            "idle_timeout": 180,
+            "retries": 1
+          }
+        }
+      }
+    }
+  }
+
+.. _pg_add_source_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`SourceName <SourceName>`
+     - Name of the Postgres database
+   * - configuration
+     - true
+     - :ref:`PGConfiguration <PGConfiguration>`
+     - Database connection configuration
+
+.. TODO: add pgconfiguration spec
+
+.. _pg_drop_source:
+
+pg_drop_source
+--------------
+
+``pg_drop_source`` is used to remove a Postgres database from Hasura.
+
+Remove a database with name ``pg1``:
+
+.. code-block:: http
+
+  POST /v1/metadata HTTP/1.1
+  Content-Type: application/json
+  X-Hasura-Role: admin
+
+  {
+    "type": "pg_drop_source",
+    "args": {
+      "name": "pg1"
+    }
+  }
+
+.. _pg_drop_source_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - name
+     - true
+     - :ref:`SourceName <SourceName>`
+     - Name of the Postgres database
+

docs/graphql/core/api-reference/metadata-api/table-view.rst

@@ -0,0 +1,300 @@
+.. meta::
+   :description: Manage tables and views with the Hasura metadata API
+   :keywords: hasura, docs, metadata API, API reference, table, view
+
+.. _metadata_api_tables_views:
+
+Metadata API Reference: Tables/Views (v1.4 and above)
+=====================================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Track/untrack a table/view in Hasura GraphQL engine.
+
+Only tracked tables/views are available for querying/mutating/subscribing data over the GraphQL API.
+
+.. _pg_track_table:
+
+pg_track_table
+--------------
+
+``pg_track_table`` is used to add a table/view to the GraphQL schema with configuration.
+You can customise the root field names.
+
+Add a table/view ``author``:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+      "type": "pg_track_table",
+      "args": {
+        "table": "author",
+        "source": "default",
+        "configuration": {
+           "custom_root_fields": {
+              "select": "Authors",
+              "select_by_pk": "Author",
+              "select_aggregate": "AuthorAggregate",
+              "insert": "AddAuthors",
+              "insert_one":"AddAuthor",
+              "update": "UpdateAuthors",
+              "update_by_pk": "UpdateAuthor",
+              "delete": "DeleteAuthors",
+              "delete_by_pk": "DeleteAuthor"
+           },
+           "custom_column_names": {
+              "id": "authorId"
+           }
+        }
+      }
+   }
+
+A table can be tracked with a ``custom name``. This can be useful when a table
+name is not GraphQL compliant, like ``Users Address``. A ``custom name`` like
+``users_address`` will complement the ``"Users Address"``
+table, so that it can be added to the GraphQL schema.
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+      "type": "pg_track_table",
+      "args": {
+        "table": "Author Details",
+        "configuration": {
+           "custom_name": "author_details"
+        }
+      }
+   }
+
+The GraphQL nodes and typenames
+that are generated will be according to the ``identifier``. For example, in this case,
+the nodes generated will be:
+
+- ``users_address``
+- ``users_address_one``
+- ``users_address_aggregate``
+- ``insert_users_address``
+- ``insert_users_address_one``
+- ``update_users_address``
+- ``update_users_address_by_pk``
+- ``delete_users_address``
+- ``delete_users_address_by_pk``
+
+.. note::
+
+   Hasura GraphQL engine requires the constraint names (if any) of a table to be
+   `GraphQL compliant <https://spec.graphql.org/June2018/#sec-Names>`__ in order to be able to track it.
+
+.. _pg_track_table_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName <TableName>`
+     - Name of the table
+   * - configuration
+     - false
+     - :ref:`Table Config <table_config>`
+     - Configuration for the table/view
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_untrack_table:
+
+pg_untrack_table
+----------------
+
+``untrack_table`` is used to remove a table/view from the GraphQL schema.
+
+Remove a table/view ``author``:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "pg_untrack_table",
+       "args": {
+           "table": {
+               "schema": "public",
+               "name": "author"
+            },
+           "source": "default",
+           "cascade": true
+       }
+   }
+
+.. _pg_untrack_table_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName <TableName>`
+     - Name of the table
+   * - cascade
+     - false
+     - Boolean
+     - When set to ``true``, the effect (if possible) is cascaded to any metadata dependent objects (relationships, permissions, templates)
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+
+.. _pg_set_table_is_enum:
+
+pg_set_table_is_enum
+--------------------
+
+``pg_set_table_is_enum`` sets whether an already-tracked table should be used as an :ref:`enum table <create_enum_table>`.
+
+Use table ``user_role`` as an enum table:
+
+.. code-block:: http
+
+  POST /v1/metadata HTTP/1.1
+  Content-Type: application/json
+  X-Hasura-Role: admin
+
+  {
+    "type": "pg_set_table_is_enum",
+    "args": {
+      "table": {
+        "schema": "public",
+        "name": "user_role"
+      },
+      "source": "default",
+      "is_enum": true
+    }
+  }
+
+.. _pg_set_table_is_enum_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName <TableName>`
+     - Name of the table
+   * - is_enum
+     - true
+     - Boolean
+     - Whether or not the table should be used as an :ref:`enum table <enum table>`.
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)
+
+.. _pg_set_table_customization:
+
+pg_set_table_customization
+--------------------------
+
+``pg_set_table_customization`` allows you to customize any given table with
+a custom name, custom root fields and custom column names of an already tracked
+table. This will **replace** the already present customization.
+
+:ref:`pg_set_table_custom_fields <set_table_custom_fields>` has been deprecated in
+favour of this API.
+
+Set the configuration for a table/view called ``author``:
+
+.. code-block:: http
+
+   POST /v1/metadata HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+      "type": "pg_set_table_customization",
+      "args": {
+        "table": "author_details",
+        "source": "default",
+        "configuration": {
+          "identifier": "author",
+          "custom_root_fields": {
+             "select": "Authors",
+             "select_by_pk": "Author",
+             "select_aggregate": "AuthorAggregate",
+             "insert": "AddAuthors",
+             "insert_one":"AddAuthor",
+             "update": "UpdateAuthors",
+             "update_by_pk": "UpdateAuthor",
+             "delete": "DeleteAuthors",
+             "delete_by_pk": "DeleteAuthor"
+          },
+          "custom_column_names": {
+             "id": "authorId"
+          }
+        }
+      }
+   }
+
+.. _pg_set_table_customization_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - table
+     - true
+     - :ref:`TableName <TableName>`
+     - Name of the table
+   * - configuration
+     - false
+     - :ref:`TableConfig <table_config>`
+     - Configuration for the table/view
+   * - source
+     - false
+     - :ref:`SourceName <SourceName>`
+     - Name of the source database of the table (default: ``default``)

docs/graphql/core/api-reference/schema-api/index.rst

@@ -47,9 +47,9 @@ Request body
 
 .. parsed-literal::
 
-   Query_
+   :ref:`Query <schema_query>`
 
-.. _Query_:
+.. _schema_query:
 
 Query
 *****
@@ -88,12 +88,12 @@ The various types of queries are listed in the following table:
      - Synopsis
 
    * - **bulk**
-     - :ref:`Query <Query>` array
+     - :ref:`Query <schema_query>` array
      - 1
      - Execute multiple operations in a single query
 
-   * - :ref:`run_sql`
+   * - :ref:`schema_run_sql`
-     - :ref:`run_sql_args <run_sql_syntax>`
+     - :ref:`run_sql_args <schema_run_sql_syntax>`
      - 1
      - Run SQL directly on Postgres
 
@@ -155,4 +155,10 @@ to explicitly state that this API is not enabled i.e. remove it from the list of
    --enabled-apis="graphql"
    HASURA_GRAPHQL_ENABLED_APIS="graphql"
 
-See :ref:`server_flag_reference` for info on setting the above flag/env var.
+See :ref:`server_flag_reference` for info on setting the above flag/env var.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Run SQL <run-sql>

docs/graphql/core/api-reference/schema-api/run-sql.rst

@@ -0,0 +1,319 @@
+.. meta::
+   :description: Execute SQL with the Hasura schema/metadata API
+   :keywords: hasura, docs, schema/metadata API, API reference, run_sql
+
+.. _schema_api_run_sql:
+
+Schema API Reference: Run SQL
+=============================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+.. _schema_run_sql:
+
+run_sql
+-------
+
+``run_sql`` can be used to run arbitrary SQL statements.
+
+Multiple SQL statements can be separated by a ``;``, however, only the result of the last SQL statement will be
+returned.
+
+.. admonition:: Admin-only
+
+  This is an admin-only request, i.e. the request can only be executed with ``X-Hasura-Role: admin``. This can be set by passing
+  ``X-Hasura-Admin-Secret`` or by setting the right role in webhook/JWT
+  authorization mode.
+
+  This is deliberate as it is hard to enforce any sort of permissions on arbitrary SQL. If
+  you find yourself in the need of using ``run_sql`` to run custom DML requests,
+  consider creating a view. You can now define permissions on that particular view
+  for various roles.
+
+Use cases
+^^^^^^^^^
+
+1. To execute DDL operations that are not supported by the console (e.g. managing indexes).
+2. Run custom DML requests from backend microservices instead of installing libraries to speak to Postgres.
+
+An example:
+
+.. code-block:: http
+
+   POST /v2/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "run_sql",
+       "args": {
+           "source": "default",
+           "sql": "CREATE UNIQUE INDEX ON films (title);"
+       }
+   }
+
+While ``run_sql`` lets you run any SQL, it tries to ensure that the Hasura GraphQL engine's
+state (relationships, permissions etc.) is consistent i.e. you
+cannot drop a column on which any metadata is dependent on (say a permission or
+a relationship). The effects, however, can be cascaded.
+
+Example: If we were to drop the 'bio' column from the author table (let's say
+the column is used in some permission), you would see an error.
+
+.. code-block:: http
+
+   POST /v2/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "run_sql",
+       "args": {
+           "source": "default",
+           "sql": "ALTER TABLE author DROP COLUMN name"
+       }
+   }
+
+.. code-block:: http
+
+   HTTP/1.1 400 BAD REQUEST
+   Content-Type: application/json
+
+   {
+       "path": "$.args",
+       "error": "cannot drop due to the following dependent objects : permission author.user.select"
+   }
+
+We can however, cascade these changes.
+
+.. code-block:: http
+   :emphasize-lines: 9
+
+   POST /v2/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "run_sql",
+       "args": {
+           "source": "default",
+           "sql": "ALTER TABLE author DROP COLUMN bio",
+           "cascade" : true
+       }
+   }
+
+.. code-block:: http
+
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+
+   {
+       "result_type": "CommandOk"
+   }
+
+With the above request, the dependent permission is also dropped.
+
+Example: If we were to drop a foreign key constraint from the article table
+(let's say the column involved in the foreign key is used to define a relationship),
+you would see an error.
+
+.. code-block:: http
+
+   POST /v2/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "run_sql",
+       "args": {
+           "source": "default",
+           "sql": "ALTER TABLE article DROP CONSTRAINT article_author_id_fkey"
+       }
+   }
+
+.. code-block:: http
+
+   HTTP/1.1 400 BAD REQUEST
+   Content-Type: application/json
+
+   {
+       "path": "$.args",
+       "error": "cannot drop due to the following dependent objects : constraint article.article_author_id_fkey"
+   }
+
+We can however, cascade these changes.
+
+.. code-block:: http
+   :emphasize-lines: 9
+
+   POST /v2/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "run_sql",
+       "args": {
+           "source": "default",
+           "sql": "ALTER TABLE article DROP CONSTRAINT article_author_id_fkey",
+           "cascade" : true
+       }
+   }
+
+.. code-block:: http
+
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+
+   {
+       "result_type": "CommandOk"
+   }
+
+With the above request, the dependent permission is also dropped.
+
+In general, the SQL operations that will affect Hasura metadata are:
+
+1. Dropping columns
+2. Dropping tables
+3. Dropping foreign keys
+4. Altering types of columns
+5. Dropping SQL functions
+6. Overloading SQL functions
+
+In case of 1, 2 and 3 the dependent objects (if any) can be dropped using ``cascade``.
+However, when altering type of columns, if any objects are affected, the change
+cannot be cascaded. So, those dependent objects have to be manually dropped before
+executing the SQL statement. Dropping SQL functions will cascade the functions in
+metadata even without using ``cascade`` since no other objects depend on them.
+Overloading tracked SQL functions is not allowed.
+
+Set ``check_metadata_consistency`` field to ``false`` to force the server to not consider metadata dependencies.
+
+.. _schema_run_sql_syntax:
+
+Args syntax
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - sql
+     - true
+     - String
+     - The sql to be executed
+   * - source
+     - false
+     - String
+     - The database on which the sql is to be executed (default: 'default' database)
+   * - cascade
+     - false
+     - Boolean
+     - When set to ``true``, the effect (if possible) is cascaded to any hasuradb dependent objects (relationships, permissions, templates).
+   * - check_metadata_consistency
+     - false
+     - Boolean
+     - When set to ``false``, the sql is executed without checking metadata dependencies.
+   * - read_only
+     - false
+     - Boolean
+     - When set to ``true``, the request will be run in ``READ ONLY`` transaction access mode which means only ``select`` queries will be successful. This flag ensures that the GraphQL schema is not modified and is hence highly performant.
+
+Response
+^^^^^^^^
+
+The response is a JSON Object with the following structure.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Always present
+     - Schema
+     - Description
+   * - result_type
+     - true
+     - String
+     - One of "CommandOk" or "TuplesOk"
+   * - result
+     - false
+     - ``[[Text]]`` (An array of rows, each row an array of columns)
+     - This is present only when the ``result_type`` is "TuplesOk"
+
+.. note::
+   The first row in the ``result`` (when present) will be the names of the columns.
+
+Some examples
+^^^^^^^^^^^^^
+
+An SQL query returning results.
+
+.. code-block:: http
+
+   POST /v2/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type": "run_sql",
+       "args": {
+           "source": "default",
+           "sql": "select user_id, first_name from author limit 2;"
+       }
+   }
+
+.. code-block:: http
+
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+
+   {
+       "result_type": "TuplesOk",
+       "result": [
+           [
+               "user_id",
+               "first_name"
+           ],
+           [
+               "1",
+               "andre"
+           ],
+           [
+               "2",
+               "angela"
+           ]
+       ]
+   }
+
+
+An SQL query to create a table:
+
+.. code-block:: http
+
+   POST /v2/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+     "type":"run_sql",
+     "args": {
+       "source": "default",
+       "sql": "create table item ( id serial,  name text,  category text,  primary key (id))",
+       "check_metadata_consistency": false
+     }
+   }
+
+.. code-block:: http
+
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+
+   {
+     "result_type": "CommandOk",
+     "result": null
+   }

docs/graphql/core/api-reference/schema-metadata-api/actions.rst

@@ -75,85 +75,13 @@ Args syntax
      - Name of the action
    * - definition
      - true
-     - ActionDefinition_
+     - :ref:`ActionDefinition`
      - Definition of the action
    * - comment
      - false
      - text
      - comment
 
-.. _ActionDefinition:
-
-ActionDefinition
-&&&&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - arguments
-     - false
-     - Array of InputArgument_
-     - Input arguments
-   * - output_type
-     - true
-     - :ref:`GraphQLType <GraphQLType>`
-     - The output type of the action. Only object and list of objects are allowed.
-   * - kind
-     - false
-     - [ ``synchronous`` | ``asynchronous`` ]
-     - The kind of the mutation action (default: ``synchronous``). If the type of
-       the action is ``query`` then the ``kind`` field should be omitted.
-   * - headers
-     - false
-     - [ :ref:`HeaderFromValue <HeaderFromValue>` | :ref:`HeaderFromEnv <HeaderFromEnv>` ]
-     - List of defined headers to be sent to the handler
-   * - forward_client_headers
-     - false
-     - boolean
-     - If set to ``true`` the client headers are forwarded to the webhook handler (default: ``false``)
-   * - handler
-     - true
-     - :ref:`WebhookURL <WebhookURL>`
-     - The action's webhook URL
-   * - type
-     - false
-     - [ ``mutation`` | ``query`` ]
-     - The type of the action (default: ``mutation``)
-   * - timeout
-     - false
-     - Integer
-     - Number of seconds to wait for response before timing out. Default: 30
-
-
-.. _InputArgument:
-
-InputArgument
-&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - name
-     - true
-     - text
-     - Name of the argument
-   * - type
-     - true
-     - :ref:`GraphQLType <GraphQLType>`
-     - Type of the argument
-
-.. note::
-
-   The ``GraphQL Types`` used in creating an action must be defined before via :ref:`Custom Types <api_custom_types>`
-
 .. _drop_action:
 
 drop_action
@@ -255,7 +183,7 @@ Args syntax
      - Name of the action
    * - definition
      - true
-     - ActionDefinition_
+     - :ref:`ActionDefinition`
      - Definition of the action to be replaced
 
 .. _create_action_permission:

docs/graphql/core/api-reference/schema-metadata-api/computed-field.rst

@@ -80,41 +80,13 @@ Args syntax
      - Name of the new computed field
    * - definition
      - true
-     - ComputedFieldDefinition_
+     - :ref:`ComputedFieldDefinition`
      - The computed field definition
    * - comment
      - false
      - text
      - comment
 
-.. _ComputedFieldDefinition:
-
-ComputedFieldDefinition
-&&&&&&&&&&&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - function
-     - true
-     - :ref:`FunctionName <FunctionName>`
-     - The SQL function
-   * - table_argument
-     - false
-     - String
-     - Name of the argument which accepts a table row type. If omitted, the first
-       argument is considered a table argument
-   * - session_argument
-     - false
-     - String
-     - Name of the argument which accepts the Hasura session object as
-       a JSON/JSONB value. If omitted, the Hasura session object is
-       not passed to the function
-
 .. _drop_computed_field:
 
 drop_computed_field

docs/graphql/core/api-reference/schema-metadata-api/custom-functions.rst

@@ -25,7 +25,7 @@ track_function
 --------------
 
 ``track_function`` is used to add a custom SQL function to the ``query`` root field of the GraphQL schema.
-Also refer a note :ref:`here <note>`.
+Also refer a note :ref:`here <function_req_note>`.
 
 Add an SQL function ``search_articles``:
 
@@ -51,7 +51,7 @@ track_function v2
 Version 2 of ``track_function`` is used to add a custom SQL function to the GraphQL schema.
 It supports more configuration options than v1, and also supports tracking
 functions as mutations.
-Also refer a note :ref:`here <note>`.
+Also refer a note :ref:`here <function_req_note>`.
 
 Track an SQL function called ``search_articles`` with a Hasura session argument:
 
@@ -138,38 +138,6 @@ Args syntax
      - :ref:`Function Configuration <function_configuration>`
      - Configuration for the SQL function
 
-.. _function_configuration:
-
-Function Configuration
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - session_argument
-     - false
-     - `String`
-     - Function argument which accepts session info JSON
-   * - exposed_as
-     - false
-     - `String`
-     - In which part of the schema should we expose this function? Either "mutation" or "query".
-
-.. _note:
-
-.. note::
-
-   Currently, only functions which satisfy the following constraints can be exposed over the GraphQL API
-   (*terminology from* `Postgres docs <https://www.postgresql.org/docs/current/sql-createfunction.html>`__):
-
-   - **Function behaviour**: ``STABLE`` or ``IMMUTABLE`` functions may *only* be exposed as queries (i.e. with ``exposed_as: query``)
-   - **Return type**: MUST be ``SETOF <table-name>`` OR ``<table_name>`` where ``<table-name>`` is already tracked
-   - **Argument modes**: ONLY ``IN``
-
 .. _untrack_function:
 
 untrack_function

docs/graphql/core/api-reference/schema-metadata-api/custom-types.rst

@@ -90,230 +90,17 @@ Args syntax
      - Description
    * - input_objects
      - false
-     - Array of InputObjectType_
+     - Array of :ref:`InputObjectType`
      - Set of GraphQL ``Input Object``
    * - objects
      - false
-     - Array of ObjectType_
+     - Array of :ref:`ObjectType`
      - Set of GraphQL ``Object``
    * - scalars
      - false
-     - Array of ScalarType_
+     - Array of :ref:`ScalarType`
      - Set of GraphQL ``Scalar``
    * - enums
      - false
-     - Array of EnumType_
+     - Array of :ref:`EnumType`
-     - Set of GraphQL ``Enum``
+     - Set of GraphQL ``Enum``
-
-.. _InputObjectType:
-
-InputObjectType
-&&&&&&&&&&&&&&&
-
-A simple JSON object to define `GraphQL Input Object <https://spec.graphql.org/June2018/#sec-Input-Objects>`__
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - name
-     - true
-     - :ref:`GraphQLName`
-     - Name of the Input object type
-   * - description
-     - false
-     - String
-     - Description of the Input object type
-   * - fields
-     - true
-     - Array of InputObjectField_
-     - Fields of the Input object type
-
-.. _InputObjectField:
-
-InputObjectField
-****************
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - name
-     - true
-     - :ref:`GraphQLName`
-     - Name of the Input object field
-   * - description
-     - false
-     - String
-     - Description of the Input object field
-   * - type
-     - true
-     - :ref:`GraphQLType <GraphQLType>`
-     - GraphQL ype of the input object field
-
-
-.. _ObjectType:
-
-ObjectType
-&&&&&&&&&&
-
-A simple JSON object to define `GraphQL Object <https://spec.graphql.org/June2018/#sec-Objects>`__
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - name
-     - true
-     - :ref:`GraphQLName`
-     - Name of the Object type
-   * - description
-     - false
-     - String
-     - Description of the Object type
-   * - fields
-     - true
-     - Array of ObjectField_
-     - Fields of the Object type
-   * - relationships
-     - false
-     - Array of ObjectRelationship_
-     - Relationships of the Object type to tables
-
-.. _ObjectField:
-
-ObjectField
-***********
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - name
-     - true
-     - :ref:`GraphQLName`
-     - Name of the Input object field
-   * - description
-     - false
-     - String
-     - Description of the Input object field
-   * - type
-     - true
-     - :ref:`GraphQLType <GraphQLType>`
-     - GraphQL type of the input object field
-
-.. _ObjectRelationship:
-
-ObjectRelationship
-******************
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - name
-     - true
-     - :ref:`RelationshipName`
-     - Name of the relationship, shouldn't conflict with existing field names
-   * - type
-     - true
-     - [ ``object`` | ``array`` ]
-     - Type of the relationship
-   * - remote_table
-     - true
-     - :ref:`TableName`
-     - The table to which relationship is defined
-   * - field_mapping
-     - true
-     - Object (ObjectField_ name : Remote table's :ref:`PGColumn`)
-     - Mapping of fields of object type to columns of remote table
-
-.. _ScalarType:
-
-ScalarType
-&&&&&&&&&&
-
-A simple JSON object to define `GraphQL Scalar <https://spec.graphql.org/June2018/#sec-Scalars>`__
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - name
-     - true
-     - :ref:`GraphQLName`
-     - Name of the Scalar type
-   * - description
-     - false
-     - String
-     - Description of the Scalar type
-
-.. _EnumType:
-
-EnumType
-&&&&&&&&
-
-A simple JSON object to define `GraphQL Enum <https://spec.graphql.org/June2018/#sec-Enums>`__
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - name
-     - true
-     - :ref:`GraphQLName`
-     - Name of the Enum type
-   * - description
-     - false
-     - String
-     - Description of the Enum type
-   * - values
-     - true
-     - Array of EnumValue_
-     - Values of the Enum type
-
-.. _EnumValue:
-
-EnumValue
-*********
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - value
-     - true
-     - :ref:`GraphQLName`
-     - Value of the Enum type
-   * - description
-     - false
-     - String
-     - Description of the value
-   * - is_deprecated
-     - false
-     - Boolean
-     - If set to ``true``, the enum value is marked as deprecated

docs/graphql/core/api-reference/schema-metadata-api/event-triggers.rst

@@ -94,15 +94,15 @@ Args syntax
      - Environment variable name of webhook (must exist at boot time) (*)
    * - insert
      - false
-     - OperationSpec_
+     - :ref:`OperationSpec`
      - Specification for insert operation
    * - update
      - false
-     - OperationSpec_
+     - :ref:`OperationSpec`
      - Specification for update operation
    * - delete
      - false
-     - OperationSpec_
+     - :ref:`OperationSpec`
      - Specification for delete operation
    * - headers
      - false
@@ -110,7 +110,7 @@ Args syntax
      - List of headers to be sent with the webhook
    * - retry_conf
      - false
-     - RetryConf_
+     - :ref:`RetryConf`
      - Retry configuration if event delivery fails
    * - replace
      - false
@@ -241,69 +241,4 @@ Args syntax
    * - payload
      - true
      - JSON
-     - Some JSON payload to send to trigger
+     - Some JSON payload to send to trigger
-
-.. _TriggerName:
-
-TriggerName
-&&&&&&&&&&&
-
-.. parsed-literal::
-
-  String
-
-.. _OperationSpec:
-
-OperationSpec
-&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - columns
-     - true
-     - EventTriggerColumns_
-     - List of columns or "*" to listen to changes
-   * - payload
-     - false
-     - EventTriggerColumns_
-     - List of columns or "*" to send as part of webhook payload
-
-.. _EventTriggerColumns:
-
-EventTriggerColumns
-&&&&&&&&&&&&&&&&&&&
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   "*" | [:ref:`PGColumn`]
-
-.. _RetryConf:
-
-RetryConf
-&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - required
-     - Schema
-     - Description
-   * - num_retries
-     - false
-     - Integer
-     - Number of times to retry delivery. Default: 0
-   * - interval_sec
-     - false
-     - Integer
-     - Number of seconds to wait between each retry. Default: 10
-   * - timeout_sec
-     - false
-     - Integer
-     - Number of seconds to wait for response before timing out. Default: 60

docs/graphql/core/api-reference/schema-metadata-api/index.rst

@@ -44,9 +44,9 @@ Request body
 
 .. parsed-literal::
 
-   Query_
+   :ref:`Query <api_query>`
 
-.. _Query:
+.. _api_query:
 
 Query
 *****
@@ -85,7 +85,7 @@ The various types of queries are listed in the following table:
      - Synopsis
 
    * - **bulk**
-     - :ref:`Query <Query>` array
+     - :ref:`Query <api_query>` array
      - 1
      - Execute multiple operations in a single query
 
@@ -119,6 +119,11 @@ The various types of queries are listed in the following table:
      - 1
      - Remove a table/view
 
+   * - :ref:`set_table_is_enum`
+     - :ref:`set_table_is_enum_args <set_table_is_enum_syntax>`
+     - 1
+     - Set a tracked table as an enum table
+
    * - :ref:`track_function`
      - :ref:`FunctionName <FunctionName>`
      - 1
@@ -289,14 +294,13 @@ The various types of queries are listed in the following table:
      - 1
      - Delete an existing remote relationship
 
-
    * - :ref:`export_metadata`
      - :ref:`Empty Object`
      - 1
      - Export the current metadata
 
-   * - :ref:`replace_metadata_v1`
+   * - :ref:`replace_metadata`
-     - :ref:`replace_metadata_args <replace_metadata_syntax_v1>`
+     - :ref:`replace_metadata_args <replace_metadata_syntax>`
      - 1
      - Import and replace existing metadata
 
@@ -495,4 +499,3 @@ See :ref:`server_flag_reference` for info on setting the above flag/env var.
   Custom Types <custom-types>
   Actions <actions>
   Manage Metadata <manage-metadata>
-  Common syntax definitions <syntax-defs>

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

@@ -62,7 +62,7 @@ metadata will be replaced with the new one.
         "args": <replace-metadata-args>
     }
 
-.. _replace_metadata_syntax_v1:
+.. _replace_metadata_syntax:
 
 Args syntax
 ^^^^^^^^^^^

docs/graphql/core/api-reference/schema-metadata-api/permission.rst

@@ -128,44 +128,13 @@ Args syntax
      - Role
    * - permission
      - true
-     - InsertPermission_
+     - :ref:`InsertPermission`
      - The permission definition
    * - comment
      - false
      - text
      - Comment
 
-.. _InsertPermission:
-
-InsertPermission
-&&&&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - check
-     - true
-     - :ref:`BoolExp`
-     - This expression has to hold true for every new row that is inserted
-   * - set
-     - false
-     - :ref:`ColumnPresetExp`
-     - Preset values for columns that can be sourced from session variables or static values
-   * - columns
-     - false
-     - :ref:`PGColumn` array (or) ``'*'``
-     - Can insert into only these columns (or all when ``'*'`` is specified)
-   * - backend_only
-     - false
-     - Boolean
-     - When set to ``true`` the mutation is accessible only if ``x-hasura-use-backend-only-permissions``
-       session variable exists and is set to ``true`` and request is made with ``x-hasura-admin-secret``
-       set if any auth is configured
-
 .. _drop_insert_permission:
 
 drop_insert_permission
@@ -278,46 +247,13 @@ Args syntax
      - Role
    * - permission
      - true
-     - SelectPermission_
+     - :ref:`SelectPermission`
      - The permission definition
    * - comment
      - false
      - text
      - Comment
 
-.. _SelectPermission:
-
-SelectPermission
-&&&&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - columns
-     - true
-     - :ref:`PGColumn` array (or) ``'*'``
-     - Only these columns are selectable (or all when ``'*'`` is specified)
-   * - computed_fields
-     - false
-     - :ref:`ComputedFieldName` array
-     - Only these computed fields are selectable
-   * - filter
-     - true
-     - :ref:`BoolExp`
-     - Only the rows where this expression holds true are selectable
-   * - limit
-     - false
-     - ``Integer``
-     - The maximum number of rows that can be returned
-   * - allow_aggregations
-     - false
-     - ``Boolean``
-     - Toggle allowing aggregate queries
-
 .. _drop_select_permission:
 
 drop_select_permission
@@ -440,43 +376,13 @@ Args syntax
      - Role
    * - permission
      - true
-     - UpdatePermission_
+     - :ref:`UpdatePermission`
      - The permission definition
    * - comment
      - false
      - text
      - Comment
 
-.. _UpdatePermission:
-
-UpdatePermission
-&&&&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - columns
-     - true
-     - :ref:`PGColumn` array (or) ``'*'``
-     - Only these columns are selectable (or all when ``'*'`` is specified)
-   * - filter
-     - true
-     - :ref:`BoolExp`
-     - Only the rows where this precondition holds true are updatable
-   * - check
-     - false
-     - :ref:`BoolExp`
-     - Postcondition which must be satisfied by rows which have been updated
-   * - set
-     - false
-     - :ref:`ColumnPresetExp`
-     - Preset values for columns that can be sourced from session variables or static values.
-
-
 .. _drop_update_permission:
 
 drop_update_permission
@@ -576,30 +482,13 @@ Args syntax
      - Role
    * - permission
      - true
-     - DeletePermission_
+     - :ref:`DeletePermission`
      - The permission definition
    * - comment
      - false
      - text
      - Comment
 
-.. _DeletePermission:
-
-DeletePermission
-&&&&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - filter
-     - true
-     - :ref:`BoolExp`
-     - Only the rows where this expression holds true are deletable
-
 .. _drop_delete_permission:
 
 drop_delete_permission

docs/graphql/core/api-reference/schema-metadata-api/query-collections.rst

@@ -205,7 +205,7 @@ Args Syntax
 .. _add_collection_to_allowlist:
 
 add_collection_to_allowlist
-----------------------------
+---------------------------
 
 ``add_collection_to_allowlist`` is used to add a collection to the allow-list.
 
@@ -242,7 +242,7 @@ Args Syntax
 .. _drop_collection_from_allowlist:
 
 drop_collection_from_allowlist
--------------------------------
+------------------------------
 
 ``drop_collection_from_allowlist`` is used to remove a collection from the allow-list.
 

docs/graphql/core/api-reference/schema-metadata-api/relationship.rst

@@ -133,59 +133,13 @@ Args syntax
      - Name of the new relationship
    * - using
      - true
-     - ObjRelUsing_
+     - :ref:`ObjRelUsing`
      - Use one of the available ways to define an object relationship
    * - comment
      - false
      - text
      - comment
 
-.. _ObjRelUsing:
-
-ObjRelUsing
-&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - foreign_key_constraint_on
-     - false
-     - :ref:`PGColumn <PGColumn>`
-     - The column with foreign key constraint
-   * - manual_configuration
-     - false
-     - ObjRelUsingManualMapping_
-     - Manual mapping of table and columns
-
-.. note::
-
-   There has to be at least one and only one of ``foreign_key_constraint_on``
-   and ``manual_configuration``. 
-
-
-ObjRelUsingManualMapping
-&&&&&&&&&&&&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - remote_table
-     - true
-     - :ref:`TableName`
-     - The table to which the relationship has to be established
-   * - column_mapping
-     - true
-     - Object (:ref:`PGColumn` : :ref:`PGColumn`)
-     - Mapping of columns from current table to remote table
-
 .. _create_array_relationship:
 
 create_array_relationship
@@ -290,72 +244,13 @@ Args syntax
      - Name of the new relationship
    * - using
      - true
-     - ArrRelUsing_
+     - :ref:`ArrRelUsing`
      - Use one of the available ways to define an array relationship
    * - comment
      - false
      - text
      - comment
 
-.. _ArrRelUsing:
-
-ArrRelUsing
-&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - foreign_key_constraint_on
-     - false
-     - ArrRelUsingFKeyOn_
-     - The column with foreign key constraint
-   * - manual_configuration
-     - false
-     - ArrRelUsingManualMapping_
-     - Manual mapping of table and columns
-
-ArrRelUsingFKeyOn
-&&&&&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - table
-     - true
-     - :ref:`TableName`
-     - Name of the table
-   * - column
-     - true
-     - :ref:`PGColumn`
-     - Name of the column with foreign key constraint
-
-ArrRelUsingManualMapping
-&&&&&&&&&&&&&&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - remote_table
-     - true
-     - :ref:`TableName`
-     - The table to which the relationship has to be established
-   * - column_mapping
-     - true
-     - Object (:ref:`PGColumn` : :ref:`PGColumn`)
-     - Mapping of columns from current table to remote table
-
 .. _drop_relationship:
 
 drop_relationship

docs/graphql/core/api-reference/schema-metadata-api/remote-relationships.rst

@@ -59,7 +59,7 @@ Args syntax
      - Description
    * - name
      - true
-     - RemoteRelationshipName_
+     - :ref:`RemoteRelationshipName`
      - Name of the remote relationship
    * - table
      - true
@@ -75,7 +75,7 @@ Args syntax
      - Name of the remote schema to join with
    * - remote_field
      - true
-     - RemoteField_
+     - :ref:`RemoteField`
      - The schema tree ending at the field in remote schema which needs to be joined with.
 
 .. _update_remote_relationship:
@@ -125,7 +125,7 @@ Args syntax
      - Description
    * - name
      - true
-     - RemoteRelationshipName_
+     - :ref:`RemoteRelationshipName`
      - Name of the remote relationship
    * - table
      - true
@@ -141,7 +141,7 @@ Args syntax
      - Name of the remote schema to join with
    * - remote_field
      - true
-     - RemoteField_
+     - :ref:`RemoteField`
      - The schema tree ending at the field in remote schema which needs to be joined with.
 
 .. _delete_remote_relationship:
@@ -186,80 +186,5 @@ Args syntax
      - Object with table name and schema
    * - name
      - true
-     - RemoteRelationshipName_
+     - :ref:`RemoteRelationshipName`
-     - Name of the remote relationship
+     - Name of the remote relationship
-
-.. _RemoteRelationshipName:
-
-RemoteRelationshipName
-&&&&&&&&&&&&&&&&&&&&&&
-
-.. parsed-literal::
-
-  String
-
-
-RemoteField
-&&&&&&&&&&&
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-      FieldName: {
-        "arguments": InputArguments
-        "field": RemoteField  # optional
-      }
-   }
-
-
-``RemoteField`` is a recursive tree structure that points to the field in the remote schema that needs to be joined with. It is recursive because the remote field maybe nested deeply in the remote schema.
-
-Examples:
-
-.. code-block:: http
-
-   POST /v1/query HTTP/1.1
-   Content-Type: application/json
-   X-Hasura-Role: admin
-
-   {
-      "message": {
-         "arguments":{
-            "message_id":"$id"
-          }
-      }
-   }
-
-.. code-block:: http
-
-   POST /v1/query HTTP/1.1
-   Content-Type: application/json
-   X-Hasura-Role: admin
-
-   {
-      "messages": {
-         "arguments": {
-            "limit": 100
-         },
-         "field": {
-           "private": {
-             "arguments": {
-                "id" : "$id"
-             }
-           }
-         }
-      }
-   }
-
-InputArguments
-&&&&&&&&&&&&&&
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-     InputField : $PGColumn | Scalar
-   }
-
-Table columns can be referred by prefixing ``$`` e.g ``$id``.

docs/graphql/core/api-reference/schema-metadata-api/remote-schema-permissions.rst

@@ -334,35 +334,20 @@ Args syntax
      - Role
    * - definition
      - true
-     - RemoteSchemaPermission_
+     - :ref:`RemoteSchemaPermission`
      - The remote schema permission definition
    * - comment
      - false
      - text
      - Comment
 
-.. _RemoteSchemaPermission:
-
-RemoteSchemaPermission
-""""""""""""""""""""""
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - schema
-     - true
-     - GraphQL SDL
-     - GraphQL SDL defining the role based schema
-
 .. note::
+
    ``add_remote_schema_permissions`` will only work when the graphql-engine has enabled remote
    schema permissions. Remote schema permissions can be enabled by running the graphql-engine
    with the ``--enable-remote-schema-permissions`` server flag or by setting the   ``HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS`` environment variable.
 
+
 .. _drop_remote_schema_permissions:
 
 drop_remote_schema_permissions

docs/graphql/core/api-reference/schema-metadata-api/scheduled-triggers.rst

@@ -77,7 +77,7 @@ Args syntax
      - List of headers to be sent with the webhook
    * - retry_conf
      - false
-     - RetryConfST_
+     - :ref:`RetryConfST`
      - Retry configuration if scheduled invocation delivery fails
    * - include_in_metadata
      - true
@@ -193,53 +193,9 @@ Args syntax
      - List of headers to be sent with the webhook
    * - retry_conf
      - false
-     - RetryConfST_
+     - :ref:`RetryConfST`
      - Retry configuration if scheduled event delivery fails
    * - comment
      - false
      - Text
-     - Custom comment.
+     - Custom comment.
-
-UrlFromEnv
-&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - required
-     - Schema
-     - Description
-   * - from_env
-     - true
-     - String
-     - Name of the environment variable which has the URL
-
-.. _RetryConfST:
-
-RetryConfST
-&&&&&&&&&&&
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - required
-     - Schema
-     - Description
-   * - num_retries
-     - false
-     - Integer
-     - Number of times to retry delivery. Default: 0
-   * - retry_interval_seconds
-     - false
-     - Integer
-     - Number of seconds to wait between each retry. Default: 10
-   * - timeout_seconds
-     - false
-     - Integer
-     - Number of seconds to wait for response before timing out. Default: 60
-   * - tolerance_seconds
-     - false
-     - Integer
-     - Number of seconds between scheduled time and actual delivery time that is acceptable. If the time difference is more than this, then the event is dropped. Default: 21600 (6 hours)

docs/graphql/core/api-reference/schema-metadata-api/syntax-defs.rst

@@ -1,699 +0,0 @@
-.. meta::
-   :description: Common syntax definitions for the Hasura schema/metadata API
-   :keywords: hasura, docs, schema/metadata API, API reference, syntax definitions
-
-.. _api_metadata_syntax_defs:
-
-Schema/Metadata API Reference: Common syntax definitions
-========================================================
-
-.. contents:: Table of contents
-  :backlinks: none
-  :depth: 1
-  :local:
-
-
-.. _TableName:
-
-TableName
-^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   String | QualifiedTable_
-
-.. _QualifiedTable:
-
-QualifiedTable
-^^^^^^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-       "name": String,
-       "schema": String
-   }
-
-.. _FunctionName:
-
-FunctionName
-^^^^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   String | QualifiedFunction_
-
-QualifiedFunction
-^^^^^^^^^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-       "name": String,
-       "schema": String
-   }
-
-.. _RoleName:
-
-RoleName
-^^^^^^^^
-
-.. parsed-literal::
-
-  String
-
-.. _ComputedFieldName:
-
-ComputedFieldName
-^^^^^^^^^^^^^^^^^^
-
-.. parsed-literal::
-
-  String
-
-.. _PGColumnType:
-
-PGColumnType
-^^^^^^^^^^^^
-
-.. parsed-literal::
-
-  String
-
-1. Numeric types
-
-   .. list-table::
-      :widths: 12 10 20
-      :header-rows: 1
-
-      * - Type
-        - Alias
-        - Description
-
-      * - ``serial``
-        -
-        - autoincrementing integer
-
-      * - ``bigserial``
-        -
-        - autoincrementing bigint
-
-      * - ``integer``
-        -
-        - 4 bytes, typical choice for integer
-
-      * - ``smallint``
-        -
-        - 2 bytes
-
-      * - ``bigint``
-        -
-        - 8 bytes
-
-      * - ``real``
-        - ``float4``
-        - 6 decimal digits precision, inexact
-
-      * - ``double precision``
-        - ``float8``
-        - 15 decimal digits precision, inexact
-
-      * - ``numeric``
-        - ``decimal``
-        - arbitrary precision, exact
-
-2. Character types
-
-   .. list-table::
-      :widths: 8 6 20
-      :header-rows: 1
-
-      * - Type
-        - Alias
-        - Description
-
-      * - ``varchar``
-        - ``text``
-        - typical choice for storing string types
-
-3. Date/Time types
-
-   .. list-table::
-      :widths: 8 6 20
-      :header-rows: 1
-
-      * - Type
-        - Alias
-        - Description
-
-      * - ``timestamp with time zone``
-        - ``timestamptz``
-        - both date and time, with time zone. Allowed values should be of ISO8601 format. E.g. 2016-07-20T17:30:15Z, 2016-07-20T17:30:15+05:30, 2016-07-20T17:30:15.234890+05:30
-
-      * - ``time with time zone``
-        - ``timetz``
-        - time of day only, with time zone. Allowed values should be of ISO8601 format. E.g. 17:30:15Z, 17:30:15+05:30, 17:30:15.234890+05:30
-
-      * - ``date``
-        -
-        - date (no time of day). Allowed values are yyyy-mm-dd
-
-4. Boolean type
-
-   .. list-table::
-      :widths: 8 6 20
-      :header-rows: 1
-
-      * - Type
-        - Alias
-        - Description
-
-      * - ``boolean``
-        -
-        - state of true or false
-
-5. JSON types
-
-   .. list-table::
-      :widths: 8 6 20
-      :header-rows: 1
-
-      * - Type
-        - Alias
-        - Description
-
-      * - ``json``
-        -
-        - Stored as plain text
-
-      * - ``jsonb``
-        -
-        - Stored in a binary format and can be indexed
-
-.. _PGColumn:
-
-PGColumn
-^^^^^^^^
-
-.. parsed-literal::
-
-  String
-
-.. _RelationshipName:
-
-RelationshipName
-^^^^^^^^^^^^^^^^
-
-.. parsed-literal::
-
-  String
-
-.. _BoolExp:
-
-BoolExp
-^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   AndExp_ | OrExp_ | NotExp_ | ExistsExp_ | TrueExp_ | ColumnExp_
-
-AndExp
-^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-       "$and" : [BoolExp_],
-   }
-
-OrExp
-^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-       "$or"  : [BoolExp_],
-   }
-
-NotExp
-^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-       "$not" : BoolExp_
-   }
-
-ExistsExp
-^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-       "$exists" : {
-            "_table": TableName_,
-            "_where": BoolExp_
-       }
-   }
-
-TrueExp
-^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-    {}
-
-ColumnExp
-^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-       PGColumn_ : { Operator_ : Value }
-   }
-
-.. _MetadataOperator:
-
-Operator
-^^^^^^^^
-
-**Generic operators (all column types except json, jsonb) :**
-
-.. list-table::
-   :header-rows: 1
-
-   * - Operator
-     - PostgreSQL equivalent
-   * - ``"$eq"``
-     - ``=``
-   * - ``"$ne"``
-     - ``<>``
-   * - ``"$gt"``
-     - ``>``
-   * - ``"$lt"``
-     - ``<``
-   * - ``"$gte"``
-     - ``>=``
-   * - ``"$lte"``
-     - ``<=``
-   * - ``"$in"``
-     - ``IN``
-   * - ``"$nin"``
-     - ``NOT IN``
-
-(For more details, refer to the Postgres docs for `comparison operators <https://www.postgresql.org/docs/current/functions-comparison.html>`__ and `list based search operators <https://www.postgresql.org/docs/current/functions-comparisons.html>`__.)
-
-**Text related operators :**
-
-.. list-table::
-   :header-rows: 1
-
-   * - Operator
-     - PostgreSQL equivalent
-   * - ``"$like"``
-     - ``LIKE``
-   * - ``"$nlike"``
-     - ``NOT LIKE``
-   * - ``"$ilike"``
-     - ``ILIKE``
-   * - ``"$nilike"``
-     - ``NOT ILIKE``
-   * - ``"$similar"``
-     - ``SIMILAR TO``
-   * - ``"$nsimilar"``
-     - ``NOT SIMILAR TO``
-   * - ``$regex``
-     - ``~``
-   * - ``$iregex``
-     - ``~*``
-   * - ``$nregex``
-     - ``!~``
-   * - ``$niregex``
-     - ``!~*``
-  
-
-(For more details on text related operators, refer to the `Postgres docs <https://www.postgresql.org/docs/current/functions-matching.html>`__.)
-
-**Operators for comparing columns (all column types except json, jsonb):**
-
-.. list-table::
-   :header-rows: 1
-
-   * - Operator
-     - PostgreSQL equivalent
-   * - ``"$ceq"``
-     - ``=``
-   * - ``"$cne"``
-     - ``<>``
-   * - ``"$cgt"``
-     - ``>``
-   * - ``"$clt"``
-     - ``<``
-   * - ``"$cgte"``
-     - ``>=``
-   * - ``"$clte"``
-     - ``<=``
-
-(For more details on comparison operators, refer to the `Postgres docs <https://www.postgresql.org/docs/current/functions-comparison.html>`__.)
-
-**Checking for NULL values :**
-
-.. list-table::
-   :header-rows: 1
-
-   * - Operator
-     - PostgreSQL equivalent
-   * - ``_is_null`` (takes true/false as values)
-     - ``IS NULL``
-
-(For more details on the ``IS NULL`` expression, refer to the `Postgres docs <https://www.postgresql.org/docs/current/functions-comparison.html>`__.)
-
-**JSONB operators :**
-
-.. list-table::
-   :header-rows: 1
-
-   * - Operator
-     - PostgreSQL equivalent
-   * - ``_contains``
-     - ``@>``
-   * - ``_contained_in``
-     - ``<@``
-   * - ``_has_key``
-     - ``?``
-   * - ``_has_keys_any``
-     - ``?!``
-   * - ``_has_keys_all``
-     - ``?&``
-
-(For more details on JSONB operators, refer to the `Postgres docs <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__.)
-
-**PostGIS related operators on GEOMETRY columns:**
-
-.. list-table::
-   :header-rows: 1
-
-   * - Operator
-     - PostGIS equivalent
-   * - ``_st_contains``
-     - ``ST_Contains(column, input)``
-   * - ``_st_crosses``
-     - ``ST_Crosses(column, input)``
-   * - ``_st_equals``
-     - ``ST_Equals(column, input)``
-   * - ``_st_intersects``
-     - ``ST_Intersects(column, input)``
-   * - ``_st_overlaps``
-     - ``ST_Overlaps(column, input)``
-   * - ``_st_touches``
-     - ``ST_Touches(column, input)``
-   * - ``_st_within``
-     - ``ST_Within(column, input)``
-   * - ``_st_d_within``
-     - ``ST_DWithin(column, input)``
-
-(For more details on spatial relationship operators, refer to the `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.)
-
-.. note::
-
-   - All operators take a JSON representation of ``geometry/geography`` values as input value.
-   - The input value for ``_st_d_within`` operator is an object:
-
-     .. parsed-literal::
-
-       {
-         field-name : {_st_d_within: {distance: Float, from: Value} }
-       }
-
-
-.. _Object:
-
-Object
-^^^^^^
-
-A JSONObject_
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-      "k1" : v1,
-      "k2" : v2,
-      ..
-   }
-
-.. _JSONObject: https://tools.ietf.org/html/rfc7159
-
-.. _Empty Object:
-
-Empty Object
-^^^^^^^^^^^^
-
-An empty JSONObject_
-
-.. code-block:: json
-
-   {}
-
-.. _ColumnPresetExp:
-
-ColumnPresetsExp
-^^^^^^^^^^^^^^^^
-A JSONObject_ of a Postgres column name to value mapping, where the value can be static or derived from a session variable.
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-      "column1" : colVal1,
-      "column2" : colVal2,
-      ..
-   }
-
-E.g. where ``id`` is derived from a session variable and ``city`` is a static value.
-
-.. code-block:: json
-
-   {
-      "id" : "x-hasura-User-Id",
-      "city" : "San Francisco"
-   }
-
-.. note::
-
-   If the value of any key begins with "x-hasura-" (*case-insensitive*), the value of the column specified in the key will be derived from a session variable of the same name.
-
-.. _RemoteSchemaName:
-
-RemoteSchemaName
-^^^^^^^^^^^^^^^^
-
-.. parsed-literal::
-
-  String
-
-.. _RemoteSchemaDef:
-
-RemoteSchemaDef
-^^^^^^^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-      "url" : url-string,
-      "url_from_env" : env-var-string,
-      "headers": [
-           { "name": header-name-string,
-             "value": header-value-string,
-             "value_from_env": env-var-string
-           }
-      ],
-      "forward_client_headers": boolean,
-      "timeout_seconds": integer
-   }
-
-.. _CollectionName:
-
-CollectionName
-^^^^^^^^^^^^^^
-
-.. parsed-literal::
-
-  String
-
-.. _QueryName:
-
-QueryName
-^^^^^^^^^
-
-.. parsed-literal::
-
-  String
-
-.. _CollectionQuery:
-
-CollectionQuery
-^^^^^^^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-       "name": String,
-       "query": String
-   }
-
-.. _EndpointUrl:
-
-EndpointUrl
-^^^^^^^^^^^
-
-.. parsed-literal::
-
-  String
-
-.. _EndpointMethods:
-
-EndpointMethods
-^^^^^^^^^^^^^^^
-
-.. parsed-literal::
-
-  [String]
-
-.. _EndpointDef:
-
-EndpointDefinition
-^^^^^^^^^^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-       "query": {
-         "query_name : String,
-         "collection_name" : CollectionName
-       }
-   }
-
-
-.. _CustomColumnNames:
-
-CustomColumnNames
-^^^^^^^^^^^^^^^^^^
-A JSONObject_ of Postgres column name to GraphQL name mapping
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   {
-      "column1" : String,
-      "column2" : String,
-      ..
-   }
-
-.. _ActionName:
-
-ActionName
-^^^^^^^^^^
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   String
-
-
-.. _WebhookURL:
-
-WebhookURL
-^^^^^^^^^^
-
-A String value which supports templating environment variables enclosed in ``{{`` and ``}}``.
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   String
-
-Template example: ``https://{{ACTION_API_DOMAIN}}/create-user``
-
-.. _HeaderFromValue:
-
-HeaderFromValue
-^^^^^^^^^^^^^^^
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - required
-     - Schema
-     - Description
-   * - name
-     - true
-     - String
-     - Name of the header
-   * - value
-     - true
-     - String
-     - Value of the header
-
-.. _HeaderFromEnv:
-
-
-HeaderFromEnv
-^^^^^^^^^^^^^
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - required
-     - Schema
-     - Description
-   * - name
-     - true
-     - String
-     - Name of the header
-   * - value_from_env
-     - true
-     - String
-     - Name of the environment variable which holds the value of the header
-
-.. _GraphQLType:
-
-GraphQLType
-^^^^^^^^^^^
-
-A GraphQL `Type Reference <https://spec.graphql.org/June2018/#sec-Type-References>`__ string.
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   String
-
-Example: ``String!`` for non-nullable String type and ``[String]`` for array of String types
-
-.. _GraphQLName:
-
-GraphQLName
-^^^^^^^^^^^
-
-A string literal that conform to `GraphQL spec <https://spec.graphql.org/June2018/#Name>`__.
-
-.. parsed-literal::
-   :class: haskell-pre
-
-   String

docs/graphql/core/api-reference/schema-metadata-api/table-view.rst

@@ -209,81 +209,6 @@ Args syntax
      - :ref:`Table Config <table_config>`
      - Configuration for the table/view
 
-.. _table_config:
-
-Table Config
-^^^^^^^^^^^^
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - custom_name
-     - false
-     - ``String``
-     - Customise the ``<table-name>`` with the provided custom name value.
-       The GraphQL nodes for the table will be generated according to the custom name.
-   * - custom_root_fields
-     - false
-     - :ref:`Custom Root Fields <custom_root_fields>`
-     - Customise the root fields
-   * - custom_column_names
-     - false
-     - :ref:`CustomColumnNames`
-     - Customise the column fields
-
-.. _custom_root_fields:
-
-Custom Root Fields
-^^^^^^^^^^^^^^^^^^
-
-.. list-table::
-   :header-rows: 1
-
-   * - Key
-     - Required
-     - Schema
-     - Description
-   * - select
-     - false
-     - ``String``
-     - Customise the ``<table-name>`` root field
-   * - select_by_pk
-     - false
-     - ``String``
-     - Customise the ``<table-name>_by_pk`` root field
-   * - select_aggregate
-     - false
-     - ``String``
-     - Customise the ``<table-name>_aggregete`` root field
-   * - insert
-     - false
-     - ``String``
-     - Customise the ``insert_<table-name>`` root field
-   * - insert_one
-     - false
-     - ``String``
-     - Customise the ``insert_<table-name>_one`` root field
-   * - update
-     - false
-     - ``String``
-     - Customise the ``update_<table-name>`` root field
-   * - update_by_pk
-     - false
-     - ``String``
-     - Customise the ``update_<table-name>_by_pk`` root field
-   * - delete
-     - false
-     - ``String``
-     - Customise the ``delete_<table-name>`` root field
-   * - delete_by_pk
-     - false
-     - ``String``
-     - Customise the ``delete_<table-name>_by_pk`` root field
-
 .. _set_table_custom_fields:
 
 set_table_custom_fields (deprecated)
@@ -297,8 +222,6 @@ table fields.
 custom column names of already tracked table. This will **replace** the already
 present custom fields configuration.
 
-
-
 Set custom fields for table/view ``author``:
 
 .. code-block:: http

docs/graphql/core/getting-started/docker-simple.rst

@@ -52,7 +52,7 @@ contains all installation manifests required to deploy Hasura anywhere. Get the
       # or run
       curl https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose-v2.0.0/docker-compose.yaml -o docker-compose.yml
 
-
+   See `changelog <https://github.com/hasura/graphql-engine/releases/tag/v2.0.0-alpha.1>`__
 
 Step 2: Run Hasura GraphQL engine & Postgres
 --------------------------------------------

docs/graphql/core/migrations/config-v1/reference/migration-file-format.rst

@@ -68,7 +68,7 @@ actions, which is represented with a ``-`` in YAML. Here is an example file:
 
 Each one of the actions in these files are actually Hasura metadata API calls,
 which are executed in **sequence** when the migration is applied. You can find
-all the metadata actions that are available in the :ref:`API reference <Query>`.
+all the metadata actions that are available in the :ref:`API reference <api_query>`.
 
 
 SQL Files

docs/graphql/core/migrations/index.rst

@@ -78,8 +78,8 @@ Reference documentation
 -----------------------
 
 - :ref:`migrations_how_it_works`
-- :ref:`Migration file format <migration_file_format_v3>`
+- :ref:`Migration file format <migration_file_format>`
-- :ref:`Metadata format <metadata_format_v3>`
+- :ref:`Metadata format <metadata_format>`
 
 .. toctree::
   :maxdepth: 1

docs/graphql/core/migrations/reference/metadata-format.rst

@@ -2,7 +2,7 @@
    :description: Hasura Metadata file format reference
    :keywords: hasura, docs, metadata, file format
 
-.. _metadata_format_v3:
+.. _metadata_format:
 
 Metadata format reference
 =========================

docs/graphql/core/migrations/reference/migration-file-format.rst

@@ -2,7 +2,7 @@
    :description: Hasura Migration file format reference
    :keywords: hasura, docs, migration, file format
 
-.. _migration_file_format_v3:
+.. _migration_file_format:
 
 Migration file format reference
 ===============================