src/include/nodes/plannodes.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * plannodes.h
   4  *        definitions for query plan nodes
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * $Id: plannodes.h,v 1.52 2001/10/28 06:26:07 momjian Exp $
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef PLANNODES_H
  15 #define PLANNODES_H
  16
  17 #include "nodes/execnodes.h"
  18
  19 /* ----------------------------------------------------------------
  20  *      Executor State types are used in the plannode structures
  21  *      so we have to include their definitions too.
  22  *
  23  *              Node Type                               node information used by executor
  24  *
  25  * control nodes
  26  *
  27  *              Result                                  ResultState                             resstate;
  28  *              Append                                  AppendState                             appendstate;
  29  *
  30  * scan nodes
  31  *
  32  *              Scan ***                                CommonScanState                 scanstate;
  33  *              IndexScan                               IndexScanState                  indxstate;
  34  *              SubqueryScan                    SubqueryScanState               subquerystate;
  35  *
  36  *                (*** nodes which inherit Scan also inherit scanstate)
  37  *
  38  * join nodes
  39  *
  40  *              NestLoop                                NestLoopState                   nlstate;
  41  *              MergeJoin                               MergeJoinState                  mergestate;
  42  *              HashJoin                                HashJoinState                   hashjoinstate;
  43  *
  44  * materialize nodes
  45  *
  46  *              Material                                MaterialState                   matstate;
  47  *              Sort                                    SortState                               sortstate;
  48  *              Unique                                  UniqueState                             uniquestate;
  49  *              SetOp                                   SetOpState                              setopstate;
  50  *              Limit                                   LimitState                              limitstate;
  51  *              Hash                                    HashState                               hashstate;
  52  *
  53  * ----------------------------------------------------------------
  54  */
  55
  56
  57 /* ----------------------------------------------------------------
  58  *                                              node definitions
  59  * ----------------------------------------------------------------
  60  */
  61
  62 /* ----------------
  63  *              Plan node
  64  * ----------------
  65  */
  66
  67 typedef struct Plan
  68 {
  69         NodeTag         type;
  70
  71         /* estimated execution costs for plan (see costsize.c for more info) */
  72         Cost            startup_cost;   /* cost expended before fetching any
  73                                                                  * tuples */
  74         Cost            total_cost;             /* total cost (assuming all tuples
  75                                                                  * fetched) */
  76
  77         /*
  78          * planner's estimate of result size (note: LIMIT, if any, is not
  79          * considered in setting plan_rows)
  80          */
  81         double          plan_rows;              /* number of rows plan is expected to emit */
  82         int                     plan_width;             /* average row width in bytes */
  83
  84         /*
  85          * execution state data.  Having Plan point to this, rather than the
  86          * other way round, is 100% bogus.
  87          */
  88         EState     *state;                      /* at execution time, state's of
  89                                                                  * individual nodes point to one EState
  90                                                                  * for the whole top-level plan */
  91
  92         struct Instrumentation *instrument; /* Optional runtime stats for this
  93                                                                                  * plan node */
  94
  95         /*
  96          * Common structural data for all Plan types.  XXX chgParam is runtime
  97          * data and should be in the EState, not here.
  98          */
  99         List       *targetlist;
 100         List       *qual;                       /* implicitly-ANDed qual conditions */
 101         struct Plan *lefttree;
 102         struct Plan *righttree;
 103         List       *extParam;           /* indices of _all_ _external_ PARAM_EXEC
 104                                                                  * for this plan in global
 105                                                                  * es_param_exec_vals. Params from
 106                                                                  * setParam from initPlan-s are not
 107                                                                  * included, but their execParam-s are
 108                                                                  * here!!! */
 109         List       *locParam;           /* someones from setParam-s */
 110         List       *chgParam;           /* list of changed ones from the above */
 111         List       *initPlan;           /* Init Plan nodes (un-correlated expr
 112                                                                  * subselects) */
 113         List       *subPlan;            /* Other SubPlan nodes */
 114
 115         /*
 116          * We really need in some TopPlan node to store range table and
 117          * resultRelation from Query there and get rid of Query itself from
 118          * Executor. Some other stuff like below could be put there, too.
 119          */
 120         int                     nParamExec;             /* Number of them in entire query. This is
 121                                                                  * to get Executor know about how many
 122                                                                  * param_exec there are in query plan. */
 123 } Plan;
 124
 125 /* ----------------
 126  *      these are are defined to avoid confusion problems with "left"
 127  *      and "right" and "inner" and "outer".  The convention is that
 128  *      the "left" plan is the "outer" plan and the "right" plan is
 129  *      the inner plan, but these make the code more readable.
 130  * ----------------
 131  */
 132 #define innerPlan(node)                 (((Plan *)(node))->righttree)
 133 #define outerPlan(node)                 (((Plan *)(node))->lefttree)
 134
 135
 136 /*
 137  * ===============
 138  * Top-level nodes
 139  * ===============
 140  */
 141
 142 /* all plan nodes "derive" from the Plan structure by having the
 143    Plan structure as the first field.  This ensures that everything works
 144    when nodes are cast to Plan's.  (node pointers are frequently cast to Plan*
 145    when passed around generically in the executor */
 146
 147
 148 /* ----------------
 149  *       Result node -
 150  *              If no outer plan, evaluate a variable-free targetlist.
 151  *              If outer plan, return tuples from outer plan that satisfy
 152  *              given quals (we can also do a level of projection)
 153  * ----------------
 154  */
 155 typedef struct Result
 156 {
 157         Plan            plan;
 158         Node       *resconstantqual;
 159         ResultState *resstate;
 160 } Result;
 161
 162 /* ----------------
 163  *       Append node -
 164  *              Generate the concatenation of the results of sub-plans.
 165  *
 166  * Append nodes are sometimes used to switch between several result relations
 167  * (when the target of an UPDATE or DELETE is an inheritance set).      Such a
 168  * node will have isTarget true.  The Append executor is then responsible
 169  * for updating the executor state to point at the correct target relation
 170  * whenever it switches subplans.
 171  * ----------------
 172  */
 173 typedef struct Append
 174 {
 175         Plan            plan;
 176         List       *appendplans;
 177         bool            isTarget;
 178         AppendState *appendstate;
 179 } Append;
 180
 181 /*
 182  * ==========
 183  * Scan nodes
 184  * ==========
 185  */
 186 typedef struct Scan
 187 {
 188         Plan            plan;
 189         Index           scanrelid;              /* relid is index into the range table */
 190         CommonScanState *scanstate;
 191 } Scan;
 192
 193 /* ----------------
 194  *              sequential scan node
 195  * ----------------
 196  */
 197 typedef Scan SeqScan;
 198
 199 /* ----------------
 200  *              index scan node
 201  * ----------------
 202  */
 203 typedef struct IndexScan
 204 {
 205         Scan            scan;
 206         List       *indxid;
 207         List       *indxqual;
 208         List       *indxqualorig;
 209         ScanDirection indxorderdir;
 210         IndexScanState *indxstate;
 211 } IndexScan;
 212
 213 /* ----------------
 214  *                              tid scan node
 215  * ----------------
 216  */
 217 typedef struct TidScan
 218 {
 219         Scan            scan;
 220         bool            needRescan;
 221         List       *tideval;
 222         TidScanState *tidstate;
 223 } TidScan;
 224
 225 /* ----------------
 226  *              subquery scan node
 227  *
 228  * SubqueryScan is for scanning the output of a sub-query in the range table.
 229  * We need a special plan node above the sub-query's plan as a place to switch
 230  * execution contexts.  Although we are not scanning a physical relation,
 231  * we make this a descendant of Scan anyway for code-sharing purposes.
 232  *
 233  * Note: we store the sub-plan in the type-specific subplan field, not in
 234  * the generic lefttree field as you might expect.      This is because we do
 235  * not want plan-tree-traversal routines to recurse into the subplan without
 236  * knowing that they are changing Query contexts.
 237  * ----------------
 238  */
 239 typedef struct SubqueryScan
 240 {
 241         Scan            scan;
 242         Plan       *subplan;
 243 } SubqueryScan;
 244
 245 /*
 246  * ==========
 247  * Join nodes
 248  * ==========
 249  */
 250
 251 /* ----------------
 252  *              Join node
 253  *
 254  * jointype:    rule for joining tuples from left and right subtrees
 255  * joinqual:    qual conditions that came from JOIN/ON or JOIN/USING
 256  *                              (plan.qual contains conditions that came from WHERE)
 257  *
 258  * When jointype is INNER, joinqual and plan.qual are semantically
 259  * interchangeable.  For OUTER jointypes, the two are *not* interchangeable;
 260  * only joinqual is used to determine whether a match has been found for
 261  * the purpose of deciding whether to generate null-extended tuples.
 262  * (But plan.qual is still applied before actually returning a tuple.)
 263  * For an outer join, only joinquals are allowed to be used as the merge
 264  * or hash condition of a merge or hash join.
 265  * ----------------
 266  */
 267 typedef struct Join
 268 {
 269         Plan            plan;
 270         JoinType        jointype;
 271         List       *joinqual;           /* JOIN quals (in addition to plan.qual) */
 272 } Join;
 273
 274 /* ----------------
 275  *              nest loop join node
 276  * ----------------
 277  */
 278 typedef struct NestLoop
 279 {
 280         Join            join;
 281         NestLoopState *nlstate;
 282 } NestLoop;
 283
 284 /* ----------------
 285  *              merge join node
 286  * ----------------
 287  */
 288 typedef struct MergeJoin
 289 {
 290         Join            join;
 291         List       *mergeclauses;
 292         MergeJoinState *mergestate;
 293 } MergeJoin;
 294
 295 /* ----------------
 296  *              hash join (probe) node
 297  * ----------------
 298  */
 299 typedef struct HashJoin
 300 {
 301         Join            join;
 302         List       *hashclauses;
 303         Oid                     hashjoinop;
 304         HashJoinState *hashjoinstate;
 305 } HashJoin;
 306
 307 /* ---------------
 308  *              aggregate node
 309  * ---------------
 310  */
 311 typedef struct Agg
 312 {
 313         Plan            plan;
 314         AggState   *aggstate;
 315 } Agg;
 316
 317 /* ---------------
 318  *       group node -
 319  *              use for queries with GROUP BY specified.
 320  *
 321  *              If tuplePerGroup is true, one tuple (with group columns only) is
 322  *              returned for each group and NULL is returned when there are no more
 323  *              groups. Otherwise, all the tuples of a group are returned with a
 324  *              NULL returned at the end of each group. (see nodeGroup.c for details)
 325  * ---------------
 326  */
 327 typedef struct Group
 328 {
 329         Plan            plan;
 330         bool            tuplePerGroup;  /* what tuples to return (see above) */
 331         int                     numCols;                /* number of group columns */
 332         AttrNumber *grpColIdx;          /* indexes into the target list */
 333         GroupState *grpstate;
 334 } Group;
 335
 336 /* ----------------
 337  *              materialization node
 338  * ----------------
 339  */
 340 typedef struct Material
 341 {
 342         Plan            plan;
 343         MaterialState *matstate;
 344 } Material;
 345
 346 /* ----------------
 347  *              sort node
 348  * ----------------
 349  */
 350 typedef struct Sort
 351 {
 352         Plan            plan;
 353         int                     keycount;
 354         SortState  *sortstate;
 355 } Sort;
 356
 357 /* ----------------
 358  *              unique node
 359  * ----------------
 360  */
 361 typedef struct Unique
 362 {
 363         Plan            plan;
 364         int                     numCols;                /* number of columns to check for
 365                                                                  * uniqueness */
 366         AttrNumber *uniqColIdx;         /* indexes into the target list */
 367         UniqueState *uniquestate;
 368 } Unique;
 369
 370 /* ----------------
 371  *              setop node
 372  * ----------------
 373  */
 374 typedef enum SetOpCmd
 375 {
 376         SETOPCMD_INTERSECT,
 377         SETOPCMD_INTERSECT_ALL,
 378         SETOPCMD_EXCEPT,
 379         SETOPCMD_EXCEPT_ALL
 380 } SetOpCmd;
 381
 382 typedef struct SetOp
 383 {
 384         Plan            plan;
 385         SetOpCmd        cmd;                    /* what to do */
 386         int                     numCols;                /* number of columns to check for
 387                                                                  * duplicate-ness */
 388         AttrNumber *dupColIdx;          /* indexes into the target list */
 389         AttrNumber      flagColIdx;
 390         SetOpState *setopstate;
 391 } SetOp;
 392
 393 /* ----------------
 394  *              limit node
 395  * ----------------
 396  */
 397 typedef struct Limit
 398 {
 399         Plan            plan;
 400         Node       *limitOffset;        /* OFFSET parameter, or NULL if none */
 401         Node       *limitCount;         /* COUNT parameter, or NULL if none */
 402         LimitState *limitstate;
 403 } Limit;
 404
 405 /* ----------------
 406  *              hash build node
 407  * ----------------
 408  */
 409 typedef struct Hash
 410 {
 411         Plan            plan;
 412         Node       *hashkey;
 413         HashState  *hashstate;
 414 } Hash;
 415
 416 #ifdef NOT_USED
 417 /* -------------------
 418  *              Tee node information
 419  *
 420  *        leftParent :                          the left parent of this node
 421  *        rightParent:                          the right parent of this node
 422  * -------------------
 423 */
 424 typedef struct Tee
 425 {
 426         Plan            plan;
 427         Plan       *leftParent;
 428         Plan       *rightParent;
 429         TeeState   *teestate;
 430         char       *teeTableName;       /* the name of the table to materialize
 431                                                                  * the tee into */
 432         List       *rtentries;          /* the range table for the plan below the
 433                                                                  * Tee may be different than the parent
 434                                                                  * plans */
 435 }                       Tee;
 436 #endif
 437
 438 /* ---------------------
 439  *              SubPlan node
 440  * ---------------------
 441  */
 442 typedef struct SubPlan
 443 {
 444         NodeTag         type;
 445         Plan       *plan;                       /* subselect plan itself */
 446         int                     plan_id;                /* dummy thing because of we haven't equal
 447                                                                  * funcs for plan nodes... actually, we
 448                                                                  * could put *plan itself somewhere else
 449                                                                  * (TopPlan node ?)... */
 450         List       *rtable;                     /* range table for subselect */
 451         /* setParam and parParam are lists of integers (param IDs) */
 452         List       *setParam;           /* non-correlated EXPR & EXISTS subqueries
 453                                                                  * have to set some Params for paren Plan */
 454         List       *parParam;           /* indices of corr. Vars from parent plan */
 455         SubLink    *sublink;            /* SubLink node from parser; holds info
 456                                                                  * about what to do with subselect's
 457                                                                  * results */
 458
 459         /*
 460          * Remaining fields are working state for executor; not used in
 461          * planning
 462          */
 463         bool            needShutdown;   /* TRUE = need to shutdown subplan */
 464         HeapTuple       curTuple;               /* copy of most recent tuple from subplan */
 465 } SubPlan;
 466
 467 #endif   /* PLANNODES_H */