Explain API Reference

Introduction

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
POST /v1/graphql/explain HTTP/1.1
Content-Type: application/json

{
     "query": "<query>",
     "user": {
         "x-hasura-role" : "...",
         "x-hasura-session-var1" : "..."
     }
}

Sample request

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:

[
    {
        "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:

{
    "sql": String -- "the generated SQL for the operation",
    "plan": [String] -- "Postgres's plan for the generated SQL"
}

Sample response for a query

[
    {
        "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

{
    "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 Metadata API and can only be disabled by disabling the same.

« previous | next »
Want to contribute or report missing content?

Powered by Sphinx. | Copyright © 2021 Hasura.