explain.h File Reference

#include "executor/executor.h"
#include "lib/stringinfo.h"
#include "parser/parse_node.h"

Include dependency graph for explain.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ExplainWorkersState
struct	ExplainState

Typedefs
typedef enum ExplainFormat	ExplainFormat
typedef struct ExplainWorkersState	ExplainWorkersState
typedef struct ExplainState	ExplainState
typedef void(*	ExplainOneQuery_hook_type) (Query *query, int cursorOptions, IntoClause *into, ExplainState *es, const char *queryString, ParamListInfo params, QueryEnvironment *queryEnv)
typedef const char *(*	explain_get_index_name_hook_type) (Oid indexId)

Enumerations
enum	ExplainFormat { EXPLAIN_FORMAT_TEXT , EXPLAIN_FORMAT_XML , EXPLAIN_FORMAT_JSON , EXPLAIN_FORMAT_YAML }

Functions
void	ExplainQuery (ParseState *pstate, ExplainStmt *stmt, ParamListInfo params, DestReceiver *dest)
ExplainState *	NewExplainState (void)
TupleDesc	ExplainResultDesc (ExplainStmt *stmt)
void	ExplainOneUtility (Node *utilityStmt, IntoClause *into, ExplainState *es, const char *queryString, ParamListInfo params, QueryEnvironment *queryEnv)
void	ExplainOnePlan (PlannedStmt *plannedstmt, IntoClause *into, ExplainState *es, const char *queryString, ParamListInfo params, QueryEnvironment *queryEnv, const instr_time *planduration, const BufferUsage *bufusage)
void	ExplainPrintPlan (ExplainState *es, QueryDesc *queryDesc)
void	ExplainPrintTriggers (ExplainState *es, QueryDesc *queryDesc)
void	ExplainPrintJITSummary (ExplainState *es, QueryDesc *queryDesc)
void	ExplainQueryText (ExplainState *es, QueryDesc *queryDesc)
void	ExplainQueryParameters (ExplainState *es, ParamListInfo params, int maxlen)
void	ExplainBeginOutput (ExplainState *es)
void	ExplainEndOutput (ExplainState *es)
void	ExplainSeparatePlans (ExplainState *es)
void	ExplainPropertyList (const char *qlabel, List *data, ExplainState *es)
void	ExplainPropertyListNested (const char *qlabel, List *data, ExplainState *es)
void	ExplainPropertyText (const char *qlabel, const char *value, ExplainState *es)
void	ExplainPropertyInteger (const char *qlabel, const char *unit, int64 value, ExplainState *es)
void	ExplainPropertyUInteger (const char *qlabel, const char *unit, uint64 value, ExplainState *es)
void	ExplainPropertyFloat (const char *qlabel, const char *unit, double value, int ndigits, ExplainState *es)
void	ExplainPropertyBool (const char *qlabel, bool value, ExplainState *es)
void	ExplainOpenGroup (const char *objtype, const char *labelname, bool labeled, ExplainState *es)
void	ExplainCloseGroup (const char *objtype, const char *labelname, bool labeled, ExplainState *es)

Variables
PGDLLIMPORT ExplainOneQuery_hook_type	ExplainOneQuery_hook
PGDLLIMPORT explain_get_index_name_hook_type	explain_get_index_name_hook

Typedef Documentation

explain_get_index_name_hook_type

typedef const char*(* explain_get_index_name_hook_type) (Oid indexId)

Definition at line 76 of file explain.h.

ExplainFormat

typedef enum ExplainFormat ExplainFormat

ExplainOneQuery_hook_type

typedef void(* ExplainOneQuery_hook_type) (Query *query, int cursorOptions, IntoClause *into, ExplainState *es, const char *queryString, ParamListInfo params, QueryEnvironment *queryEnv)

Definition at line 66 of file explain.h.

ExplainState

typedef struct ExplainState ExplainState

ExplainWorkersState

typedef struct ExplainWorkersState ExplainWorkersState

Enumeration Type Documentation

ExplainFormat

enum ExplainFormat

Enumerator
EXPLAIN_FORMAT_TEXT
EXPLAIN_FORMAT_XML
EXPLAIN_FORMAT_JSON
EXPLAIN_FORMAT_YAML

Definition at line 20 of file explain.h.

{
    EXPLAIN_FORMAT_TEXT,
    EXPLAIN_FORMAT_XML,
    EXPLAIN_FORMAT_JSON,
    EXPLAIN_FORMAT_YAML
} ExplainFormat;

Function Documentation

ExplainBeginOutput()

void ExplainBeginOutput

(

ExplainState *

es

)

Definition at line 4872 of file explain.c.

{
    switch (es->format)
    {
        case EXPLAIN_FORMAT_TEXT:
            /* nothing to do */
            break;
 
        case EXPLAIN_FORMAT_XML:
            appendStringInfoString(es->str,
                                   "<explain xmlns=\"http://www.postgresql.org/2009/explain\">\n");
            es->indent++;
            break;
 
        case EXPLAIN_FORMAT_JSON:
            /* top-level structure is an array of plans */
            appendStringInfoChar(es->str, '[');
            es->grouping_stack = lcons_int(0, es->grouping_stack);
            es->indent++;
            break;
 
        case EXPLAIN_FORMAT_YAML:
            es->grouping_stack = lcons_int(0, es->grouping_stack);
            break;
    }
}

References appendStringInfoChar(), appendStringInfoString(), EXPLAIN_FORMAT_JSON, EXPLAIN_FORMAT_TEXT, EXPLAIN_FORMAT_XML, EXPLAIN_FORMAT_YAML, ExplainState::format, ExplainState::grouping_stack, ExplainState::indent, lcons_int(), and ExplainState::str.

Referenced by explain_ExecutorEnd(), and ExplainQuery().

ExplainCloseGroup()

