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