EXPLAIN

Explain or analyze the plan for a given statement.

Synopsis

  1. EXPLAIN [ ANALYZE ] statement

Description

The EXPLAIN command displays the execution plan that the planner generates for the supplied statement. The plan is returned as a nested object containing the plan tree.

When issuing EXPLAIN ANALYZE the plan of the statement is executed and timings of the different phases of the plan are returned.

Note

The content of the returned plan tree as well as the level of detail of the timings of the different phases should be considered experimental and are subject to change in future versions. Also not all plan nodes provide in-depth details.

The output of EXPLAIN ANALYZE also includes a break down of the query execution if the statement being explained involves queries which are executed using Lucene.

The output includes verbose low level information per queried shard. Since SQL query expressions do not always have a direct 1:1 mapping to Lucene queries, the output may be more complex but in most cases it should still be possible to identify the most expensive parts of a query expression. Some familiarity with Lucene helps in interpreting the output.

A short excerpt of a query breakdown looks like this:

  1. {
  2.   "QueryName": "PointRangeQuery",
  3.   "QueryDescription": "x:[1 TO 1]",
  4.   "Time": 0.004096,
  5.   "BreakDown": {
  6.     "score": 0,
  7.     "match_count": 0,
  8.     "build_scorer_count": 0,
  9.     "create_weight": 0.004095,
  10.     "next_doc": 0,
  11.     "match": 0,
  12.     "score_count": 0,
  13.     "next_doc_count": 0,
  14.     "create_weight_count": 1,
  15.     "build_scorer": 0,
  16.     "advance_count": 0,
  17.     "advance": 0
  18.   }
  19. }

The time values are in milliseconds. Fields suffixed with _count indicate how often an operation was invoked.

field

description

create_weight

A Weight object is created for a query and acts as a temporary object containing state. This metric shows how long this process took.

build_scorer

A Scorer object is used to iterate over documents matching the query and generate scores for them. Note that this includes only the time to create the scorer, not that actual time spent on the iteration.

score

Shows the time it takes to score a particular document via its Scorer.

next_doc

Shows the time it takes to determine which document is the next match.

advance

A lower level version of next_doc.

match

Some queries use a two-phase execution, doing an approximation first, and then a second more expensive phase. This metric measures the second phase.

Note

Individual timings of the different phases and queries that are profiled do not sum up to the Total. This is because there is usually additional initialization that is not measured. Also, certain phases do overlap during their execution.

Parameters

statement

The statement for which a plan or plan analysis should be returned.

Currently only SELECT and COPY FROM statements are supported.