void ExplainCloseGroup	(	const char *	objtype,
		const char *	labelname,
		bool	labeled,
		ExplainState *	es
	)

Definition at line 4679 of file explain.c.

{
    switch (es->format)
    {
        case EXPLAIN_FORMAT_TEXT:
            /* nothing to do */
            break;
 
        case EXPLAIN_FORMAT_XML:
            es->indent--;
            ExplainXMLTag(objtype, X_CLOSING, es);
            break;
 
        case EXPLAIN_FORMAT_JSON:
            es->indent--;
            appendStringInfoChar(es->str, '\n');
            appendStringInfoSpaces(es->str, 2 * es->indent);
            appendStringInfoChar(es->str, labeled ? '}' : ']');
            es->grouping_stack = list_delete_first(es->grouping_stack);
            break;
 
        case EXPLAIN_FORMAT_YAML:
            es->indent--;
            es->grouping_stack = list_delete_first(es->grouping_stack);
            break;
    }
}

References appendStringInfoChar(), appendStringInfoSpaces(), EXPLAIN_FORMAT_JSON, EXPLAIN_FORMAT_TEXT, EXPLAIN_FORMAT_XML, EXPLAIN_FORMAT_YAML, ExplainXMLTag(), ExplainState::format, ExplainState::grouping_stack, ExplainState::indent, list_delete_first(), ExplainState::str, and X_CLOSING.

Referenced by ExplainFlushWorkersState(), ExplainNode(), ExplainOnePlan(), ExplainPrintJIT(), ExplainPrintSettings(), ExplainPrintTriggers(), report_triggers(), show_grouping_set_keys(), show_grouping_sets(), show_incremental_sort_group_info(), and show_modifytable_info().

ExplainEndOutput()

void ExplainEndOutput

(

ExplainState *

es

)

Definition at line 4903 of file explain.c.

{
    switch (es->format)
    {
        case EXPLAIN_FORMAT_TEXT:
            /* nothing to do */
            break;
 
        case EXPLAIN_FORMAT_XML:
            es->indent--;
            appendStringInfoString(es->str, "</explain>");
            break;
 
        case EXPLAIN_FORMAT_JSON:
            es->indent--;
            appendStringInfoString(es->str, "\n]");
            es->grouping_stack = list_delete_first(es->grouping_stack);
            break;
 
        case EXPLAIN_FORMAT_YAML:
            es->grouping_stack = list_delete_first(es->grouping_stack);
            break;
    }
}

References appendStringInfoString(), EXPLAIN_FORMAT_JSON, EXPLAIN_FORMAT_TEXT, EXPLAIN_FORMAT_XML, EXPLAIN_FORMAT_YAML, ExplainState::format, ExplainState::grouping_stack, ExplainState::indent, list_delete_first(), and ExplainState::str.

Referenced by explain_ExecutorEnd(), and ExplainQuery().

ExplainOnePlan()

void ExplainOnePlan	(	PlannedStmt *	plannedstmt,
		IntoClause *	into,
		ExplainState *	es,
		const char *	queryString,
		ParamListInfo	params,
		QueryEnvironment *	queryEnv,
		const instr_time *	planduration,
		const BufferUsage *	bufusage
	)

Definition at line 527 of file explain.c.

{
    DestReceiver *dest;
    QueryDesc  *queryDesc;
    instr_time  starttime;
    double      totaltime = 0;
    int         eflags;
    int         instrument_option = 0;
 
    Assert(plannedstmt->commandType != CMD_UTILITY);
 
    if (es->analyze && es->timing)
        instrument_option |= INSTRUMENT_TIMER;
    else if (es->analyze)
        instrument_option |= INSTRUMENT_ROWS;
 
    if (es->buffers)
        instrument_option |= INSTRUMENT_BUFFERS;
    if (es->wal)
        instrument_option |= INSTRUMENT_WAL;
 
    /*
     * We always collect timing for the entire statement, even when node-level
     * timing is off, so we don't look at es->timing here.  (We could skip
     * this if !es->summary, but it's hardly worth the complication.)
     */
    INSTR_TIME_SET_CURRENT(starttime);
 
    /*
     * Use a snapshot with an updated command ID to ensure this query sees
     * results of any previously executed queries.
     */
    PushCopiedSnapshot(GetActiveSnapshot());
    UpdateActiveSnapshotCommandId();
 
    /*
     * Normally we discard the query's output, but if explaining CREATE TABLE
     * AS, we'd better use the appropriate tuple receiver.
     */
    if (into)
        dest = CreateIntoRelDestReceiver(into);
    else
        dest = None_Receiver;
 
    /* Create a QueryDesc for the query */
    queryDesc = CreateQueryDesc(plannedstmt, queryString,
                                GetActiveSnapshot(), InvalidSnapshot,
                                dest, params, queryEnv, instrument_option);
 
    /* Select execution options */
    if (es->analyze)
        eflags = 0;             /* default run-to-completion flags */
    else
        eflags = EXEC_FLAG_EXPLAIN_ONLY;
    if (es->generic)
        eflags |= EXEC_FLAG_EXPLAIN_GENERIC;
    if (into)
        eflags |= GetIntoRelEFlags(into);
 
    /* call ExecutorStart to prepare the plan for execution */
    ExecutorStart(queryDesc, eflags);
 
    /* Execute the plan for statistics if asked for */
    if (es->analyze)
    {
        ScanDirection dir;
 
        /* EXPLAIN ANALYZE CREATE TABLE AS WITH NO DATA is weird */
        if (into && into->skipData)
            dir = NoMovementScanDirection;
        else
            dir = ForwardScanDirection;
 
        /* run the plan */
        ExecutorRun(queryDesc, dir, 0, true);
 
        /* run cleanup too */
        ExecutorFinish(queryDesc);
 
        /* We can't run ExecutorEnd 'till we're done printing the stats... */
        totaltime += elapsed_time(&starttime);
    }
 
    ExplainOpenGroup("Query", NULL, true, es);
 
    /* Create textual dump of plan tree */
    ExplainPrintPlan(es, queryDesc);
 
    /* Show buffer usage in planning */
    if (bufusage)
    {
        ExplainOpenGroup("Planning", "Planning", true, es);
        show_buffer_usage(es, bufusage, true);
        ExplainCloseGroup("Planning", "Planning", true, es);
    }
 
    if (es->summary && planduration)
    {
        double      plantime = INSTR_TIME_GET_DOUBLE(*planduration);
 
        ExplainPropertyFloat("Planning Time", "ms", 1000.0 * plantime, 3, es);
    }
 
    /* Print info about runtime of triggers */
    if (es->analyze)
        ExplainPrintTriggers(es, queryDesc);
 
    /*
     * Print info about JITing. Tied to es->costs because we don't want to
     * display this in regression tests, as it'd cause output differences
     * depending on build options.  Might want to separate that out from COSTS
     * at a later stage.
     */
    if (es->costs)
        ExplainPrintJITSummary(es, queryDesc);
 
    /*
     * Close down the query and free resources.  Include time for this in the
     * total execution time (although it should be pretty minimal).
     */
    INSTR_TIME_SET_CURRENT(starttime);
 
    ExecutorEnd(queryDesc);
 
    FreeQueryDesc(queryDesc);
 
    PopActiveSnapshot();
 
    /* We need a CCI just in case query expanded to multiple plans */
    if (es->analyze)
        CommandCounterIncrement();
 
    totaltime += elapsed_time(&starttime);
 
    /*
     * We only report execution time if we actually ran the query (that is,
     * the user specified ANALYZE), and if summary reporting is enabled (the
     * user can set SUMMARY OFF to not have the timing information included in
     * the output).  By default, ANALYZE sets SUMMARY to true.
     */
    if (es->summary && es->analyze)
        ExplainPropertyFloat("Execution Time", "ms", 1000.0 * totaltime, 3,
                             es);
 
    ExplainCloseGroup("Query", NULL, true, es);
}

