docs: document explain api (close #870) (#3739)

docs/graphql/manual/api-reference/explain.rst

@@ -0,0 +1,121 @@
+.. _explain_api_reference:
+
+Explain API Reference
+=====================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+The Explain API is used to analyse queries and subscriptions. It returns a list of Postgres plans for a query and a single Postgres plan for a subscription, based
+on the defined permissions.
+
+Endpoint
+--------
+
+All requests are ``POST`` requests to the ``/v1/graphql/explain`` endpoint.
+
+API Spec
+--------
+
+Request
+^^^^^^^
+
+The request expects a JSON object with the following keys:
+  - ``query``: the GraphQL query to be analysed
+  - ``user`` (optional): the ``x-hasura-role`` along with session variables
+
+.. code-block:: http
+
+   POST /v1/graphql/explain HTTP/1.1
+   Content-Type: application/json
+
+   {
+        "query": <query>,
+        "user": {
+            "x-hasura-role" : "...",
+            "x-hasura-session-var1" : "..."
+        }
+   }
+
+Sample request
+**************
+
+.. code-block:: http
+
+   POST /v1/graphql/explain HTTP/1.1
+   Content-Type: application/json
+
+   {
+        "query": {
+            "query": "query getAuthors { authors { name }}",
+            "operationName": "getAuthors"
+        }
+   }
+
+
+Response
+^^^^^^^^
+
+The response for a query is a list of plans:
+
+.. code-block:: json
+
+    [
+        {
+            "field": String -- "name of the field",
+            "sql": String -- "the generated SQL for the operation",
+            "plan": [String] -- "Postgres's plan for the generated SQL"
+        }
+    ]
+
+The response for a subscription is a single plan:
+
+.. code-block:: json
+
+    {
+        "sql": String -- "the generated SQL for the operation",
+        "plan": [String] -- "Postgres's plan for the generated SQL"
+    }
+
+Sample response for a query
+***************************
+
+.. code-block:: json
+
+    [
+        {
+            "field": "authors",
+            "sql": "SELECT  coalesce(json_agg(\"root\" ), '[]' ) AS \"root\" FROM  (SELECT  row_to_json((SELECT  \"_1_e\"  FROM  (SELECT  \"_0_root.base\".\"name\" AS \"name\"       ) AS \"_1_e\"      ) ) AS \"root\" FROM  (SELECT  *  FROM \"public\".\"authors\"  WHERE ('true')     ) AS \"_0_root.base\"      ) AS \"_2_root\"      ",
+            "plan": [
+                "Aggregate  (cost=14.27..14.27 rows=1 width=32)",
+                "  ->  Seq Scan on authors  (cost=0.00..11.83 rows=610 width=32)",
+                "  SubPlan 1",
+                "    ->  Result  (cost=0.00..0.00 rows=1 width=32)"
+            ]
+        }
+    ]
+
+Sample response for a subscription
+**********************************
+
+.. code-block:: json
+
+    {
+        "sql": "\n        select\n          _subs.result_id, _fld_resp.root as result\n          from\n            unnest(\n              $1::uuid[], $2::json[]\n            ) _subs (result_id, result_vars)\n          left outer join lateral\n            (\n        SELECT  coalesce(json_agg(\"root\" ), '[]' ) AS \"root\" FROM  (SELECT  row_to_json((SELECT  \"_1_e\"  FROM  (SELECT  \"_0_root.base\".\"name\" AS \"name\"       ) AS \"_1_e\"      ) ) AS \"root\" FROM  (SELECT  *  FROM \"public\".\"authors\"  WHERE ('true')     ) AS \"_0_root.base\"      ) AS \"_2_root\"      \n            ) _fld_resp ON ('true')\n        ",
+        "plan": [
+            "Nested Loop Left Join  (cost=14.27..14.93 rows=100 width=48)",
+            "  ->  Function Scan on _subs  (cost=0.00..0.30 rows=100 width=16)",
+            "  ->  Materialize  (cost=14.27..14.28 rows=1 width=32)",
+            "        ->  Aggregate  (cost=14.27..14.27 rows=1 width=32)",
+            "              ->  Seq Scan on authors  (cost=0.00..11.83 rows=610 width=32)",
+            "              SubPlan 1",
+            "                ->  Result  (cost=0.00..0.00 rows=1 width=32)"
+        ]
+    }
+
+Disabling Explain API
+---------------------
+
+The Explain API is part of the :doc:`Metadata API <schema-metadata-api/index>` and can only be disabled by disabling the same.

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

@@ -15,23 +15,25 @@ API Reference
 Available APIs
 --------------
 
-+-----------------+----------------------------------------+------------------+
++-----------------+-----------------------------------------+------------------+
-| API             | Endpoint                               | Access           |
+| API             | Endpoint                                | Access           |
-+=================+========================================+==================+
++=================+=========================================+==================+
-| GraphQL         | :ref:`/v1/graphql <graphql_api>`       | Permission rules |
+| GraphQL         | :ref:`/v1/graphql <graphql_api>`        | Permission rules |
-+-----------------+----------------------------------------+------------------+
++-----------------+-----------------------------------------+------------------+
-| Legacy GraphQL  | :ref:`/v1alpha1/graphql <graphql_api>` | Permission rules |
+| Legacy GraphQL  | :ref:`/v1alpha1/graphql <graphql_api>`  | Permission rules |
-+-----------------+----------------------------------------+------------------+
++-----------------+-----------------------------------------+------------------+
-| Schema/Metadata | :ref:`/v1/query <schema_metadata_api>` | Admin only       |
+| Schema/Metadata | :ref:`/v1/query <schema_metadata_api>`  | Admin only       |
-+-----------------+----------------------------------------+------------------+
++-----------------+-----------------------------------------+------------------+
-| Version         | :ref:`/v1/version <version_api>`       | Public           |
+| Version         | :ref:`/v1/version <version_api>`        | Public           |
-+-----------------+----------------------------------------+------------------+
++-----------------+-----------------------------------------+------------------+
-| Health          | :ref:`/healthz <health_api>`           | Public           |
+| Health          | :ref:`/healthz <health_api>`            | Public           |
-+-----------------+----------------------------------------+------------------+
++-----------------+-----------------------------------------+------------------+
-| PG Dump         | :ref:`/v1alpha1/pg_dump <pg_dump_api>` | Admin only       |
+| PG Dump         | :ref:`/v1alpha1/pg_dump <pg_dump_api>`  | Admin only       |
-+-----------------+----------------------------------------+------------------+
++-----------------+-----------------------------------------+------------------+
-| Config          | :ref:`/v1alpha1/config <config_api>`   | Admin only       |
+| Config          | :ref:`/v1alpha1/config <config_api>`    | Admin only       |
-+-----------------+----------------------------------------+------------------+
++-----------------+-----------------------------------------+------------------+
+| Explain         | :ref:`/v1/graphql/explain <explain_api>`| Admin only       |
++-----------------+-----------------------------------------+------------------+
 
 .. _graphql_api:
 
@@ -94,6 +96,16 @@ configuration.
 
 See details at :doc:`config`.
 
+.. _explain_api:
+
+Explain API
+^^^^^^^^^^^
+
+``v1/graphql/explain`` returns the Postgres plan for a query or subscription based
+on the defined permissions.
+
+See details at :doc:`explain`.
+
 Supported PostgreSQL types
 --------------------------
 You can refer to the following to know about all PostgreSQL types supported by the Hasura GraphQL engine:
@@ -110,4 +122,5 @@ You can refer to the following to know about all PostgreSQL types supported by t
   Health check API <health>
   PG Dump API <pgdump>
   Config API <config>
+  Explain API <explain>
   Supported PostgreSQL types <postgresql-types>