MAmacrometa
Query

Explain an C8QL query

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.
post/_fabric/{fabric}/_api/query/explain

Request

Path parameters

fabricstring string required

The name of the fabric.

Request body

bindVarsobject[]

Key/value pairs representing the bind parameters.

querystring 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

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 required

Example response

{
  "code": 200,
  "error": false,
  "plans": [
    {
      "nodes": [
        {
          "type": "SingletonNode",
          "dependencies": [],
          "id": 1,
          "estimatedCost": 1,
          "estimatedNrItems": 1
        },
        {
          "type": "EnumerateCollectionNode",
          "dependencies": [
            1
          ],
          "id": 2,
          "estimatedCost": 9,
          "estimatedNrItems": 7,
          "random": false,
          "indexHint": {
            "forced": false,
            "type": "none"
          },
          "outVariable": {
            "id": 0,
            "name": "u"
          },
          "projections": [],
          "producesResult": true,
          "database": "_system",
          "collection": "testCollection",
          "satellite": false
        },
        {
          "type": "ReturnNode",
          "dependencies": [
            2
          ],
          "id": 3,
          "estimatedCost": 16,
          "estimatedNrItems": 7,
          "inVariable": {
            "id": 0,
            "name": "u"
          },
          "count": true
        }
      ],
      "rules": [],
      "collections": [
        {
          "name": "testCollection",
          "type": "read"
        }
      ],
      "variables": [
        {
          "id": 0,
          "name": "u"
        }
      ],
      "estimatedCost": 16,
      "estimatedNrItems": 7,
      "initialize": true,
      "isModificationQuery": false
    }
  ],
  "warnings": [],
  "stats": {
    "rulesExecuted": 35,
    "rulesSkipped": 1,
    "plansCreated": 1
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.