References ExplainState::analyze, Assert(), ExplainState::buffers, CMD_UTILITY, CommandCounterIncrement(), PlannedStmt::commandType, ExplainState::costs, CreateIntoRelDestReceiver(), CreateQueryDesc(), generate_unaccent_rules::dest, elapsed_time(), EXEC_FLAG_EXPLAIN_GENERIC, EXEC_FLAG_EXPLAIN_ONLY, ExecutorEnd(), ExecutorFinish(), ExecutorRun(), ExecutorStart(), ExplainCloseGroup(), ExplainOpenGroup(), ExplainPrintJITSummary(), ExplainPrintPlan(), ExplainPrintTriggers(), ExplainPropertyFloat(), ForwardScanDirection, FreeQueryDesc(), ExplainState::generic, GetActiveSnapshot(), GetIntoRelEFlags(), INSTR_TIME_GET_DOUBLE, INSTR_TIME_SET_CURRENT, INSTRUMENT_BUFFERS, INSTRUMENT_ROWS, INSTRUMENT_TIMER, INSTRUMENT_WAL, InvalidSnapshot, NoMovementScanDirection, None_Receiver, PopActiveSnapshot(), PushCopiedSnapshot(), show_buffer_usage(), IntoClause::skipData, ExplainState::summary, ExplainState::timing, UpdateActiveSnapshotCommandId(), and ExplainState::wal.

Referenced by ExplainExecuteQuery(), and ExplainOneQuery().

ExplainOneUtility()

void ExplainOneUtility	(	Node *	utilityStmt,
		IntoClause *	into,
		ExplainState *	es,
		const char *	queryString,
		ParamListInfo	params,
		QueryEnvironment *	queryEnv
	)

Definition at line 437 of file explain.c.

{
    if (utilityStmt == NULL)
        return;
 
    if (IsA(utilityStmt, CreateTableAsStmt))
    {
        /*
         * We have to rewrite the contained SELECT and then pass it back to
         * ExplainOneQuery.  Copy to be safe in the EXPLAIN EXECUTE case.
         */
        CreateTableAsStmt *ctas = (CreateTableAsStmt *) utilityStmt;
        List       *rewritten;
 
        /*
         * Check if the relation exists or not.  This is done at this stage to
         * avoid query planning or execution.
         */
        if (CreateTableAsRelExists(ctas))
        {
            if (ctas->objtype == OBJECT_TABLE)
                ExplainDummyGroup("CREATE TABLE AS", NULL, es);
            else if (ctas->objtype == OBJECT_MATVIEW)
                ExplainDummyGroup("CREATE MATERIALIZED VIEW", NULL, es);
            else
                elog(ERROR, "unexpected object type: %d",
                     (int) ctas->objtype);
            return;
        }
 
        rewritten = QueryRewrite(castNode(Query, copyObject(ctas->query)));
        Assert(list_length(rewritten) == 1);
        ExplainOneQuery(linitial_node(Query, rewritten),
                        CURSOR_OPT_PARALLEL_OK, ctas->into, es,
                        queryString, params, queryEnv);
    }
    else if (IsA(utilityStmt, DeclareCursorStmt))
    {
        /*
         * Likewise for DECLARE CURSOR.
         *
         * Notice that if you say EXPLAIN ANALYZE DECLARE CURSOR then we'll
         * actually run the query.  This is different from pre-8.3 behavior
         * but seems more useful than not running the query.  No cursor will
         * be created, however.
         */
        DeclareCursorStmt *dcs = (DeclareCursorStmt *) utilityStmt;
        List       *rewritten;
 
        rewritten = QueryRewrite(castNode(Query, copyObject(dcs->query)));
        Assert(list_length(rewritten) == 1);
        ExplainOneQuery(linitial_node(Query, rewritten),
                        dcs->options, NULL, es,
                        queryString, params, queryEnv);
    }
    else if (IsA(utilityStmt, ExecuteStmt))
        ExplainExecuteQuery((ExecuteStmt *) utilityStmt, into, es,
                            queryString, params, queryEnv);
    else if (IsA(utilityStmt, NotifyStmt))
    {
        if (es->format == EXPLAIN_FORMAT_TEXT)
            appendStringInfoString(es->str, "NOTIFY\n");
        else
            ExplainDummyGroup("Notify", NULL, es);
    }
    else
    {
        if (es->format == EXPLAIN_FORMAT_TEXT)
            appendStringInfoString(es->str,
                                   "Utility statements have no plan structure\n");
        else
            ExplainDummyGroup("Utility Statement", NULL, es);
    }
}

