1 /*-------------------------------------------------------------------------
4 * definitions for query plan nodes
7 * Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
10 * $PostgreSQL: pgsql/src/include/nodes/plannodes.h,v 1.113 2009/10/26 02:26:42 tgl Exp $
12 *-------------------------------------------------------------------------
17 #include "access/sdir.h"
18 #include "nodes/bitmapset.h"
19 #include "nodes/primnodes.h"
20 #include "storage/itemptr.h"
23 /* ----------------------------------------------------------------
25 * ----------------------------------------------------------------
31 * The output of the planner is a Plan tree headed by a PlannedStmt node.
32 * PlannedStmt holds the "one time" information needed by the executor.
35 typedef struct PlannedStmt
39 CmdType commandType; /* select|insert|update|delete */
41 bool hasReturning; /* is it insert|update|delete RETURNING? */
43 bool canSetTag; /* do I set the command result tag? */
45 bool transientPlan; /* redo plan when TransactionXmin changes? */
47 struct Plan *planTree; /* tree of Plan nodes */
49 List *rtable; /* list of RangeTblEntry nodes */
51 /* rtable indexes of target relations for INSERT/UPDATE/DELETE */
52 List *resultRelations; /* integer list of RT indexes, or NIL */
54 Node *utilityStmt; /* non-null if this is DECLARE CURSOR */
56 IntoClause *intoClause; /* target for SELECT INTO / CREATE TABLE AS */
58 List *subplans; /* Plan trees for SubPlan expressions */
60 Bitmapset *rewindPlanIDs; /* indices of subplans that require REWIND */
62 List *rowMarks; /* a list of PlanRowMark's */
64 List *relationOids; /* OIDs of relations the plan depends on */
66 List *invalItems; /* other dependencies, as PlanInvalItems */
68 int nParamExec; /* number of PARAM_EXEC Params used */
71 /* macro for fetching the Plan associated with a SubPlan node */
72 #define exec_subplan_get_plan(plannedstmt, subplan) \
73 ((Plan *) list_nth((plannedstmt)->subplans, (subplan)->plan_id - 1))
79 * All plan nodes "derive" from the Plan structure by having the
80 * Plan structure as the first field. This ensures that everything works
81 * when nodes are cast to Plan's. (node pointers are frequently cast to Plan*
82 * when passed around generically in the executor)
84 * We never actually instantiate any Plan nodes; this is just the common
85 * abstract superclass for all Plan-type nodes.
93 * estimated execution costs for plan (see costsize.c for more info)
95 Cost startup_cost; /* cost expended before fetching any tuples */
96 Cost total_cost; /* total cost (assuming all tuples fetched) */
99 * planner's estimate of result size of this plan step
101 double plan_rows; /* number of rows plan is expected to emit */
102 int plan_width; /* average row width in bytes */
105 * Common structural data for all Plan types.
107 List *targetlist; /* target list to be computed at this node */
108 List *qual; /* implicitly-ANDed qual conditions */
109 struct Plan *lefttree; /* input plan tree(s) */
110 struct Plan *righttree;
111 List *initPlan; /* Init Plan nodes (un-correlated expr
115 * Information for management of parameter-change-driven rescanning
117 * extParam includes the paramIDs of all external PARAM_EXEC params
118 * affecting this plan node or its children. setParam params from the
119 * node's initPlans are not included, but their extParams are.
121 * allParam includes all the extParam paramIDs, plus the IDs of local
122 * params that affect the node (i.e., the setParams of its initplans).
123 * These are _all_ the PARAM_EXEC params that affect this node.
130 * these are are defined to avoid confusion problems with "left"
131 * and "right" and "inner" and "outer". The convention is that
132 * the "left" plan is the "outer" plan and the "right" plan is
133 * the inner plan, but these make the code more readable.
136 #define innerPlan(node) (((Plan *)(node))->righttree)
137 #define outerPlan(node) (((Plan *)(node))->lefttree)
142 * If no outer plan, evaluate a variable-free targetlist.
143 * If outer plan, return tuples from outer plan (after a level of
144 * projection as shown by targetlist).
146 * If resconstantqual isn't NULL, it represents a one-time qualification
147 * test (i.e., one that doesn't depend on any variables from the outer plan,
148 * so needs to be evaluated only once).
151 typedef struct Result
154 Node *resconstantqual;
159 * Apply rows produced by subplan(s) to result table(s),
160 * by inserting, updating, or deleting.
163 typedef struct ModifyTable
166 CmdType operation; /* INSERT, UPDATE, or DELETE */
167 List *resultRelations; /* integer list of RT indexes */
168 List *plans; /* plan(s) producing source data */
169 List *returningLists; /* per-target-table RETURNING tlists */
170 List *rowMarks; /* PlanRowMarks (non-locking only) */
171 int epqParam; /* ID of Param for EvalPlanQual re-eval */
176 * Generate the concatenation of the results of sub-plans.
179 typedef struct Append
186 * RecursiveUnion node -
187 * Generate a recursive union of two subplans.
189 * The "outer" subplan is always the non-recursive term, and the "inner"
190 * subplan is the recursive term.
193 typedef struct RecursiveUnion
196 int wtParam; /* ID of Param representing work table */
197 /* Remaining fields are zero/null in UNION ALL case */
198 int numCols; /* number of columns to check for
200 AttrNumber *dupColIdx; /* their indexes in the target list */
201 Oid *dupOperators; /* equality operators to compare with */
202 long numGroups; /* estimated number of groups in input */
207 * Generate the intersection of the results of sub-plans.
209 * The subplans must be of types that yield tuple bitmaps. The targetlist
210 * and qual fields of the plan are unused and are always NIL.
213 typedef struct BitmapAnd
221 * Generate the union of the results of sub-plans.
223 * The subplans must be of types that yield tuple bitmaps. The targetlist
224 * and qual fields of the plan are unused and are always NIL.
227 typedef struct BitmapOr
241 Index scanrelid; /* relid is index into the range table */
245 * sequential scan node
248 typedef Scan SeqScan;
253 * indexqualorig is an implicitly-ANDed list of index qual expressions, each
254 * in the same form it appeared in the query WHERE condition. Each should
255 * be of the form (indexkey OP comparisonval) or (comparisonval OP indexkey).
256 * The indexkey is a Var or expression referencing column(s) of the index's
257 * base table. The comparisonval might be any expression, but it won't use
258 * any columns of the base table.
260 * indexqual has the same form, but the expressions have been commuted if
261 * necessary to put the indexkeys on the left, and the indexkeys are replaced
262 * by Var nodes identifying the index columns (varattno is the index column
263 * position, not the base table's column, even though varno is for the base
264 * table). This is a bit hokey ... would be cleaner to use a special-purpose
265 * node type that could not be mistaken for a regular Var. But it will do
269 typedef struct IndexScan
272 Oid indexid; /* OID of index to scan */
273 List *indexqual; /* list of index quals (OpExprs) */
274 List *indexqualorig; /* the same in original form */
275 ScanDirection indexorderdir; /* forward or backward or don't care */
279 * bitmap index scan node
281 * BitmapIndexScan delivers a bitmap of potential tuple locations;
282 * it does not access the heap itself. The bitmap is used by an
283 * ancestor BitmapHeapScan node, possibly after passing through
284 * intermediate BitmapAnd and/or BitmapOr nodes to combine it with
285 * the results of other BitmapIndexScans.
287 * The fields have the same meanings as for IndexScan, except we don't
288 * store a direction flag because direction is uninteresting.
290 * In a BitmapIndexScan plan node, the targetlist and qual fields are
291 * not used and are always NIL. The indexqualorig field is unused at
292 * run time too, but is saved for the benefit of EXPLAIN.
295 typedef struct BitmapIndexScan
298 Oid indexid; /* OID of index to scan */
299 List *indexqual; /* list of index quals (OpExprs) */
300 List *indexqualorig; /* the same in original form */
304 * bitmap sequential scan node
306 * This needs a copy of the qual conditions being used by the input index
307 * scans because there are various cases where we need to recheck the quals;
308 * for example, when the bitmap is lossy about the specific rows on a page
309 * that meet the index condition.
312 typedef struct BitmapHeapScan
315 List *bitmapqualorig; /* index quals, in standard expr form */
321 * tidquals is an implicitly OR'ed list of qual expressions of the form
322 * "CTID = pseudoconstant" or "CTID = ANY(pseudoconstant_array)".
325 typedef struct TidScan
328 List *tidquals; /* qual(s) involving CTID = something */
334 * SubqueryScan is for scanning the output of a sub-query in the range table.
335 * We often need an extra plan node above the sub-query's plan to perform
336 * expression evaluations (which we can't push into the sub-query without
337 * risking changing its semantics). Although we are not scanning a physical
338 * relation, we make this a descendant of Scan anyway for code-sharing
341 * Note: we store the sub-plan in the type-specific subplan field, not in
342 * the generic lefttree field as you might expect. This is because we do
343 * not want plan-tree-traversal routines to recurse into the subplan without
344 * knowing that they are changing Query contexts.
346 * Note: subrtable is used just to carry the subquery rangetable from
347 * createplan.c to setrefs.c; it should always be NIL by the time the
348 * executor sees the plan. Similarly for subrowmark.
351 typedef struct SubqueryScan
355 List *subrtable; /* temporary workspace for planner */
356 List *subrowmark; /* temporary workspace for planner */
363 typedef struct FunctionScan
366 Node *funcexpr; /* expression tree for func call */
367 List *funccolnames; /* output column names (string Value nodes) */
368 List *funccoltypes; /* OID list of column type OIDs */
369 List *funccoltypmods; /* integer list of column typmods */
376 typedef struct ValuesScan
379 List *values_lists; /* list of expression lists */
386 typedef struct CteScan
389 int ctePlanId; /* ID of init SubPlan for CTE */
390 int cteParam; /* ID of Param representing CTE output */
397 typedef struct WorkTableScan
400 int wtParam; /* ID of Param representing work table */
413 * jointype: rule for joining tuples from left and right subtrees
414 * joinqual: qual conditions that came from JOIN/ON or JOIN/USING
415 * (plan.qual contains conditions that came from WHERE)
417 * When jointype is INNER, joinqual and plan.qual are semantically
418 * interchangeable. For OUTER jointypes, the two are *not* interchangeable;
419 * only joinqual is used to determine whether a match has been found for
420 * the purpose of deciding whether to generate null-extended tuples.
421 * (But plan.qual is still applied before actually returning a tuple.)
422 * For an outer join, only joinquals are allowed to be used as the merge
423 * or hash condition of a merge or hash join.
430 List *joinqual; /* JOIN quals (in addition to plan.qual) */
434 * nest loop join node
437 typedef struct NestLoop
445 * The expected ordering of each mergeable column is described by a btree
446 * opfamily OID, a direction (BTLessStrategyNumber or BTGreaterStrategyNumber)
447 * and a nulls-first flag. Note that the two sides of each mergeclause may
448 * be of different datatypes, but they are ordered the same way according to
449 * the common opfamily. The operator in each mergeclause must be an equality
450 * operator of the indicated opfamily.
453 typedef struct MergeJoin
456 List *mergeclauses; /* mergeclauses as expression trees */
457 /* these are arrays, but have the same length as the mergeclauses list: */
458 Oid *mergeFamilies; /* per-clause OIDs of btree opfamilies */
459 int *mergeStrategies; /* per-clause ordering (ASC or DESC) */
460 bool *mergeNullsFirst; /* per-clause nulls ordering */
467 typedef struct HashJoin
474 * materialization node
477 typedef struct Material
489 int numCols; /* number of sort-key columns */
490 AttrNumber *sortColIdx; /* their indexes in the target list */
491 Oid *sortOperators; /* OIDs of operators to sort them by */
492 bool *nullsFirst; /* NULLS FIRST/LAST directions */
497 * Used for queries with GROUP BY (but no aggregates) specified.
498 * The input must be presorted according to the grouping columns.
504 int numCols; /* number of grouping columns */
505 AttrNumber *grpColIdx; /* their indexes in the target list */
506 Oid *grpOperators; /* equality operators to compare with */
512 * An Agg node implements plain or grouped aggregation. For grouped
513 * aggregation, we can work with presorted input or unsorted input;
514 * the latter strategy uses an internal hashtable.
516 * Notice the lack of any direct info about the aggregate functions to be
517 * computed. They are found by scanning the node's tlist and quals during
518 * executor startup. (It is possible that there are no aggregate functions;
519 * this could happen if they get optimized away by constant-folding, or if
520 * we are using the Agg node to implement hash-based grouping.)
523 typedef enum AggStrategy
525 AGG_PLAIN, /* simple agg across all input rows */
526 AGG_SORTED, /* grouped agg, input must be sorted */
527 AGG_HASHED /* grouped agg, use internal hashtable */
533 AggStrategy aggstrategy;
534 int numCols; /* number of grouping columns */
535 AttrNumber *grpColIdx; /* their indexes in the target list */
536 Oid *grpOperators; /* equality operators to compare with */
537 long numGroups; /* estimated number of groups in input */
541 * window aggregate node
544 typedef struct WindowAgg
547 Index winref; /* ID referenced by window functions */
548 int partNumCols; /* number of columns in partition clause */
549 AttrNumber *partColIdx; /* their indexes in the target list */
550 Oid *partOperators; /* equality operators for partition columns */
551 int ordNumCols; /* number of columns in ordering clause */
552 AttrNumber *ordColIdx; /* their indexes in the target list */
553 Oid *ordOperators; /* equality operators for ordering columns */
554 int frameOptions; /* frame_clause options, see WindowDef */
561 typedef struct Unique
564 int numCols; /* number of columns to check for uniqueness */
565 AttrNumber *uniqColIdx; /* their indexes in the target list */
566 Oid *uniqOperators; /* equality operators to compare with */
572 * If the executor is supposed to try to apply skew join optimization, then
573 * skewTable/skewColumn identify the outer relation's join key column, from
574 * which the relevant MCV statistics can be fetched. Also, its type
575 * information is provided to save a lookup.
581 Oid skewTable; /* outer join key's table OID, or InvalidOid */
582 AttrNumber skewColumn; /* outer join key's column #, or zero */
583 Oid skewColType; /* datatype of the outer key column */
584 int32 skewColTypmod; /* typmod of the outer key column */
585 /* all other info is in the parent HashJoin node */
592 typedef enum SetOpCmd
595 SETOPCMD_INTERSECT_ALL,
600 typedef enum SetOpStrategy
602 SETOP_SORTED, /* input must be sorted */
603 SETOP_HASHED /* use internal hashtable */
609 SetOpCmd cmd; /* what to do */
610 SetOpStrategy strategy; /* how to do it */
611 int numCols; /* number of columns to check for
613 AttrNumber *dupColIdx; /* their indexes in the target list */
614 Oid *dupOperators; /* equality operators to compare with */
615 AttrNumber flagColIdx; /* where is the flag column, if any */
616 int firstFlag; /* flag value for first input relation */
617 long numGroups; /* estimated number of groups in input */
623 * rowMarks identifies the rels to be locked by this node; it should be
624 * a subset of the rowMarks listed in the top-level PlannedStmt.
625 * epqParam is a Param that all scan nodes below this one must depend on.
626 * It is used to force re-evaluation of the plan during EvalPlanQual.
629 typedef struct LockRows
632 List *rowMarks; /* a list of PlanRowMark's */
633 int epqParam; /* ID of Param for EvalPlanQual re-eval */
639 * Note: as of Postgres 8.2, the offset and count expressions are expected
640 * to yield int8, rather than int4 as before.
646 Node *limitOffset; /* OFFSET parameter, or NULL if none */
647 Node *limitCount; /* COUNT parameter, or NULL if none */
653 * enums for types of row-marking operations
655 * When doing UPDATE, DELETE, or SELECT FOR UPDATE/SHARE, we have to uniquely
656 * identify all the source rows, not only those from the target relations, so
657 * that we can perform EvalPlanQual rechecking at need. For plain tables we
658 * can just fetch the TID, the same as for a target relation. Otherwise (for
659 * example for VALUES or FUNCTION scans) we have to copy the whole row value.
660 * The latter is pretty inefficient but fortunately the case is not
661 * performance-critical in practice.
663 typedef enum RowMarkType
665 ROW_MARK_EXCLUSIVE, /* obtain exclusive tuple lock */
666 ROW_MARK_SHARE, /* obtain shared tuple lock */
667 ROW_MARK_REFERENCE, /* just fetch the TID */
668 ROW_MARK_COPY /* physically copy the row value */
671 #define RowMarkRequiresRowShareLock(marktype) ((marktype) <= ROW_MARK_SHARE)
675 * plan-time representation of FOR UPDATE/SHARE clauses
677 * When doing UPDATE, DELETE, or SELECT FOR UPDATE/SHARE, we create a separate
678 * PlanRowMark node for each non-target relation in the query. Relations that
679 * are not specified as FOR UPDATE/SHARE are marked ROW_MARK_REFERENCE (if
680 * real tables) or ROW_MARK_COPY (if not).
682 * Initially all PlanRowMarks have rti == prti and isParent == false.
683 * When the planner discovers that a relation is the root of an inheritance
684 * tree, it sets isParent true, and adds an additional PlanRowMark to the
685 * list for each child relation (including the target rel itself in its role
686 * as a child). The child entries have rti == child rel's RT index and
687 * prti == parent's RT index, and can therefore be recognized as children by
688 * the fact that prti != rti.
690 * The AttrNumbers are filled in during preprocess_targetlist. We use
691 * different subsets of them for plain relations, inheritance children,
692 * and non-table relations.
694 typedef struct PlanRowMark
697 Index rti; /* range table index of markable relation */
698 Index prti; /* range table index of parent relation */
699 RowMarkType markType; /* see enum above */
700 bool noWait; /* NOWAIT option */
701 bool isParent; /* true if this is a "dummy" parent entry */
702 AttrNumber ctidAttNo; /* resno of ctid junk attribute, if any */
703 AttrNumber toidAttNo; /* resno of tableoid junk attribute, if any */
704 AttrNumber wholeAttNo; /* resno of whole-row junk attribute, if any */
709 * Plan invalidation info
711 * We track the objects on which a PlannedStmt depends in two ways:
712 * relations are recorded as a simple list of OIDs, and everything else
713 * is represented as a list of PlanInvalItems. A PlanInvalItem is designed
714 * to be used with the syscache invalidation mechanism, so it identifies a
715 * system catalog entry by cache ID and tuple TID.
717 typedef struct PlanInvalItem
720 int cacheId; /* a syscache ID, see utils/syscache.h */
721 ItemPointerData tupleId; /* TID of the object's catalog tuple */
724 #endif /* PLANNODES_H */