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

   1 /*-------------------------------------------------------------------------
   2  *
   3  * primnodes.h
   4  *        Definitions for parse tree/query tree ("primitive") nodes.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2000, PostgreSQL, Inc
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * $Id: primnodes.h,v 1.40 2000/02/20 21:32:16 tgl Exp $
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef PRIMNODES_H
  15 #define PRIMNODES_H
  16
  17 #include "access/attnum.h"
  18 #include "nodes/pg_list.h"
  19 #include "utils/fcache.h"
  20
  21 /* ----------------------------------------------------------------
  22  *                                              node definitions
  23  * ----------------------------------------------------------------
  24  */
  25
  26 /* ----------------
  27  * Resdom (Result Domain)
  28  *              resno                   - attribute number
  29  *              restype                 - type of the value
  30  *              restypmod               - type-specific modifier of the value
  31  *              resname                 - name of the resdom (could be NULL)
  32  *              ressortgroupref - nonzero if referenced by a sort/group clause
  33  *              reskey                  - order of key in a sort (for those > 0)
  34  *              reskeyop                - sort operator's regproc Oid
  35  *              resjunk                 - set to true to eliminate the attribute
  36  *                                                from final target list
  37  *
  38  * Notes:
  39  * ressortgroupref is the parse/plan-time representation of ORDER BY and
  40  * GROUP BY items.  Targetlist entries with ressortgroupref=0 are not
  41  * sort/group items.  If ressortgroupref>0, then this item is an ORDER BY or
  42  * GROUP BY value.  No two entries in a targetlist may have the same nonzero
  43  * ressortgroupref --- but there is no particular meaning to the nonzero
  44  * values, except as tags.  (For example, one must not assume that lower
  45  * ressortgroupref means a more significant sort key.)  The order of the
  46  * associated SortClause or GroupClause lists determine the semantics.
  47  *
  48  * reskey and reskeyop are the execution-time representation of sorting.
  49  * reskey must be zero in any non-sort-key item.  The reskey of sort key
  50  * targetlist items for a sort plan node is 1,2,...,n for the n sort keys.
  51  * The reskeyop of each such targetlist item is the sort operator's
  52  * regproc OID.  reskeyop will be zero in non-sort-key items.
  53  *
  54  * Both reskey and reskeyop are typically zero during parse/plan stages.
  55  * The executor does not pay any attention to ressortgroupref.
  56  * ----------------
  57  */
  58 typedef struct Resdom
  59 {
  60         NodeTag         type;
  61         AttrNumber      resno;
  62         Oid                     restype;
  63         int32           restypmod;
  64         char       *resname;
  65         Index           ressortgroupref;
  66         Index           reskey;
  67         Oid                     reskeyop;
  68         bool            resjunk;
  69 } Resdom;
  70
  71 /* -------------
  72  * Fjoin
  73  *              initialized             - true if the Fjoin has already been initialized for
  74  *                                                the current target list evaluation
  75  *              nNodes                  - The number of Iter nodes returning sets that the
  76  *                                                node will flatten
  77  *              outerList               - 1 or more Iter nodes
  78  *              inner                   - exactly one Iter node.  We eval every node in the
  79  *                                                outerList once then eval the inner node to completion
  80  *                                                pair the outerList result vector with each inner
  81  *                                                result to form the full result.  When the inner has
  82  *                                                been exhausted, we get the next outer result vector
  83  *                                                and reset the inner.
  84  *              results                 - The complete (flattened) result vector
  85  *              alwaysNull              - a null vector to indicate sets with a cardinality of
  86  *                                                0, we treat them as the set {NULL}.
  87  */
  88 typedef struct Fjoin
  89 {
  90         NodeTag         type;
  91         bool            fj_initialized;
  92         int                     fj_nNodes;
  93         List       *fj_innerNode;
  94         DatumPtr        fj_results;
  95         BoolPtr         fj_alwaysDone;
  96 } Fjoin;
  97
  98 /* ----------------
  99  * Expr
 100  *              typeOid                 - oid of the type of this expression
 101  *              opType                  - type of this expression
 102  *              oper                    - operator node if needed (Oper, Func, or SubPlan)
 103  *              args                    - arguments to this expression
 104  * ----------------
 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 expr */
 115         OpType          opType;                 /* type of the op */
 116         Node       *oper;                       /* could be Oper or Func or SubPlan */
 117         List       *args;                       /* list of argument nodes */
 118 } Expr;
 119
 120 /* ----------------
 121  * Var
 122  *              varno                   - index of this var's relation in the range table
 123  *                                                (could also be INNER or OUTER)
 124  *              varattno                - attribute number of this var, or zero for all
 125  *              vartype                 - pg_type tuple OID for the type of this var
 126  *              vartypmod               - pg_attribute typmod value
 127  *              varlevelsup             - for subquery variables referencing outer relations;
 128  *                                                0 in a normal var, >0 means N levels up
 129  *              varnoold                - original value of varno
 130  *              varoattno               - original value of varattno
 131  *
 132  * Note: during parsing/planning, varnoold/varoattno are always just copies
 133  * of varno/varattno.  At the tail end of planning, Var nodes appearing in
 134  * upper-level plan nodes are reassigned to point to the outputs of their
 135  * subplans; for example, in a join node varno becomes INNER or OUTER and
 136  * varattno becomes the index of the proper element of that subplan's target
 137  * list.  But varnoold/varoattno continue to hold the original values.
 138  * The code doesn't really need varnoold/varoattno, but they are very useful
 139  * for debugging and interpreting completed plans, so we keep them around.
 140  * ----------------
 141  */
 142 #define    INNER                65000
 143 #define    OUTER                65001
 144
 145 #define    PRS2_CURRENT_VARNO                   1
 146 #define    PRS2_NEW_VARNO                               2
 147
 148 typedef struct Var
 149 {
 150         NodeTag         type;
 151         Index           varno;
 152         AttrNumber      varattno;
 153         Oid                     vartype;
 154         int32           vartypmod;
 155         Index           varlevelsup;    /* erased by upper optimizer */
 156         Index           varnoold;               /* mainly for debugging --- see above */
 157         AttrNumber      varoattno;
 158 } Var;
 159
 160 /* ----------------
 161  * Oper
 162  *              opno                    - PG_OPERATOR OID of the operator
 163  *              opid                    - PG_PROC OID for the operator
 164  *              opresulttype    - PG_TYPE OID of the operator's return value
 165  *              opsize                  - size of return result (cached by executor)
 166  *              op_fcache               - XXX comment me.
 167  *
 168  * ----
 169  * NOTE: in the good old days 'opno' used to be both (or either, or
 170  * neither) the pg_operator oid, and/or the pg_proc oid depending
 171  * on the postgres module in question (parser->pg_operator,
 172  * executor->pg_proc, planner->both), the mood of the programmer,
 173  * and the phase of the moon (rumors that it was also depending on the day
 174  * of the week are probably false). To make things even more postgres-like
 175  * (i.e. a mess) some comments were referring to 'opno' using the name
 176  * 'opid'. Anyway, now we have two separate fields, and of course that
 177  * immediately removes all bugs from the code...                [ sp :-) ].
 178  * ----------------
 179  */
 180 typedef struct Oper
 181 {
 182         NodeTag         type;
 183         Oid                     opno;
 184         Oid                     opid;
 185         Oid                     opresulttype;
 186         int                     opsize;
 187         FunctionCachePtr op_fcache;
 188 } Oper;
 189
 190
 191 /* ----------------
 192  * Const
 193  *              consttype - PG_TYPE OID of the constant's value
 194  *              constlen - length in bytes of the constant's value
 195  *              constvalue - the constant's value
 196  *              constisnull - whether the constant is null
 197  *                              (if true, the other fields are undefined)
 198  *              constbyval - whether the information in constvalue
 199  *                              if passed by value.  If true, then all the information
 200  *                              is stored in the datum. If false, then the datum
 201  *                              contains a pointer to the information.
 202  *              constisset - whether the const represents a set.  The const
 203  *                              value corresponding will be the query that defines
 204  *                              the set.
 205  * ----------------
 206  */
 207 typedef struct Const
 208 {
 209         NodeTag         type;
 210         Oid                     consttype;
 211         int                     constlen;
 212         Datum           constvalue;
 213         bool            constisnull;
 214         bool            constbyval;
 215         bool            constisset;
 216         bool            constiscast;
 217 } Const;
 218
 219 /* ----------------
 220  * Param
 221  *              paramkind - specifies the kind of parameter. The possible values
 222  *              for this field are specified in "params.h", and they are:
 223  *
 224  *              PARAM_NAMED: The parameter has a name, i.e. something
 225  *                              like `$.salary' or `$.foobar'.
 226  *                              In this case field `paramname' must be a valid Name.
 227  *
 228  *              PARAM_NUM:       The parameter has only a numeric identifier,
 229  *                              i.e. something like `$1', `$2' etc.
 230  *                              The number is contained in the `paramid' field.
 231  *
 232  *              PARAM_NEW:       Used in PRS2 rule, similar to PARAM_NAMED.
 233  *                                       The `paramname' and `paramid' refer to the "NEW" tuple
 234  *                                       The `pramname' is the attribute name and `paramid'
 235  *                                       is the attribute number.
 236  *
 237  *              PARAM_OLD:       Same as PARAM_NEW, but in this case we refer to
 238  *                              the "OLD" tuple.
 239  *
 240  *              paramid - numeric identifier for literal-constant parameters ("$1")
 241  *              paramname - attribute name for tuple-substitution parameters ("$.foo")
 242  *              paramtype - PG_TYPE OID of the parameter's value
 243  *              param_tlist - allows for projection in a param node.
 244  * ----------------
 245  */
 246 typedef struct Param
 247 {
 248         NodeTag         type;
 249         int                     paramkind;
 250         AttrNumber      paramid;
 251         char       *paramname;
 252         Oid                     paramtype;
 253         List       *param_tlist;
 254 } Param;
 255
 256
 257 /* ----------------
 258  * Func
 259  *              funcid                  - PG_FUNCTION OID of the function
 260  *              functype                - PG_TYPE OID of the function's return value
 261  *              funcisindex             - the function can be evaluated by scanning an index
 262  *                                                (set during query optimization)
 263  *              funcsize                - size of return result (cached by executor)
 264  *              func_fcache             - runtime state while running this function.  Where
 265  *                                                we are in the execution of the function if it
 266  *                                                returns more than one value, etc.
 267  *                                                See utils/fcache.h
 268  *              func_tlist              - projection of functions returning tuples
 269  *              func_planlist   - result of planning this func, if it's a PQ func
 270  * ----------------
 271  */
 272 typedef struct Func
 273 {
 274         NodeTag         type;
 275         Oid                     funcid;
 276         Oid                     functype;
 277         bool            funcisindex;
 278         int                     funcsize;
 279         FunctionCachePtr func_fcache;
 280         List       *func_tlist;
 281         List       *func_planlist;
 282 } Func;
 283
 284 /* ----------------
 285  * Iter
 286  *              can anyone explain what this is for?  Seems to have something to do
 287  *              with evaluation of functions that return sets...
 288  * ----------------
 289  */
 290 typedef struct Iter
 291 {
 292         NodeTag         type;
 293         Node       *iterexpr;
 294         Oid                     itertype;               /* type of the iter expr (use for type
 295                                                                  * checking) */
 296 } Iter;
 297
 298 /* ----------------
 299  * Aggref
 300  *              aggname                 - name of the aggregate
 301  *              basetype                - base type Oid of the aggregate (ie, input type)
 302  *              aggtype                 - type Oid of final result of the aggregate
 303  *              target                  - attribute or expression we are aggregating on
 304  *              usenulls                - TRUE to accept null values as inputs
 305  *              aggstar                 - TRUE if argument was really '*'
 306  *              aggdistinct             - TRUE if arguments were labeled DISTINCT
 307  *              aggno                   - workspace for nodeAgg.c executor
 308  * ----------------
 309  */
 310 typedef struct Aggref
 311 {
 312         NodeTag         type;
 313         char       *aggname;
 314         Oid                     basetype;
 315         Oid                     aggtype;
 316         Node       *target;
 317         bool            usenulls;
 318         bool            aggstar;
 319         bool            aggdistinct;
 320         int                     aggno;
 321 } Aggref;
 322
 323 /* ----------------
 324  * SubLink
 325  *              subLinkType             - EXISTS, ALL, ANY, MULTIEXPR, EXPR
 326  *              useor                   - TRUE to combine column results with "OR" not "AND"
 327  *              lefthand                - list of outer-query expressions on the left
 328  *              oper                    - list of Oper nodes for combining operators
 329  *              subselect               - subselect as Query* or parsetree
 330  *
 331  * A SubLink represents a subselect appearing in an expression, and in some
 332  * cases also the combining operator(s) just above it.  The subLinkType
 333  * indicates the form of the expression represented:
 334  *      EXISTS_SUBLINK          EXISTS(SELECT ...)
 335  *      ALL_SUBLINK                     (lefthand) op ALL (SELECT ...)
 336  *      ANY_SUBLINK                     (lefthand) op ANY (SELECT ...)
 337  *      MULTIEXPR_SUBLINK       (lefthand) op (SELECT ...)
 338  *      EXPR_SUBLINK            (SELECT with single targetlist item ...)
 339  * For ALL, ANY, and MULTIEXPR, the lefthand is a list of expressions of the
 340  * same length as the subselect's targetlist.  MULTIEXPR will *always* have
 341  * a list with more than one entry; if the subselect has just one target
 342  * then the parser will create an EXPR_SUBLINK instead (and any operator
 343  * above the subselect will be represented separately).  Note that both
 344  * MULTIEXPR and EXPR require the subselect to deliver only one row.
 345  * ALL, ANY, and MULTIEXPR require the combining operators to deliver boolean
 346  * results.  These are reduced to one result per row using OR or AND semantics
 347  * depending on the "useor" flag.  ALL and ANY combine the per-row results
 348  * using AND and OR semantics respectively.
 349  *
 350  * NOTE: lefthand and oper have varying meanings depending on where you look
 351  * in the parse/plan pipeline:
 352  * 1. gram.y delivers a list of the (untransformed) lefthand expressions in
 353  *    lefthand, and sets oper to a one-element list containing the string
 354  *    name of the operator.
 355  * 2. The parser's expression transformation transforms lefthand normally,
 356  *    and replaces oper with a list of Oper nodes, one per lefthand
 357  *    expression.  These nodes represent the parser's resolution of exactly
 358  *    which operator to apply to each pair of lefthand and targetlist
 359  *    expressions.  However, we have not constructed actual Expr trees for
 360  *    these operators yet.  This is the representation seen in saved rules
 361  *    and in the rewriter.
 362  * 3. Finally, the planner converts the oper list to a list of normal Expr
 363  *    nodes representing the application of the operator(s) to the lefthand
 364  *    expressions and values from the inner targetlist.  The inner
 365  *    targetlist items are represented by placeholder Param or Const nodes.
 366  *    The lefthand field is set to NIL, since its expressions are now in
 367  *    the Expr list.  This representation is passed to the executor.
 368  *
 369  * Planner routines that might see either representation 2 or 3 can tell
 370  * the difference by checking whether lefthand is NIL or not.  Also,
 371  * representation 2 appears in a "bare" SubLink, while representation 3 is
 372  * found in SubLinks that are children of SubPlan nodes.
 373  *
 374  * In EXISTS and EXPR SubLinks, both lefthand and oper are unused and are
 375  * always NIL.  useor is not significant either for these sublink types.
 376  * ----------------
 377  */
 378 typedef enum SubLinkType
 379 {
 380         EXISTS_SUBLINK, ALL_SUBLINK, ANY_SUBLINK, MULTIEXPR_SUBLINK, EXPR_SUBLINK
 381 } SubLinkType;
 382
 383
 384 typedef struct SubLink
 385 {
 386         NodeTag         type;
 387         SubLinkType subLinkType;
 388         bool            useor;
 389         List       *lefthand;
 390         List       *oper;
 391         Node       *subselect;
 392 } SubLink;
 393
 394 /* ----------------
 395  * Array
 396  *              arrayelemtype   - type of the array's elements (homogenous!)
 397  *              arrayelemlength - length of that type
 398  *              arrayelembyval  - is the element type pass-by-value?
 399  *              arrayndim               - number of dimensions of the array
 400  *              arraylow                - base for array indexing
 401  *              arrayhigh               - limit for array indexing
 402  *              arraylen                - total length of array object
 403  * ----------------
 404  *
 405  *      memo from mao:  the array support we inherited from 3.1 is just
 406  *      wrong.  when time exists, we should redesign this stuff to get
 407  *      around a bunch of unfortunate implementation decisions made there.
 408  */
 409 typedef struct Array
 410 {
 411         NodeTag         type;
 412         Oid                     arrayelemtype;
 413         int                     arrayelemlength;
 414         bool            arrayelembyval;
 415         int                     arrayndim;
 416         IntArray        arraylow;
 417         IntArray        arrayhigh;
 418         int                     arraylen;
 419 } Array;
 420
 421 /* ----------------
 422  *      ArrayRef: describes an array subscripting operation
 423  *
 424  * An ArrayRef can describe fetching a single element from an array,
 425  * fetching a subarray (array slice), storing a single element into
 426  * an array, or storing a slice.  The "store" cases work with an
 427  * initial array value and a source value that is inserted into the
 428  * appropriate part of the array.
 429  *
 430  *              refattrlength   - total length of array object
 431  *              refelemtype             - type of the result of the subscript operation
 432  *              refelemlength   - length of the array element type
 433  *              refelembyval    - is the element type pass-by-value?
 434  *              refupperindexpr - expressions that evaluate to upper array indexes
 435  *              reflowerindexpr - expressions that evaluate to lower array indexes
 436  *              refexpr                 - the expression that evaluates to an array value
 437  *              refassgnexpr    - expression for the source value, or NULL if fetch
 438  *
 439  * If reflowerindexpr = NIL, then we are fetching or storing a single array
 440  * element at the subscripts given by refupperindexpr.  Otherwise we are
 441  * fetching or storing an array slice, that is a rectangular subarray
 442  * with lower and upper bounds given by the index expressions.
 443  * reflowerindexpr must be the same length as refupperindexpr when it
 444  * is not NIL.
 445  *
 446  * Note: array types can be fixed-length (refattrlength > 0), but only
 447  * when the element type is itself fixed-length.  Otherwise they are
 448  * varlena structures and have refattrlength = -1.  In any case,
 449  * an array type is never pass-by-value.
 450  *
 451  * Note: currently, refelemtype is NOT the element type, but the array type,
 452  * when doing subarray fetch or either type of store.  It would be cleaner
 453  * to add more fields so we can distinguish the array element type from the
 454  * result type of the subscript operator...
 455  * ----------------
 456  */
 457 typedef struct ArrayRef
 458 {
 459         NodeTag         type;
 460         int                     refattrlength;
 461         int                     refelemlength;
 462         Oid                     refelemtype;
 463         bool            refelembyval;
 464         List       *refupperindexpr;
 465         List       *reflowerindexpr;
 466         Node       *refexpr;
 467         Node       *refassgnexpr;
 468 } ArrayRef;
 469
 470 /* ----------------
 471  * RelabelType
 472  *              arg                             - input expression
 473  *              resulttype              - output type of coercion expression
 474  *              resulttypmod    - output typmod (usually -1)
 475  *
 476  * RelabelType represents a "dummy" type coercion between two binary-
 477  * compatible datatypes, such as reinterpreting the result of an OID
 478  * expression as an int4.  It is a no-op at runtime; we only need it
 479  * to provide a place to store the correct type to be attributed to
 480  * the expression result during type resolution.  (We can't get away
 481  * with just overwriting the type field of the input expression node,
 482  * so we need a separate node to show the coercion's result type.)
 483  * ----------------
 484  */
 485
 486 typedef struct RelabelType
 487 {
 488         NodeTag         type;
 489         Node       *arg;
 490         Oid                     resulttype;
 491         int32           resulttypmod;
 492 } RelabelType;
 493
 494 #endif   /* PRIMNODES_H */