References appendStringInfoString(), Assert(), castNode, copyObject, CreateTableAsRelExists(), CURSOR_OPT_PARALLEL_OK, elog(), ERROR, EXPLAIN_FORMAT_TEXT, ExplainDummyGroup(), ExplainExecuteQuery(), ExplainOneQuery(), ExplainState::format, CreateTableAsStmt::into, IsA, linitial_node, list_length(), OBJECT_MATVIEW, OBJECT_TABLE, CreateTableAsStmt::objtype, DeclareCursorStmt::options, DeclareCursorStmt::query, CreateTableAsStmt::query, QueryRewrite(), and ExplainState::str.

Referenced by ExplainExecuteQuery(), and ExplainOneQuery().

ExplainOpenGroup()

void ExplainOpenGroup	(	const char *	objtype,
		const char *	labelname,
		bool	labeled,
		ExplainState *	es
	)

Definition at line 4616 of file explain.c.

{
    switch (es->format)
    {
        case EXPLAIN_FORMAT_TEXT:
            /* nothing to do */
            break;
 
        case EXPLAIN_FORMAT_XML:
            ExplainXMLTag(objtype, X_OPENING, es);
            es->indent++;
            break;
 
        case EXPLAIN_FORMAT_JSON:
            ExplainJSONLineEnding(es);
            appendStringInfoSpaces(es->str, 2 * es->indent);
            if (labelname)
            {
                escape_json(es->str, labelname);
                appendStringInfoString(es->str, ": ");
            }
            appendStringInfoChar(es->str, labeled ? '{' : '[');
 
            /*
             * In JSON format, the grouping_stack is an integer list.  0 means
             * we've emitted nothing at this grouping level, 1 means we've
             * emitted something (and so the next item needs a comma). See
             * ExplainJSONLineEnding().
             */
            es->grouping_stack = lcons_int(0, es->grouping_stack);
            es->indent++;
            break;
 
        case EXPLAIN_FORMAT_YAML:
 
            /*
             * In YAML format, the grouping stack is an integer list.  0 means
             * we've emitted nothing at this grouping level AND this grouping
             * level is unlabeled and must be marked with "- ".  See
             * ExplainYAMLLineStarting().
             */
            ExplainYAMLLineStarting(es);
            if (labelname)
            {
                appendStringInfo(es->str, "%s: ", labelname);
                es->grouping_stack = lcons_int(1, es->grouping_stack);
            }
            else
            {
                appendStringInfoString(es->str, "- ");
                es->grouping_stack = lcons_int(0, es->grouping_stack);
            }
            es->indent++;
            break;
    }
}

References appendStringInfo(), appendStringInfoChar(), appendStringInfoSpaces(), appendStringInfoString(), escape_json(), EXPLAIN_FORMAT_JSON, EXPLAIN_FORMAT_TEXT, EXPLAIN_FORMAT_XML, EXPLAIN_FORMAT_YAML, ExplainJSONLineEnding(), ExplainXMLTag(), ExplainYAMLLineStarting(), ExplainState::format, ExplainState::grouping_stack, ExplainState::indent, lcons_int(), ExplainState::str, and X_OPENING.

Referenced by ExplainFlushWorkersState(), ExplainNode(), ExplainOnePlan(), ExplainPrintJIT(), ExplainPrintSettings(), ExplainPrintTriggers(), report_triggers(), show_grouping_set_keys(), show_grouping_sets(), show_incremental_sort_group_info(), and show_modifytable_info().

ExplainPrintJITSummary()

void ExplainPrintJITSummary	(	ExplainState *	es,
		QueryDesc *	queryDesc
	)

Definition at line 860 of file explain.c.

{
    JitInstrumentation ji = {0};
 
    if (!(queryDesc->estate->es_jit_flags & PGJIT_PERFORM))
        return;
 
    /*
     * Work with a copy instead of modifying the leader state, since this
     * function may be called twice
     */
    if (queryDesc->estate->es_jit)
        InstrJitAgg(&ji, &queryDesc->estate->es_jit->instr);
 
    /* If this process has done JIT in parallel workers, merge stats */
    if (queryDesc->estate->es_jit_worker_instr)
        InstrJitAgg(&ji, queryDesc->estate->es_jit_worker_instr);
 
    ExplainPrintJIT(es, queryDesc->estate->es_jit_flags, &ji);
}

References EState::es_jit, EState::es_jit_flags, EState::es_jit_worker_instr, QueryDesc::estate, ExplainPrintJIT(), JitContext::instr, InstrJitAgg(), and PGJIT_PERFORM.

Referenced by explain_ExecutorEnd(), and ExplainOnePlan().

ExplainPrintPlan()

void ExplainPrintPlan	(	ExplainState *	es,
		QueryDesc *	queryDesc
	)

Definition at line 752 of file explain.c.

