---
title: "Explain an C8QL query"
method: POST
path: "/_fabric/{fabric}/_api/query/explain"
tags: ["Query"]
---

# Explain an C8QL query

`POST /_fabric/{fabric}/_api/query/explain`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/macrometa/apis/macrometa-api-reference/docs/_fabric/:fabric/_api/query/explain/post.ts> (a function with typed inputs; its response is checked against the schema)

To explain how an C8QL query would run on the server, the query string can be sent to the server via a HTTP POST request. The server validates the query and creates an execution plan for it. The execution plan is returned, but the query does not run.

The execution plan that is returned by the server can be used to estimate the probable performance of the query. Though the actual performance depends on many different factors, the execution plan normally can provide some rough estimates on the amount of work the server needs to do in order to run the query.

By default, the explain operation returns the optimal plan as chosen by the query optimizer. The optimal plan is the plan with the lowest total estimated cost. The response object contains the plan as a *plan* attribute. If the option *allPlans* is specified in the request, the result contains all plans created by the optimizer. The plans are returned in the attribute *plans*.

The result also contains an attribute *warnings*, that is an array of warnings that occurred during optimization or execution of plan creation. Additionally, the result contains a *stats* attribute with optimizer statistics. If *allPlans* is set to *false*, the result contains an attribute *cacheable* that states whether the query results can be cached on the server if the query result cache were used. The *cacheable* attribute is not present when *allPlans* is set to *true*.

Each plan in the result is a JSON object with the following attributes:
- *nodes*: the array of execution nodes of the plan.
- *estimatedCost*: the total estimated cost for the plan. If there are multiple plans, the optimizer chooses the plan with the lowest total cost.
- *collections*: an array of collections used in the query
- *rules*: an array of rules the optimizer applied.
- *variables*: array of variables used in the query.

## Path parameters

- `fabric` string, string, required

## Request body

- ApiExplain
  - `bindVars` object[]: Key/value pairs representing the bind parameters.
  - `options` ExplainOptions: Options for the query.
    - `allPlans` boolean: If set to *true*, all possible execution are returned. The default is *false*, meaning only the optimal plan is be returned.
    - `maxNumberOfPlans` integer: An optional maximum number of plans that the optimizer is allowed to generate. Setting this attribute to a low value allows to put a cap on the amount of work the optimizer does.
    - `optimizer.rules` string[]: An array of to-be-included or to-be-excluded optimizer rules can be put into this attribute, telling the optimizer to include or exclude specific rules. To disable a rule, prefix its name with a `-`, to enable a rule, prefix it with a `+`. There is also a pseudo-rule `all`, which matches all optimizer rules.
  - `query` string, required: The query which you want explained. If the query references any bind variables, these must also be passed in the attribute *bindVars*. Additional options for the query can be passed in the *options* attribute.

## Response `200`

Successfully fetched the optimal execution plan in the *plan* attribute. If option *allPlans* is set in the request, an array of plans is returned in the *allPlans* attribute instead.

- unknown

## Other responses

- `400`: Failed due to missing, malformed data or the query contains a parse error. Verify that all parameters are complete.
- `404`: Failed to validate query due to non-existing collection being accessed by the query.

---

[API](https://skmtc.dev/macrometa/apis/macrometa-api-reference.md) - [All operations](https://skmtc.dev/macrometa/apis/macrometa-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/macrometa/apis/macrometa-api-reference/revisions/2006b6d7f31d?raw)