mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
Marion Schleifer
GitHub
parent
fca16b88ef
commit
2b977bb9b9
121
docs/graphql/manual/api-reference/explain.rst
Normal file
121
docs/graphql/manual/api-reference/explain.rst
Normal file
@ -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.
|
||||
@ -15,23 +15,25 @@ API Reference
|
||||
Available APIs
|
||||
--------------
|
||||
|
||||
+-----------------+----------------------------------------+------------------+
|
||||
| API | Endpoint | Access |
|
||||
+=================+========================================+==================+
|
||||
| GraphQL | :ref:`/v1/graphql <graphql_api>` | Permission rules |
|
||||
+-----------------+----------------------------------------+------------------+
|
||||
| Legacy GraphQL | :ref:`/v1alpha1/graphql <graphql_api>` | Permission rules |
|
||||
+-----------------+----------------------------------------+------------------+
|
||||
| Schema/Metadata | :ref:`/v1/query <schema_metadata_api>` | Admin only |
|
||||
+-----------------+----------------------------------------+------------------+
|
||||
| Version | :ref:`/v1/version <version_api>` | Public |
|
||||
+-----------------+----------------------------------------+------------------+
|
||||
| Health | :ref:`/healthz <health_api>` | Public |
|
||||
+-----------------+----------------------------------------+------------------+
|
||||
| PG Dump | :ref:`/v1alpha1/pg_dump <pg_dump_api>` | Admin only |
|
||||
+-----------------+----------------------------------------+------------------+
|
||||
| Config | :ref:`/v1alpha1/config <config_api>` | Admin only |
|
||||
+-----------------+----------------------------------------+------------------+
|
||||
+-----------------+-----------------------------------------+------------------+
|
||||
| API | Endpoint | Access |
|
||||
+=================+=========================================+==================+
|
||||
| GraphQL | :ref:`/v1/graphql <graphql_api>` | Permission rules |
|
||||
+-----------------+-----------------------------------------+------------------+
|
||||
| Legacy GraphQL | :ref:`/v1alpha1/graphql <graphql_api>` | Permission rules |
|
||||
+-----------------+-----------------------------------------+------------------+
|
||||
| Schema/Metadata | :ref:`/v1/query <schema_metadata_api>` | Admin only |
|
||||
+-----------------+-----------------------------------------+------------------+
|
||||
| Version | :ref:`/v1/version <version_api>` | Public |
|
||||
+-----------------+-----------------------------------------+------------------+
|
||||
| Health | :ref:`/healthz <health_api>` | Public |
|
||||
+-----------------+-----------------------------------------+------------------+
|
||||
| PG Dump | :ref:`/v1alpha1/pg_dump <pg_dump_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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user