{
    Bitmapset  *rels_used = NULL;
    PlanState  *ps;
 
    /* Set up ExplainState fields associated with this plan tree */
    Assert(queryDesc->plannedstmt != NULL);
    es->pstmt = queryDesc->plannedstmt;
    es->rtable = queryDesc->plannedstmt->rtable;
    ExplainPreScanNode(queryDesc->planstate, &rels_used);
    es->rtable_names = select_rtable_names_for_explain(es->rtable, rels_used);
    es->deparse_cxt = deparse_context_for_plan_tree(queryDesc->plannedstmt,
                                                    es->rtable_names);
    es->printed_subplans = NULL;
 
    /*
     * Sometimes we mark a Gather node as "invisible", which means that it's
     * not to be displayed in EXPLAIN output.  The purpose of this is to allow
     * running regression tests with debug_parallel_query=regress to get the
     * same results as running the same tests with debug_parallel_query=off.
     * Such marking is currently only supported on a Gather at the top of the
     * plan.  We skip that node, and we must also hide per-worker detail data
     * further down in the plan tree.
     */
    ps = queryDesc->planstate;
    if (IsA(ps, GatherState) && ((Gather *) ps->plan)->invisible)
    {
        ps = outerPlanState(ps);
        es->hide_workers = true;
    }
    ExplainNode(ps, NIL, NULL, NULL, es);
 
    /*
     * If requested, include information about GUC parameters with values that
     * don't match the built-in defaults.
     */
    ExplainPrintSettings(es);
 
    /*
     * COMPUTE_QUERY_ID_REGRESS means COMPUTE_QUERY_ID_AUTO, but we don't show
     * the queryid in any of the EXPLAIN plans to keep stable the results
     * generated by regression test suites.
     */
    if (es->verbose && queryDesc->plannedstmt->queryId != UINT64CONST(0) &&
        compute_query_id != COMPUTE_QUERY_ID_REGRESS)
    {
        /*
         * Output the queryid as an int64 rather than a uint64 so we match
         * what would be seen in the BIGINT pg_stat_statements.queryid column.
         */
        ExplainPropertyInteger("Query Identifier", NULL, (int64)
                               queryDesc->plannedstmt->queryId, es);
    }
}

References Assert(), compute_query_id, COMPUTE_QUERY_ID_REGRESS, deparse_context_for_plan_tree(), ExplainState::deparse_cxt, ExplainNode(), ExplainPreScanNode(), ExplainPrintSettings(), ExplainPropertyInteger(), ExplainState::hide_workers, IsA, NIL, outerPlanState, QueryDesc::plannedstmt, QueryDesc::planstate, ExplainState::printed_subplans, ps, ExplainState::pstmt, PlannedStmt::queryId, ExplainState::rtable, PlannedStmt::rtable, ExplainState::rtable_names, select_rtable_names_for_explain(), and ExplainState::verbose.

Referenced by explain_ExecutorEnd(), and ExplainOnePlan().

ExplainPrintTriggers()

void ExplainPrintTriggers	(	ExplainState *	es,
		QueryDesc *	queryDesc
	)

Definition at line 817 of file explain.c.

{
    ResultRelInfo *rInfo;
    bool        show_relname;
    List       *resultrels;
    List       *routerels;
    List       *targrels;
    ListCell   *l;
 
    resultrels = queryDesc->estate->es_opened_result_relations;
    routerels = queryDesc->estate->es_tuple_routing_result_relations;
    targrels = queryDesc->estate->es_trig_target_relations;
 
    ExplainOpenGroup("Triggers", "Triggers", false, es);
 
    show_relname = (list_length(resultrels) > 1 ||
                    routerels != NIL || targrels != NIL);
    foreach(l, resultrels)
    {
        rInfo = (ResultRelInfo *) lfirst(l);
        report_triggers(rInfo, show_relname, es);
    }
 
    foreach(l, routerels)
    {
        rInfo = (ResultRelInfo *) lfirst(l);
        report_triggers(rInfo, show_relname, es);
    }
 
    foreach(l, targrels)
    {
        rInfo = (ResultRelInfo *) lfirst(l);
        report_triggers(rInfo, show_relname, es);
    }
 
    ExplainCloseGroup("Triggers", "Triggers", false, es);
}

References EState::es_opened_result_relations, EState::es_trig_target_relations, EState::es_tuple_routing_result_relations, QueryDesc::estate, ExplainCloseGroup(), ExplainOpenGroup(), lfirst, list_length(), NIL, and report_triggers().

Referenced by explain_ExecutorEnd(), and ExplainOnePlan().

ExplainPropertyBool()

void ExplainPropertyBool	(	const char *	qlabel,
		bool	value,
		ExplainState *	es
	)

Definition at line 4601 of file explain.c.

{
    ExplainProperty(qlabel, NULL, value ? "true" : "false", true, es);
}

References ExplainProperty(), and value.

Referenced by ExplainNode(), and ExplainPrintJIT().

ExplainPropertyFloat()

void ExplainPropertyFloat	(	const char *	qlabel,
		const char *	unit,
		double	value,
		int	ndigits,
		ExplainState *	es
	)

Definition at line 4587 of file explain.c.

{
    char       *buf;
 
    buf = psprintf("%.*f", ndigits, value);
    ExplainProperty(qlabel, unit, buf, true, es);
    pfree(buf);
}

References buf, ExplainProperty(), pfree(), psprintf(), and value.

Referenced by ExplainNode(), ExplainOnePlan(), ExplainPrintJIT(), report_triggers(), show_buffer_usage(), show_instrumentation_count(), and show_modifytable_info().

ExplainPropertyInteger()

void ExplainPropertyInteger	(	const char *	qlabel,
		const char *	unit,
		int64	value,
		ExplainState *	es
	)

Definition at line 4560 of file explain.c.

{
    char        buf[32];
 
    snprintf(buf, sizeof(buf), INT64_FORMAT, value);
    ExplainProperty(qlabel, unit, buf, true, es);
}

References buf, ExplainProperty(), INT64_FORMAT, snprintf, and value.

