granicus.if.org Git - postgresql/blob - src/include/nodes/primnodes.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * primnodes.h
   4  *        Definitions for "primitive" node types, those that are used in more
   5  *        than one of the parse/plan/execute stages of the query pipeline.
   6  *        Currently, these are mostly nodes for executable expressions
   7  *        and join trees.
   8  *
   9  *
  10  * Portions Copyright (c) 1996-2000, PostgreSQL, Inc
  11  * Portions Copyright (c) 1994, Regents of the University of California
  12  *
  13  * $Id: primnodes.h,v 1.50 2001/01/17 06:41:31 momjian Exp $
  14  *
  15  *-------------------------------------------------------------------------
  16  */
  17 #ifndef PRIMNODES_H
  18 #define PRIMNODES_H
  19
  20 #include "access/attnum.h"
  21 #include "nodes/pg_list.h"
  22
  23 /* FunctionCache is declared in utils/fcache.h */
  24 typedef struct FunctionCache *FunctionCachePtr;
  25
  26
  27 /* ----------------------------------------------------------------
  28  *                                              node definitions
  29  * ----------------------------------------------------------------
  30  */
  31
  32 /*
  33  * Resdom (Result Domain)
  34  *
  35  * Notes:
  36  * ressortgroupref is the parse/plan-time representation of ORDER BY and
  37  * GROUP BY items.      Targetlist entries with ressortgroupref=0 are not
  38  * sort/group items.  If ressortgroupref>0, then this item is an ORDER BY or
  39  * GROUP BY value.      No two entries in a targetlist may have the same nonzero
  40  * ressortgroupref --- but there is no particular meaning to the nonzero
  41  * values, except as tags.      (For example, one must not assume that lower
  42  * ressortgroupref means a more significant sort key.)  The order of the
  43  * associated SortClause or GroupClause lists determine the semantics.
  44  *
  45  * reskey and reskeyop are the execution-time representation of sorting.
  46  * reskey must be zero in any non-sort-key item.  The reskey of sort key
  47  * targetlist items for a sort plan node is 1,2,...,n for the n sort keys.
  48  * The reskeyop of each such targetlist item is the sort operator's
  49  * regproc OID.  reskeyop will be zero in non-sort-key items.
  50  *
  51  * Both reskey and reskeyop are typically zero during parse/plan stages.
  52  * The executor does not pay any attention to ressortgroupref.
  53  *
  54  */
  55 typedef struct Resdom
  56 {
  57         NodeTag         type;
  58         AttrNumber      resno;          /* attribute number */
  59         Oid                     restype;        /* type of the value */
  60         int32           restypmod;      /* type-specific modifier of the value */
  61         char       *resname;    /* name of the resdom (could be NULL) */
  62         Index           ressortgroupref;
  63                                                         /* nonzero if referenced by a sort/group clause */
  64         Index           reskey;         /* order of key in a sort (for those > 0) */
  65         Oid                     reskeyop;       /* sort operator's regproc Oid */
  66         bool            resjunk;        /* set to true to eliminate the attribute
  67  *                                                     from final target list */
  68 } Resdom;
  69
  70 /*
  71  * Fjoin
  72  */
  73 typedef struct Fjoin
  74 {
  75         NodeTag         type;
  76         bool            fj_initialized; /* true if the Fjoin has already been
  77                                                                  * initialized for the current target
  78                                                                  * list evaluation */
  79         int                     fj_nNodes;              /* The number of Iter nodes returning
  80                                                                  * sets that the node will flatten */
  81         List       *fj_innerNode;       /* exactly one Iter node.  We eval every
  82                                                                  * node in the outerList once then eval
  83                                                                  * the inner node to completion pair the
  84                                                                  * outerList result vector with each inner
  85                                                                  * result to form the full result.  When
  86                                                                  * the inner has been exhausted, we get
  87                                                                  * the next outer result vector and reset
  88                                                                  * the inner.
  89                                                                  */
  90         DatumPtr        fj_results;             /* The complete (flattened) result vector */
  91         BoolPtr         fj_alwaysDone;  /* a null vector to indicate sets with a
  92                                                                  * cardinality of 0, we treat them as the
  93                                                                  * set {NULL}.
  94                                                                  */
  95 } Fjoin;
  96
  97
  98 /* ----------------------------------------------------------------
  99  *                                      node types for executable expressions
 100  * ----------------------------------------------------------------
 101  */
 102
 103 /*
 104  * Expr
 105  */
 106 typedef enum OpType
 107 {
 108         OP_EXPR, FUNC_EXPR, OR_EXPR, AND_EXPR, NOT_EXPR, SUBPLAN_EXPR
 109 } OpType;
 110
 111 typedef struct Expr
 112 {
 113         NodeTag         type;
 114         Oid                     typeOid;        /* oid of the type of this expression */
 115         OpType          opType;         /* type of this expression */
 116         Node       *oper;               /* operator node if needed (Oper, Func, or
 117                                                          * SubPlan) */
 118         List       *args;               /* arguments to this expression */
 119 } Expr;
 120
 121 /*
 122  * Var
 123  *
 124  * Note: during parsing/planning, varnoold/varoattno are always just copies
 125  * of varno/varattno.  At the tail end of planning, Var nodes appearing in
 126  * upper-level plan nodes are reassigned to point to the outputs of their
 127  * subplans; for example, in a join node varno becomes INNER or OUTER and
 128  * varattno becomes the index of the proper element of that subplan's target
 129  * list.  But varnoold/varoattno continue to hold the original values.
 130  * The code doesn't really need varnoold/varoattno, but they are very useful
 131  * for debugging and interpreting completed plans, so we keep them around.
 132  * ----------------
 133  */
 134 #define    INNER                65000
 135 #define    OUTER                65001
 136
 137 #define    PRS2_OLD_VARNO                       1
 138 #define    PRS2_NEW_VARNO                       2
 139
 140 typedef struct Var
 141 {
 142         NodeTag         type;
 143         Index           varno;          /* index of this var's relation in the range
 144                                                          * table (could also be INNER or OUTER) */
 145         AttrNumber      varattno;       /* attribute number of this var, or zero for all */
 146         Oid                     vartype;        /* pg_type tuple OID for the type of this var */
 147         int32           vartypmod;      /* pg_attribute typmod value */
 148         Index           varlevelsup;
 149                                                         /* for subquery variables referencing outer
 150                                                          * relations; 0 in a normal var, >0 means N
 151                                                          * levels up */
 152         Index           varnoold;       /* original value of varno, for debugging */
 153         AttrNumber      varoattno;      /* original value of varattno */
 154 } Var;
 155
 156 /*
 157  * Oper
 158  *
 159  * NOTE: in the good old days 'opno' used to be both (or either, or
 160  * neither) the pg_operator oid, and/or the pg_proc oid depending
 161  * on the postgres module in question (parser->pg_operator,
 162  * executor->pg_proc, planner->both), the mood of the programmer,
 163  * and the phase of the moon (rumors that it was also depending on the day
 164  * of the week are probably false). To make things even more postgres-like
 165  * (i.e. a mess) some comments were referring to 'opno' using the name
 166  * 'opid'. Anyway, now we have two separate fields, and of course that
 167  * immediately removes all bugs from the code...                [ sp :-) ].
 168  *
 169  * Note also that opid is not necessarily filled in immediately on creation
 170  * of the node.  The planner makes sure it is valid before passing the node
 171  * tree to the executor, but during parsing/planning opid is typically 0.
 172  *
 173  */
 174 typedef struct Oper
 175 {
 176         NodeTag         type;
 177         Oid                     opno;           /* PG_OPERATOR OID of the operator */
 178         Oid                     opid;           /* PG_PROC OID for the operator's underlying
 179                                                          * function */
 180         Oid                     opresulttype;
 181                                                         /* PG_TYPE OID of the operator's return value */
 182         FunctionCachePtr op_fcache;
 183                                                         /* runtime state while running the function */
 184 } Oper;
 185
 186
 187 /*
 188  * Const
 189  */
 190 typedef struct Const
 191 {
 192         NodeTag         type;
 193         Oid                     consttype;              /* PG_TYPE OID of the constant's value */
 194         int                     constlen;               /* length in bytes of the constant's value */
 195         Datum           constvalue;             /* the constant's value */
 196         bool            constisnull;    /* whether the constant is null (if true,
 197                                                                  * the other fields are undefined) */
 198         bool            constbyval;             /* whether the information in constvalue
 199                                                                  * if passed by value.  If true, then all
 200                                                                  * the information is stored in the datum.
 201                                                                  * If false, then the datum contains a pointer
 202                                                                  * to the information. */
 203         bool            constisset;             /* whether the const represents a set.
 204                                                                  * The const value corresponding will be the
 205                                                                  * query that defines the set. */
 206         bool            constiscast;
 207 } Const;
 208
 209 /* ----------------
 210  * Param
 211  *              paramkind - specifies the kind of parameter. The possible values
 212  *              for this field are specified in "params.h", and they are:
 213  *
 214  *              PARAM_NAMED: The parameter has a name, i.e. something
 215  *                              like `$.salary' or `$.foobar'.
 216  *                              In this case field `paramname' must be a valid Name.
 217  *
 218  *              PARAM_NUM:       The parameter has only a numeric identifier,
 219  *                              i.e. something like `$1', `$2' etc.
 220  *                              The number is contained in the `paramid' field.
 221  *
 222  *              PARAM_NEW:       Used in PRS2 rule, similar to PARAM_NAMED.
 223  *                                       The `paramname' and `paramid' refer to the "NEW" tuple
 224  *                                       The `pramname' is the attribute name and `paramid'
 225  *                                       is the attribute number.
 226  *
 227  *              PARAM_OLD:       Same as PARAM_NEW, but in this case we refer to
 228  *                              the "OLD" tuple.
 229  * ----------------
 230  */
 231 typedef struct Param
 232 {
 233         NodeTag         type;
 234         int                     paramkind;      /* specifies the kind of parameter.  See above */
 235         AttrNumber      paramid;        /* numeric identifier for literal-constant
 236                                                          * parameters ("$1") */
 237         char       *paramname;  /* attribute name for tuple-substitution
 238                                                          * parameters ("$.foo") */
 239         Oid                     paramtype;      /* PG_TYPE OID of the parameter's value */
 240 } Param;
 241
 242
 243 /*
 244  * Func
 245  */
 246 typedef struct Func
 247 {
 248         NodeTag         type;
 249         Oid                     funcid;         /* PG_PROC OID of the function */
 250         Oid                     functype;       /* PG_TYPE OID of the function's return value */
 251         FunctionCachePtr func_fcache;
 252                                                         /* runtime state while running this function.
 253                                                          * Where we are in the execution of the function
 254                                                          * if it returns more than one value, etc.
 255                                                          * See utils/fcache.h */
 256 } Func;
 257
 258 /* ----------------
 259  * Iter
 260  *              can anyone explain what this is for?  Seems to have something to do
 261  *              with evaluation of functions that return sets...
 262  * ----------------
 263  */
 264 typedef struct Iter
 265 {
 266         NodeTag         type;
 267         Node       *iterexpr;
 268         Oid                     itertype;               /* type of the iter expr (use for type
 269                                                                  * checking) */
 270 } Iter;
 271
 272 /*
 273  * Aggref
 274  */
 275 typedef struct Aggref
 276 {
 277         NodeTag         type;
 278         char       *aggname;    /* name of the aggregate */
 279         Oid                     basetype;       /* base type Oid of the aggregate
 280                                                          * (ie, input type) */
 281         Oid                     aggtype;        /* type Oid of final result of the aggregate */
 282         Node       *target;             /* attribute or expression we are aggregating on */
 283         bool            aggstar;        /* TRUE if argument was really '*' */
 284         bool            aggdistinct;/* TRUE if it's agg(DISTINCT ...) */
 285         int                     aggno;          /* workspace for executor (see nodeAgg.c) */
 286 } Aggref;
 287
 288 /* ----------------
 289  * SubLink
 290  *
 291  * A SubLink represents a subselect appearing in an expression, and in some
 292  * cases also the combining operator(s) just above it.  The subLinkType
 293  * indicates the form of the expression represented:
 294  *      EXISTS_SUBLINK          EXISTS(SELECT ...)
 295  *      ALL_SUBLINK                     (lefthand) op ALL (SELECT ...)
 296  *      ANY_SUBLINK                     (lefthand) op ANY (SELECT ...)
 297  *      MULTIEXPR_SUBLINK       (lefthand) op (SELECT ...)
 298  *      EXPR_SUBLINK            (SELECT with single targetlist item ...)
 299  * For ALL, ANY, and MULTIEXPR, the lefthand is a list of expressions of the
 300  * same length as the subselect's targetlist.  MULTIEXPR will *always* have
 301  * a list with more than one entry; if the subselect has just one target
 302  * then the parser will create an EXPR_SUBLINK instead (and any operator
 303  * above the subselect will be represented separately).  Note that both
 304  * MULTIEXPR and EXPR require the subselect to deliver only one row.
 305  * ALL, ANY, and MULTIEXPR require the combining operators to deliver boolean
 306  * results.  These are reduced to one result per row using OR or AND semantics
 307  * depending on the "useor" flag.  ALL and ANY combine the per-row results
 308  * using AND and OR semantics respectively.
 309  *
 310  * NOTE: lefthand and oper have varying meanings depending on where you look
 311  * in the parse/plan pipeline:
 312  * 1. gram.y delivers a list of the (untransformed) lefthand expressions in
 313  *        lefthand, and sets oper to a single A_Expr (not a list!) containing
 314  *        the string name of the operator, but no arguments.
 315  * 2. The parser's expression transformation transforms lefthand normally,
 316  *        and replaces oper with a list of Oper nodes, one per lefthand
 317  *        expression.  These nodes represent the parser's resolution of exactly
 318  *        which operator to apply to each pair of lefthand and targetlist
 319  *        expressions.  However, we have not constructed actual Expr trees for
 320  *        these operators yet.  This is the representation seen in saved rules
 321  *        and in the rewriter.
 322  * 3. Finally, the planner converts the oper list to a list of normal Expr
 323  *        nodes representing the application of the operator(s) to the lefthand
 324  *        expressions and values from the inner targetlist.  The inner
 325  *        targetlist items are represented by placeholder Param or Const nodes.
 326  *        The lefthand field is set to NIL, since its expressions are now in
 327  *        the Expr list.  This representation is passed to the executor.
 328  *
 329  * Planner routines that might see either representation 2 or 3 can tell
 330  * the difference by checking whether lefthand is NIL or not.  Also,
 331  * representation 2 appears in a "bare" SubLink, while representation 3 is
 332  * found in SubLinks that are children of SubPlan nodes.
 333  *
 334  * In EXISTS and EXPR SubLinks, both lefthand and oper are unused and are
 335  * always NIL.  useor is not significant either for these sublink types.
 336  * ----------------
 337  */
 338 typedef enum SubLinkType
 339 {
 340         EXISTS_SUBLINK, ALL_SUBLINK, ANY_SUBLINK, MULTIEXPR_SUBLINK, EXPR_SUBLINK
 341 } SubLinkType;
 342
 343
 344 typedef struct SubLink
 345 {
 346         NodeTag         type;
 347         SubLinkType subLinkType;/* EXISTS, ALL, ANY, MULTIEXPR, EXPR */
 348         bool            useor;          /* TRUE to combine column results with "OR"
 349                                                          * not "AND" */
 350         List       *lefthand;   /* list of outer-query expressions on the left */
 351         List       *oper;               /* list of Oper nodes for combining operators */
 352         Node       *subselect;  /* subselect as Query* or parsetree */
 353 } SubLink;
 354
 355 /* ----------------
 356  *      ArrayRef: describes an array subscripting operation
 357  *
 358  * An ArrayRef can describe fetching a single element from an array,
 359  * fetching a subarray (array slice), storing a single element into
 360  * an array, or storing a slice.  The "store" cases work with an
 361  * initial array value and a source value that is inserted into the
 362  * appropriate part of the array; the result of the operation is an
 363  * entire new modified array value.
 364  *
 365  * If reflowerindexpr = NIL, then we are fetching or storing a single array
 366  * element at the subscripts given by refupperindexpr.  Otherwise we are
 367  * fetching or storing an array slice, that is a rectangular subarray
 368  * with lower and upper bounds given by the index expressions.
 369  * reflowerindexpr must be the same length as refupperindexpr when it
 370  * is not NIL.
 371  *
 372  * Note: array types can be fixed-length (refattrlength > 0), but only
 373  * when the element type is itself fixed-length.  Otherwise they are
 374  * varlena structures and have refattrlength = -1.      In any case,
 375  * an array type is never pass-by-value.
 376  *
 377  * Note: currently, refelemtype is NOT the element type, but the array type,
 378  * when doing subarray fetch or either type of store.  It would be cleaner
 379  * to add more fields so we can distinguish the array element type from the
 380  * result type of the ArrayRef operator...
 381  * ----------------
 382  */
 383 typedef struct ArrayRef
 384 {
 385         NodeTag         type;
 386         int                     refattrlength;          /* typlen of array type */
 387         int                     refelemlength;          /* typlen of the array element type */
 388         Oid                     refelemtype;            /* type of the result of the ArrayRef
 389                                                                          * operation */
 390         bool            refelembyval;           /* is the element type pass-by-value? */
 391         List       *refupperindexpr;    /* expressions that evaluate to upper
 392                                                                          * array indexes */
 393         List       *reflowerindexpr;    /* expressions that evaluate to lower
 394                                                                          * array indexes */
 395         Node       *refexpr;                    /* the expression that evaluates to an
 396                                                                          * array value */
 397         Node       *refassgnexpr;               /* expression for the source value, or NULL
 398                                                                          * if fetch */
 399 } ArrayRef;
 400
 401 /* ----------------
 402  * FieldSelect
 403  *
 404  * FieldSelect represents the operation of extracting one field from a tuple
 405  * value.  At runtime, the input expression is expected to yield a Datum
 406  * that contains a pointer-to-TupleTableSlot.  The specified field number
 407  * is extracted and returned as a Datum.
 408  * ----------------
 409  */
 410
 411 typedef struct FieldSelect
 412 {
 413         NodeTag         type;
 414         Node       *arg;                        /* input expression */
 415         AttrNumber      fieldnum;               /* attribute number of field to extract */
 416         Oid                     resulttype;             /* type of the field (result type of this
 417                                                                  * node) */
 418         int32           resulttypmod;   /* output typmod (usually -1) */
 419 } FieldSelect;
 420
 421 /* ----------------
 422  * RelabelType
 423  *
 424  * RelabelType represents a "dummy" type coercion between two binary-
 425  * compatible datatypes, such as reinterpreting the result of an OID
 426  * expression as an int4.  It is a no-op at runtime; we only need it
 427  * to provide a place to store the correct type to be attributed to
 428  * the expression result during type resolution.  (We can't get away
 429  * with just overwriting the type field of the input expression node,
 430  * so we need a separate node to show the coercion's result type.)
 431  * ----------------
 432  */
 433
 434 typedef struct RelabelType
 435 {
 436         NodeTag         type;
 437         Node       *arg;                        /* input expression */
 438         Oid                     resulttype;             /* output type of coercion expression */
 439         int32           resulttypmod;   /* output typmod (usually -1) */
 440 } RelabelType;
 441
 442
 443 /* ----------------------------------------------------------------
 444  *                                      node types for join trees
 445  *
 446  * The leaves of a join tree structure are RangeTblRef nodes.  Above
 447  * these, JoinExpr nodes can appear to denote a specific kind of join
 448  * or qualified join.  Also, FromExpr nodes can appear to denote an
 449  * ordinary cross-product join ("FROM foo, bar, baz WHERE ...").
 450  * FromExpr is like a JoinExpr of jointype JOIN_INNER, except that it
 451  * may have any number of child nodes, not just two.  Also, there is an
 452  * implementation-defined difference: the planner is allowed to join the
 453  * children of a FromExpr using whatever join order seems good to it.
 454  * At present, JoinExpr nodes are always joined in exactly the order
 455  * implied by the jointree structure (except the planner may choose to
 456  * swap inner and outer members of a join pair).
 457  *
 458  * NOTE: the top level of a Query's jointree is always a FromExpr.
 459  * Even if the jointree contains no rels, there will be a FromExpr.
 460  *
 461  * NOTE: the qualification expressions present in JoinExpr nodes are
 462  * *in addition to* the query's main WHERE clause, which appears as the
 463  * qual of the top-level FromExpr.  The reason for associating quals with
 464  * specific nodes in the jointree is that the position of a qual is critical
 465  * when outer joins are present.  (If we enforce a qual too soon or too late,
 466  * that may cause the outer join to produce the wrong set of NULL-extended
 467  * rows.)  If all joins are inner joins then all the qual positions are
 468  * semantically interchangeable.
 469  *
 470  * NOTE: in the raw output of gram.y, a join tree contains RangeVar and
 471  * RangeSubselect nodes, which are both replaced by RangeTblRef nodes
 472  * during the parse analysis phase.  Also, the top-level FromExpr is added
 473  * during parse analysis; the grammar regards FROM and WHERE as separate.
 474  * ----------------------------------------------------------------
 475  */
 476
 477 /*
 478  * RangeTblRef - reference to an entry in the query's rangetable
 479  *
 480  * We could use direct pointers to the RT entries and skip having these
 481  * nodes, but multiple pointers to the same node in a querytree cause
 482  * lots of headaches, so it seems better to store an index into the RT.
 483  */
 484 typedef struct RangeTblRef
 485 {
 486         NodeTag         type;
 487         int                     rtindex;
 488 } RangeTblRef;
 489
 490 /*----------
 491  * JoinExpr - for SQL JOIN expressions
 492  *
 493  * isNatural, using, and quals are interdependent.  The user can write only
 494  * one of NATURAL, USING(), or ON() (this is enforced by the grammar).
 495  * If he writes NATURAL then parse analysis generates the equivalent USING()
 496  * list, and from that fills in "quals" with the right equality comparisons.
 497  * If he writes USING() then "quals" is filled with equality comparisons.
 498  * If he writes ON() then only "quals" is set.  Note that NATURAL/USING
 499  * are not equivalent to ON() since they also affect the output column list.
 500  *
 501  * alias is an Attr node representing the AS alias-clause attached to the
 502  * join expression, or NULL if no clause.  During parse analysis, colnames
 503  * is filled with a list of String nodes giving the column names (real or
 504  * alias) of the output of the join, and colvars is filled with a list of
 505  * expressions that can be copied to reference the output columns.
 506  *----------
 507  */
 508 typedef struct JoinExpr
 509 {
 510         NodeTag         type;
 511         JoinType        jointype;               /* type of join */
 512         bool            isNatural;              /* Natural join? Will need to shape table */
 513         Node       *larg;                       /* left subtree */
 514         Node       *rarg;                       /* right subtree */
 515         List       *using;                      /* USING clause, if any (list of String) */
 516         Node       *quals;                      /* qualifiers on join, if any */
 517         struct Attr *alias;                     /* user-written alias clause, if any */
 518         List       *colnames;           /* output column names (list of String) */
 519         List       *colvars;            /* output column nodes (list of expressions) */
 520 } JoinExpr;
 521
 522 /*----------
 523  * FromExpr - represents a FROM ... WHERE ... construct
 524  *
 525  * This is both more flexible than a JoinExpr (it can have any number of
 526  * children, including zero) and less so --- we don't need to deal with
 527  * aliases and so on.  The output column set is implicitly just the union
 528  * of the outputs of the children.
 529  *----------
 530  */
 531 typedef struct FromExpr
 532 {
 533         NodeTag         type;
 534         List       *fromlist;           /* List of join subtrees */
 535         Node       *quals;                      /* qualifiers on join, if any */
 536 } FromExpr;
 537
 538 #endif   /* PRIMNODES_H */