Referenced by ExplainMissingMembers(), ExplainNode(), ExplainOpenWorker(), ExplainPrintJIT(), ExplainPrintPlan(), fileExplainForeignScan(), postgresExplainForeignModify(), show_buffer_usage(), show_hash_info(), show_hashagg_info(), show_incremental_sort_group_info(), show_memoize_info(), show_sort_info(), show_tidbitmap_info(), and show_wal_usage().

ExplainPropertyList()

void ExplainPropertyList	(	const char *	qlabel,
		List *	data,
		ExplainState *	es
	)

Definition at line 4375 of file explain.c.

{
    ListCell   *lc;
    bool        first = true;
 
    switch (es->format)
    {
        case EXPLAIN_FORMAT_TEXT:
            ExplainIndentText(es);
            appendStringInfo(es->str, "%s: ", qlabel);
            foreach(lc, data)
            {
                if (!first)
                    appendStringInfoString(es->str, ", ");
                appendStringInfoString(es->str, (const char *) lfirst(lc));
                first = false;
            }
            appendStringInfoChar(es->str, '\n');
            break;
 
        case EXPLAIN_FORMAT_XML:
            ExplainXMLTag(qlabel, X_OPENING, es);
            foreach(lc, data)
            {
                char       *str;
 
                appendStringInfoSpaces(es->str, es->indent * 2 + 2);
                appendStringInfoString(es->str, "<Item>");
                str = escape_xml((const char *) lfirst(lc));
                appendStringInfoString(es->str, str);
                pfree(str);
                appendStringInfoString(es->str, "</Item>\n");
            }
            ExplainXMLTag(qlabel, X_CLOSING, es);
            break;
 
        case EXPLAIN_FORMAT_JSON:
            ExplainJSONLineEnding(es);
            appendStringInfoSpaces(es->str, es->indent * 2);
            escape_json(es->str, qlabel);
            appendStringInfoString(es->str, ": [");
            foreach(lc, data)
            {
                if (!first)
                    appendStringInfoString(es->str, ", ");
                escape_json(es->str, (const char *) lfirst(lc));
                first = false;
            }
            appendStringInfoChar(es->str, ']');
            break;
 
        case EXPLAIN_FORMAT_YAML:
            ExplainYAMLLineStarting(es);
            appendStringInfo(es->str, "%s: ", qlabel);
            foreach(lc, data)
            {
                appendStringInfoChar(es->str, '\n');
                appendStringInfoSpaces(es->str, es->indent * 2 + 2);
                appendStringInfoString(es->str, "- ");
                escape_yaml(es->str, (const char *) lfirst(lc));
            }
            break;
    }
}

References appendStringInfo(), appendStringInfoChar(), appendStringInfoSpaces(), appendStringInfoString(), data, escape_json(), escape_xml(), escape_yaml(), EXPLAIN_FORMAT_JSON, EXPLAIN_FORMAT_TEXT, EXPLAIN_FORMAT_XML, EXPLAIN_FORMAT_YAML, ExplainIndentText(), ExplainJSONLineEnding(), ExplainXMLTag(), ExplainYAMLLineStarting(), ExplainState::format, ExplainState::indent, lfirst, pfree(), generate_unaccent_rules::str, ExplainState::str, X_CLOSING, and X_OPENING.

Referenced by ExplainPropertyListNested(), show_eval_params(), show_incremental_sort_group_info(), show_modifytable_info(), show_plan_tlist(), show_sort_group_keys(), and show_tablesample().

ExplainPropertyListNested()

void ExplainPropertyListNested	(	const char *	qlabel,
		List *	data,
		ExplainState *	es
	)

Definition at line 4445 of file explain.c.

{
    ListCell   *lc;
    bool        first = true;
 
    switch (es->format)
    {
        case EXPLAIN_FORMAT_TEXT:
        case EXPLAIN_FORMAT_XML:
            ExplainPropertyList(qlabel, data, es);
            return;
 
        case EXPLAIN_FORMAT_JSON:
            ExplainJSONLineEnding(es);
            appendStringInfoSpaces(es->str, es->indent * 2);
            appendStringInfoChar(es->str, '[');
            foreach(lc, data)
            {
                if (!first)
                    appendStringInfoString(es->str, ", ");
                escape_json(es->str, (const char *) lfirst(lc));
                first = false;
            }
            appendStringInfoChar(es->str, ']');
            break;
 
        case EXPLAIN_FORMAT_YAML:
            ExplainYAMLLineStarting(es);
            appendStringInfoString(es->str, "- [");
            foreach(lc, data)
            {
                if (!first)
                    appendStringInfoString(es->str, ", ");
                escape_yaml(es->str, (const char *) lfirst(lc));
                first = false;
            }
            appendStringInfoChar(es->str, ']');
            break;
    }
}

References appendStringInfoChar(), appendStringInfoSpaces(), appendStringInfoString(), data, escape_json(), escape_yaml(), EXPLAIN_FORMAT_JSON, EXPLAIN_FORMAT_TEXT, EXPLAIN_FORMAT_XML, EXPLAIN_FORMAT_YAML, ExplainJSONLineEnding(), ExplainPropertyList(), ExplainYAMLLineStarting(), ExplainState::format, ExplainState::indent, lfirst, and ExplainState::str.

Referenced by show_grouping_set_keys().

ExplainPropertyText()

void ExplainPropertyText	(	const char *	qlabel,
		const char *	value,
		ExplainState *	es
	)

Definition at line 4551 of file explain.c.

{
    ExplainProperty(qlabel, NULL, value, false, es);
}

References ExplainProperty(), and value.

Referenced by ExplainIndexScanDetails(), ExplainNode(), ExplainPrintSettings(), ExplainQueryParameters(), ExplainQueryText(), ExplainTargetRel(), fileExplainForeignScan(), postgresExplainDirectModify(), postgresExplainForeignModify(), postgresExplainForeignScan(), report_triggers(), show_expression(), show_grouping_set_keys(), show_memoize_info(), show_modifytable_info(), show_sort_info(), and show_tablesample().

ExplainPropertyUInteger()

void ExplainPropertyUInteger	(	const char *	qlabel,
		const char *	unit,
		uint64	value,
		ExplainState *	es
	)

Definition at line 4573 of file explain.c.

{
    char        buf[32];
 
    snprintf(buf, sizeof(buf), UINT64_FORMAT, value);
    ExplainProperty(qlabel, unit, buf, true, es);
}

References buf, ExplainProperty(), snprintf, UINT64_FORMAT, and value.

Referenced by show_wal_usage().

ExplainQuery()

void ExplainQuery	(	ParseState *	pstate,
		ExplainStmt *	stmt,
		ParamListInfo	params,
		DestReceiver *	dest
	)

Definition at line 164 of file explain.c.

{
    ExplainState *es = NewExplainState();
    TupOutputState *tstate;
    JumbleState *jstate = NULL;
    Query      *query;
    List       *rewritten;
    ListCell   *lc;
    bool        timing_set = false;
    bool        summary_set = false;
 
    /* Parse options list. */
    foreach(lc, stmt->options)
    {
        DefElem    *opt = (DefElem *) lfirst(lc);
 
        if (strcmp(opt->defname, "analyze") == 0)
            es->analyze = defGetBoolean(opt);
        else if (strcmp(opt->defname, "verbose") == 0)
            es->verbose = defGetBoolean(opt);
        else if (strcmp(opt->defname, "costs") == 0)
            es->costs = defGetBoolean(opt);
        else if (strcmp(opt->defname, "buffers") == 0)
            es->buffers = defGetBoolean(opt);
        else if (strcmp(opt->defname, "wal") == 0)
            es->wal = defGetBoolean(opt);
        else if (strcmp(opt->defname, "settings") == 0)
            es->settings = defGetBoolean(opt);
        else if (strcmp(opt->defname, "generic_plan") == 0)
            es->generic = defGetBoolean(opt);
        else if (strcmp(opt->defname, "timing") == 0)
        {
            timing_set = true;
            es->timing = defGetBoolean(opt);
        }
        else if (strcmp(opt->defname, "summary") == 0)
        {
            summary_set = true;
            es->summary = defGetBoolean(opt);
        }
        else if (strcmp(opt->defname, "format") == 0)
        {
            char       *p = defGetString(opt);
 
            if (strcmp(p, "text") == 0)
                es->format = EXPLAIN_FORMAT_TEXT;
            else if (strcmp(p, "xml") == 0)
                es->format = EXPLAIN_FORMAT_XML;
            else if (strcmp(p, "json") == 0)
                es->format = EXPLAIN_FORMAT_JSON;
            else if (strcmp(p, "yaml") == 0)
                es->format = EXPLAIN_FORMAT_YAML;
            else
                ereport(ERROR,
                        (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                         errmsg("unrecognized value for EXPLAIN option \"%s\": \"%s\"",
                                opt->defname, p),
                         parser_errposition(pstate, opt->location)));
        }
        else
            ereport(ERROR,
                    (errcode(ERRCODE_SYNTAX_ERROR),
                     errmsg("unrecognized EXPLAIN option \"%s\"",
                            opt->defname),
                     parser_errposition(pstate, opt->location)));
    }
 
    /* check that WAL is used with EXPLAIN ANALYZE */
    if (es->wal && !es->analyze)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("EXPLAIN option WAL requires ANALYZE")));
 
    /* if the timing was not set explicitly, set default value */
    es->timing = (timing_set) ? es->timing : es->analyze;
 
    /* check that timing is used with EXPLAIN ANALYZE */
    if (es->timing && !es->analyze)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("EXPLAIN option TIMING requires ANALYZE")));
 
    /* check that GENERIC_PLAN is not used with EXPLAIN ANALYZE */
    if (es->generic && es->analyze)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("EXPLAIN options ANALYZE and GENERIC_PLAN cannot be used together")));
 
    /* if the summary was not set explicitly, set default value */
    es->summary = (summary_set) ? es->summary : es->analyze;
 
    query = castNode(Query, stmt->query);
    if (IsQueryIdEnabled())
        jstate = JumbleQuery(query, pstate->p_sourcetext);
 
    if (post_parse_analyze_hook)
        (*post_parse_analyze_hook) (pstate, query, jstate);
 
    /*
     * Parse analysis was done already, but we still have to run the rule
     * rewriter.  We do not do AcquireRewriteLocks: we assume the query either
     * came straight from the parser, or suitable locks were acquired by
     * plancache.c.
     */
    rewritten = QueryRewrite(castNode(Query, stmt->query));
 
    /* emit opening boilerplate */
    ExplainBeginOutput(es);
 
    if (rewritten == NIL)
    {
        /*
         * In the case of an INSTEAD NOTHING, tell at least that.  But in
         * non-text format, the output is delimited, so this isn't necessary.
         */
        if (es->format == EXPLAIN_FORMAT_TEXT)
            appendStringInfoString(es->str, "Query rewrites to nothing\n");
    }
    else
    {
        ListCell   *l;
 
        /* Explain every plan */
        foreach(l, rewritten)
        {
            ExplainOneQuery(lfirst_node(Query, l),
                            CURSOR_OPT_PARALLEL_OK, NULL, es,
                            pstate->p_sourcetext, params, pstate->p_queryEnv);
 
            /* Separate plans with an appropriate separator */
            if (lnext(rewritten, l) != NULL)
                ExplainSeparatePlans(es);
        }
    }
 
    /* emit closing boilerplate */
    ExplainEndOutput(es);
    Assert(es->indent == 0);
 
    /* output tuples */
    tstate = begin_tup_output_tupdesc(dest, ExplainResultDesc(stmt),
                                      &TTSOpsVirtual);
    if (es->format == EXPLAIN_FORMAT_TEXT)
        do_text_output_multiline(tstate, es->str->data);
    else
        do_text_output_oneline(tstate, es->str->data);
    end_tup_output(tstate);
 
    pfree(es->str->data);
}

References ExplainState::analyze, appendStringInfoString(), Assert(), begin_tup_output_tupdesc(), ExplainState::buffers, castNode, ExplainState::costs, CURSOR_OPT_PARALLEL_OK, StringInfoData::data, defGetBoolean(), defGetString(), DefElem::defname, generate_unaccent_rules::dest, do_text_output_multiline(), do_text_output_oneline, end_tup_output(), ereport, errcode(), errmsg(), ERROR, EXPLAIN_FORMAT_JSON, EXPLAIN_FORMAT_TEXT, EXPLAIN_FORMAT_XML, EXPLAIN_FORMAT_YAML, ExplainBeginOutput(), ExplainEndOutput(), ExplainOneQuery(), ExplainResultDesc(), ExplainSeparatePlans(), ExplainState::format, ExplainState::generic, if(), ExplainState::indent, IsQueryIdEnabled(), JumbleQuery(), lfirst, lfirst_node, lnext(), DefElem::location, NewExplainState(), NIL, ParseState::p_queryEnv, ParseState::p_sourcetext, parser_errposition(), pfree(), post_parse_analyze_hook, QueryRewrite(), ExplainState::settings, stmt, ExplainState::str, ExplainState::summary, ExplainState::timing, TTSOpsVirtual, ExplainState::verbose, and ExplainState::wal.

Referenced by standard_ProcessUtility().

ExplainQueryParameters()

void ExplainQueryParameters	(	ExplainState *	es,
		ParamListInfo	params,
		int	maxlen
	)

Definition at line 995 of file explain.c.

{
    char       *str;
 
    /* This check is consistent with errdetail_params() */
    if (params == NULL || params->numParams <= 0 || maxlen == 0)
        return;
 
    str = BuildParamLogString(params, NULL, maxlen);
    if (str && str[0] != '\0')
        ExplainPropertyText("Query Parameters", str, es);
}

References BuildParamLogString(), ExplainPropertyText(), ParamListInfoData::numParams, and generate_unaccent_rules::str.

Referenced by explain_ExecutorEnd().

ExplainQueryText()

void ExplainQueryText	(	ExplainState *	es,
		QueryDesc *	queryDesc
	)

Definition at line 980 of file explain.c.

{
    if (queryDesc->sourceText)
        ExplainPropertyText("Query Text", queryDesc->sourceText, es);
}

References ExplainPropertyText(), and QueryDesc::sourceText.

Referenced by explain_ExecutorEnd().

ExplainResultDesc()

TupleDesc ExplainResultDesc

(

ExplainStmt *

stmt

)

Definition at line 337 of file explain.c.

{
    TupleDesc   tupdesc;
    ListCell   *lc;
    Oid         result_type = TEXTOID;
 
    /* Check for XML format option */
    foreach(lc, stmt->options)
    {
        DefElem    *opt = (DefElem *) lfirst(lc);
 
        if (strcmp(opt->defname, "format") == 0)
        {
            char       *p = defGetString(opt);
 
            if (strcmp(p, "xml") == 0)
                result_type = XMLOID;
            else if (strcmp(p, "json") == 0)
                result_type = JSONOID;
            else
                result_type = TEXTOID;
            /* don't "break", as ExplainQuery will use the last value */
        }
    }
 
    /* Need a tuple descriptor representing a single TEXT or XML column */
    tupdesc = CreateTemplateTupleDesc(1);
    TupleDescInitEntry(tupdesc, (AttrNumber) 1, "QUERY PLAN",
                       result_type, -1, 0);
    return tupdesc;
}

References CreateTemplateTupleDesc(), defGetString(), DefElem::defname, lfirst, stmt, and TupleDescInitEntry().

Referenced by ExplainQuery(), and UtilityTupleDescriptor().

ExplainSeparatePlans()

void ExplainSeparatePlans

(

ExplainState *

es

)

Definition at line 4932 of file explain.c.

{
    switch (es->format)
    {
        case EXPLAIN_FORMAT_TEXT:
            /* add a blank line */
            appendStringInfoChar(es->str, '\n');
            break;
 
        case EXPLAIN_FORMAT_XML:
        case EXPLAIN_FORMAT_JSON:
        case EXPLAIN_FORMAT_YAML:
            /* nothing to do */
            break;
    }
}

References appendStringInfoChar(), EXPLAIN_FORMAT_JSON, EXPLAIN_FORMAT_TEXT, EXPLAIN_FORMAT_XML, EXPLAIN_FORMAT_YAML, ExplainState::format, and ExplainState::str.

Referenced by ExplainExecuteQuery(), and ExplainQuery().

NewExplainState()

ExplainState* NewExplainState

(

void

)

Definition at line 320 of file explain.c.

{
    ExplainState *es = (ExplainState *) palloc0(sizeof(ExplainState));
 
    /* Set default options (most fields can be left as zeroes). */
    es->costs = true;
    /* Prepare output buffer. */
    es->str = makeStringInfo();
 
    return es;
}

References ExplainState::costs, makeStringInfo(), palloc0(), and ExplainState::str.

Referenced by explain_ExecutorEnd(), and ExplainQuery().

Variable Documentation

explain_get_index_name_hook

PGDLLIMPORT explain_get_index_name_hook_type explain_get_index_name_hook

extern

Definition at line 48 of file explain.c.

Referenced by explain_get_index_name().

ExplainOneQuery_hook

PGDLLIMPORT ExplainOneQuery_hook_type ExplainOneQuery_hook

extern

Definition at line 45 of file explain.c.

Referenced by ExplainOneQuery().