1 /*-------------------------------------------------------------------------
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
10 * Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group
11 * Portions Copyright (c) 1994, Regents of the University of California
13 * $Id: primnodes.h,v 1.82 2003/05/06 00:20:33 tgl Exp $
15 *-------------------------------------------------------------------------
20 #include "access/attnum.h"
21 #include "nodes/pg_list.h"
24 /* ----------------------------------------------------------------
26 * ----------------------------------------------------------------
29 /*--------------------
30 * Resdom (Result Domain)
34 * resno will normally be equal to the item's position in a targetlist,
35 * but the code generally tries to avoid relying on that (eg, we avoid
36 * using "nth()" rather than a search to find an item by resno).
38 * resname will be null if no name can easily be assigned to the column.
39 * But it should never be null for user-visible columns (i.e., non-junk
40 * columns in a toplevel targetlist).
42 * ressortgroupref is used in the representation of ORDER BY and
43 * GROUP BY items. Targetlist entries with ressortgroupref=0 are not
44 * sort/group items. If ressortgroupref>0, then this item is an ORDER BY or
45 * GROUP BY value. No two entries in a targetlist may have the same nonzero
46 * ressortgroupref --- but there is no particular meaning to the nonzero
47 * values, except as tags. (For example, one must not assume that lower
48 * ressortgroupref means a more significant sort key.) The order of the
49 * associated SortClause or GroupClause lists determine the semantics.
51 * resorigtbl/resorigcol identify the source of the column, if it is a
52 * simple reference to a column of a base table (or view). If it is not
53 * a simple reference, these fields are zeroes.
55 * If resjunk is true then the column is a working column (such as a sort key)
56 * that should be removed from the final output of the query.
62 AttrNumber resno; /* attribute number (1..N) */
63 Oid restype; /* type of the value */
64 int32 restypmod; /* type-specific modifier of the value */
65 char *resname; /* name of the column (could be NULL) */
66 Index ressortgroupref; /* nonzero if referenced by a
67 * sort/group clause */
68 Oid resorigtbl; /* OID of column's source table */
69 AttrNumber resorigcol; /* column's number in source table */
70 bool resjunk; /* set to true to eliminate the attribute
71 * from final target list */
77 * specifies an alias for a range variable; the alias might also
78 * specify renaming of columns within the table.
83 char *aliasname; /* aliased rel name (never qualified) */
84 List *colnames; /* optional list of column aliases */
85 /* Note: colnames is a list of Value nodes (always strings) */
88 typedef enum InhOption
90 INH_NO, /* Do NOT scan child tables */
91 INH_YES, /* DO scan child tables */
92 INH_DEFAULT /* Use current SQL_inheritance option */
96 * RangeVar - range variable, used in FROM clauses
98 * Also used to represent table names in utility statements; there, the alias
99 * field is not used, and inhOpt shows whether to apply the operation
100 * recursively to child tables. In some contexts it is also useful to carry
101 * a TEMP table indication here.
103 typedef struct RangeVar
106 char *catalogname; /* the catalog (database) name, or NULL */
107 char *schemaname; /* the schema name, or NULL */
108 char *relname; /* the relation/sequence name */
109 InhOption inhOpt; /* expand rel by inheritance? recursively
110 * act on children? */
111 bool istemp; /* is this a temp relation/sequence? */
112 Alias *alias; /* table alias & optional column aliases */
116 /* ----------------------------------------------------------------
117 * node types for executable expressions
118 * ----------------------------------------------------------------
122 * Expr - generic superclass for executable-expression nodes
124 * All node types that are used in executable expression trees should derive
125 * from Expr (that is, have Expr as their first field). Since Expr only
126 * contains NodeTag, this is a formality, but it is an easy form of
127 * documentation. See also the ExprState node types in execnodes.h.
135 * Var - expression node representing a variable (ie, a table column)
137 * Note: during parsing/planning, varnoold/varoattno are always just copies
138 * of varno/varattno. At the tail end of planning, Var nodes appearing in
139 * upper-level plan nodes are reassigned to point to the outputs of their
140 * subplans; for example, in a join node varno becomes INNER or OUTER and
141 * varattno becomes the index of the proper element of that subplan's target
142 * list. But varnoold/varoattno continue to hold the original values.
143 * The code doesn't really need varnoold/varoattno, but they are very useful
144 * for debugging and interpreting completed plans, so we keep them around.
149 #define PRS2_OLD_VARNO 1
150 #define PRS2_NEW_VARNO 2
155 Index varno; /* index of this var's relation in the
156 * range table (could also be INNER or
158 AttrNumber varattno; /* attribute number of this var, or zero
160 Oid vartype; /* pg_type tuple OID for the type of this
162 int32 vartypmod; /* pg_attribute typmod value */
166 * for subquery variables referencing outer relations; 0 in a normal
167 * var, >0 means N levels up
169 Index varnoold; /* original value of varno, for debugging */
170 AttrNumber varoattno; /* original value of varattno */
179 Oid consttype; /* PG_TYPE OID of the constant's datatype */
180 int constlen; /* typlen of the constant's datatype */
181 Datum constvalue; /* the constant's value */
182 bool constisnull; /* whether the constant is null (if true,
183 * constvalue is undefined) */
184 bool constbyval; /* whether this datatype is passed by value.
185 * If true, then all the information is
186 * stored in the Datum.
187 * If false, then the Datum contains a
188 * pointer to the information. */
193 * paramkind - specifies the kind of parameter. The possible values
194 * for this field are specified in "params.h", and they are:
196 * PARAM_NAMED: The parameter has a name, i.e. something
197 * like `$.salary' or `$.foobar'.
198 * In this case field `paramname' must be a valid name.
200 * PARAM_NUM: The parameter has only a numeric identifier,
201 * i.e. something like `$1', `$2' etc.
202 * The number is contained in the `paramid' field.
204 * PARAM_EXEC: The parameter is an internal executor parameter.
205 * It has a number contained in the `paramid' field.
211 int paramkind; /* kind of parameter. See above */
212 AttrNumber paramid; /* numeric ID for parameter ("$1") */
213 char *paramname; /* name for parameter ("$.foo") */
214 Oid paramtype; /* PG_TYPE OID of parameter's datatype */
220 typedef struct Aggref
223 Oid aggfnoid; /* pg_proc Oid of the aggregate */
224 Oid aggtype; /* type Oid of result of the aggregate */
225 Expr *target; /* expression we are aggregating on */
226 bool aggstar; /* TRUE if argument was really '*' */
227 bool aggdistinct; /* TRUE if it's agg(DISTINCT ...) */
231 * ArrayRef: describes an array subscripting operation
233 * An ArrayRef can describe fetching a single element from an array,
234 * fetching a subarray (array slice), storing a single element into
235 * an array, or storing a slice. The "store" cases work with an
236 * initial array value and a source value that is inserted into the
237 * appropriate part of the array; the result of the operation is an
238 * entire new modified array value.
240 * If reflowerindexpr = NIL, then we are fetching or storing a single array
241 * element at the subscripts given by refupperindexpr. Otherwise we are
242 * fetching or storing an array slice, that is a rectangular subarray
243 * with lower and upper bounds given by the index expressions.
244 * reflowerindexpr must be the same length as refupperindexpr when it
247 * Note: refrestype is NOT the element type, but the array type,
248 * when doing subarray fetch or either type of store.
251 typedef struct ArrayRef
254 Oid refrestype; /* type of the result of the ArrayRef
256 Oid refarraytype; /* type of the array proper */
257 Oid refelemtype; /* type of the array elements */
258 List *refupperindexpr;/* expressions that evaluate to upper
260 List *reflowerindexpr;/* expressions that evaluate to lower
262 Expr *refexpr; /* the expression that evaluates to an
264 Expr *refassgnexpr; /* expression for the source value, or
269 * CoercionContext - distinguishes the allowed set of type casts
271 * NB: ordering of the alternatives is significant; later (larger) values
272 * allow more casts than earlier ones.
274 typedef enum CoercionContext
276 COERCION_IMPLICIT, /* coercion in context of expression */
277 COERCION_ASSIGNMENT, /* coercion in context of assignment */
278 COERCION_EXPLICIT /* explicit cast operation */
282 * CoercionForm - information showing how to display a function-call node
284 typedef enum CoercionForm
286 COERCE_EXPLICIT_CALL, /* display as a function call */
287 COERCE_EXPLICIT_CAST, /* display as an explicit cast */
288 COERCE_IMPLICIT_CAST, /* implicit cast, so hide it */
289 COERCE_DONTCARE /* special case for pathkeys */
293 * FuncExpr - expression node for a function call
295 typedef struct FuncExpr
298 Oid funcid; /* PG_PROC OID of the function */
299 Oid funcresulttype; /* PG_TYPE OID of result value */
300 bool funcretset; /* true if function returns set */
301 CoercionForm funcformat; /* how to display this function call */
302 List *args; /* arguments to the function */
306 * OpExpr - expression node for an operator invocation
308 * Semantically, this is essentially the same as a function call.
310 * Note that opfuncid is not necessarily filled in immediately on creation
311 * of the node. The planner makes sure it is valid before passing the node
312 * tree to the executor, but during parsing/planning opfuncid is typically 0.
314 typedef struct OpExpr
317 Oid opno; /* PG_OPERATOR OID of the operator */
318 Oid opfuncid; /* PG_PROC OID of underlying function */
319 Oid opresulttype; /* PG_TYPE OID of result value */
320 bool opretset; /* true if operator returns set */
321 List *args; /* arguments to the operator (1 or 2) */
325 * DistinctExpr - expression node for "x IS DISTINCT FROM y"
327 * Except for the nodetag, this is represented identically to an OpExpr
328 * referencing the "=" operator for x and y.
329 * We use "=", not the more obvious "<>", because more datatypes have "="
330 * than "<>". This means the executor must invert the operator result.
331 * Note that the operator function won't be called at all if either input
332 * is NULL, since then the result can be determined directly.
334 typedef OpExpr DistinctExpr;
337 * BoolExpr - expression node for the basic Boolean operators AND, OR, NOT
339 * Notice the arguments are given as a List. For NOT, of course the list
340 * must always have exactly one element. For AND and OR, the executor can
341 * handle any number of arguments. The parser treats AND and OR as binary
342 * and so it only produces two-element lists, but the optimizer will flatten
343 * trees of AND and OR nodes to produce longer lists when possible.
345 typedef enum BoolExprType
347 AND_EXPR, OR_EXPR, NOT_EXPR
350 typedef struct BoolExpr
354 List *args; /* arguments to this expression */
360 * A SubLink represents a subselect appearing in an expression, and in some
361 * cases also the combining operator(s) just above it. The subLinkType
362 * indicates the form of the expression represented:
363 * EXISTS_SUBLINK EXISTS(SELECT ...)
364 * ALL_SUBLINK (lefthand) op ALL (SELECT ...)
365 * ANY_SUBLINK (lefthand) op ANY (SELECT ...)
366 * MULTIEXPR_SUBLINK (lefthand) op (SELECT ...)
367 * EXPR_SUBLINK (SELECT with single targetlist item ...)
368 * ARRAY_SUBLINK ARRAY(SELECT with single targetlist item ...)
369 * For ALL, ANY, and MULTIEXPR, the lefthand is a list of expressions of the
370 * same length as the subselect's targetlist. MULTIEXPR will *always* have
371 * a list with more than one entry; if the subselect has just one target
372 * then the parser will create an EXPR_SUBLINK instead (and any operator
373 * above the subselect will be represented separately). Note that both
374 * MULTIEXPR and EXPR require the subselect to deliver only one row.
375 * ARRAY requires just one target column, and creates an array of the target
376 * column's type using one or more rows resulting from the subselect.
377 * ALL, ANY, and MULTIEXPR require the combining operators to deliver boolean
378 * results. These are reduced to one result per row using OR or AND semantics
379 * depending on the "useOr" flag. ALL and ANY combine the per-row results
380 * using AND and OR semantics respectively.
382 * SubLink is classed as an Expr node, but it is not actually executable;
383 * it must be replaced in the expression tree by a SubPlan node during
386 * NOTE: in the raw output of gram.y, lefthand contains a list of raw
387 * expressions; useOr and operOids are not filled in yet. Also, subselect
388 * is a raw parsetree. During parse analysis, the parser transforms the
389 * lefthand expression list using normal expression transformation rules.
390 * It fills operOids with the OIDs representing the specific operator(s)
391 * to apply to each pair of lefthand and targetlist expressions.
392 * And subselect is transformed to a Query. This is the representation
393 * seen in saved rules and in the rewriter.
395 * In EXISTS, EXPR, and ARRAY SubLinks, lefthand, operName, and operOids are
396 * unused and are always NIL. useOr is not significant either for these
400 typedef enum SubLinkType
411 typedef struct SubLink
414 SubLinkType subLinkType; /* EXISTS, ALL, ANY, MULTIEXPR, EXPR */
415 bool useOr; /* TRUE to combine column results with
417 List *lefthand; /* list of outer-query expressions on the
419 List *operName; /* originally specified operator name */
420 List *operOids; /* OIDs of actual combining operators */
421 Node *subselect; /* subselect as Query* or parsetree */
425 * SubPlan - executable expression node for a subplan (sub-SELECT)
427 * The planner replaces SubLink nodes in expression trees with SubPlan
428 * nodes after it has finished planning the subquery. SubPlan contains
429 * a sub-plantree and rtable instead of a sub-Query.
431 * In an ordinary subplan, "exprs" points to a list of executable expressions
432 * (OpExpr trees) for the combining operators; their left-hand arguments are
433 * the original lefthand expressions, and their right-hand arguments are
434 * PARAM_EXEC Param nodes representing the outputs of the sub-select.
435 * (NOTE: runtime coercion functions may be inserted as well.) But if the
436 * sub-select becomes an initplan rather than a subplan, these executable
437 * expressions are part of the outer plan's expression tree (and the SubPlan
438 * node itself is not). In this case "exprs" is NIL to avoid duplication.
440 * The planner also derives lists of the values that need to be passed into
441 * and out of the subplan. Input values are represented as a list "args" of
442 * expressions to be evaluated in the outer-query context (currently these
443 * args are always just Vars, but in principle they could be any expression).
444 * The values are assigned to the global PARAM_EXEC params indexed by parParam
445 * (the parParam and args lists must have the same ordering). setParam is a
446 * list of the PARAM_EXEC params that are computed by the sub-select, if it
447 * is an initplan; they are listed in order by sub-select output column
448 * position. (parParam and setParam are integer Lists, not Bitmapsets,
449 * because their ordering is significant.)
451 typedef struct SubPlan
454 /* Fields copied from original SubLink: */
455 SubLinkType subLinkType; /* EXISTS, ALL, ANY, MULTIEXPR, EXPR */
456 bool useOr; /* TRUE to combine column results with
458 /* The combining operators, transformed to executable expressions: */
459 List *exprs; /* list of OpExpr expression trees */
460 List *paramIds; /* IDs of Params embedded in the above */
461 /* Note: paramIds has a one-to-one correspondence to the exprs list */
462 /* The subselect, transformed to a Plan: */
463 struct Plan *plan; /* subselect plan itself */
464 int plan_id; /* dummy thing because of we haven't equal
465 * funcs for plan nodes... actually, we
466 * could put *plan itself somewhere else
467 * (TopPlan node ?)... */
468 List *rtable; /* range table for subselect */
469 /* Information about execution strategy: */
470 bool useHashTable; /* TRUE to store subselect output in a hash
471 * table (implies we are doing "IN") */
472 bool unknownEqFalse; /* TRUE if it's okay to return FALSE when
473 * the spec result is UNKNOWN; this allows
474 * much simpler handling of null values */
475 /* Information for passing params into and out of the subselect: */
476 /* setParam and parParam are lists of integers (param IDs) */
477 List *setParam; /* initplan subqueries have to set these
478 * Params for parent plan */
479 List *parParam; /* indices of input Params from parent plan */
480 List *args; /* exprs to pass as parParam values */
486 * FieldSelect represents the operation of extracting one field from a tuple
487 * value. At runtime, the input expression is expected to yield a Datum
488 * that contains a pointer-to-TupleTableSlot. The specified field number
489 * is extracted and returned as a Datum.
493 typedef struct FieldSelect
496 Expr *arg; /* input expression */
497 AttrNumber fieldnum; /* attribute number of field to extract */
498 Oid resulttype; /* type of the field (result type of this
500 int32 resulttypmod; /* output typmod (usually -1) */
506 * RelabelType represents a "dummy" type coercion between two binary-
507 * compatible datatypes, such as reinterpreting the result of an OID
508 * expression as an int4. It is a no-op at runtime; we only need it
509 * to provide a place to store the correct type to be attributed to
510 * the expression result during type resolution. (We can't get away
511 * with just overwriting the type field of the input expression node,
512 * so we need a separate node to show the coercion's result type.)
516 typedef struct RelabelType
519 Expr *arg; /* input expression */
520 Oid resulttype; /* output type of coercion expression */
521 int32 resulttypmod; /* output typmod (usually -1) */
522 CoercionForm relabelformat; /* how to display this node */
526 * CaseExpr - a CASE expression
528 typedef struct CaseExpr
531 Oid casetype; /* type of expression result */
532 Expr *arg; /* implicit equality comparison argument */
533 List *args; /* the arguments (list of WHEN clauses) */
534 Expr *defresult; /* the default result (ELSE clause) */
538 * CaseWhen - an argument to a CASE expression
540 typedef struct CaseWhen
543 Expr *expr; /* condition expression */
544 Expr *result; /* substitution result */
548 * ArrayExpr - an ARRAY[] expression
550 * Note: if ndims > 1, then the array elements are all ArrayExprs of the
551 * same type and ndims one less.
553 typedef struct ArrayExpr
556 Oid array_typeid; /* type of expression result */
557 Oid element_typeid; /* common type of expression elements */
558 List *elements; /* the array elements */
559 int ndims; /* number of array dimensions */
563 * CoalesceExpr - a COALESCE expression
565 typedef struct CoalesceExpr
568 Oid coalescetype; /* type of expression result */
569 List *args; /* the arguments */
573 * NullIfExpr - a NULLIF expression
575 * Like DistinctExpr, this is represented the same as an OpExpr referencing
576 * the "=" operator for x and y.
578 typedef OpExpr NullIfExpr;
583 * NullTest represents the operation of testing a value for NULLness.
584 * Currently, we only support scalar input values, but eventually a
585 * row-constructor input should be supported.
586 * The appropriate test is performed and returned as a boolean Datum.
590 typedef enum NullTestType
595 typedef struct NullTest
598 Expr *arg; /* input expression */
599 NullTestType nulltesttype; /* IS NULL, IS NOT NULL */
605 * BooleanTest represents the operation of determining whether a boolean
606 * is TRUE, FALSE, or UNKNOWN (ie, NULL). All six meaningful combinations
607 * are supported. Note that a NULL input does *not* cause a NULL result.
608 * The appropriate test is performed and returned as a boolean Datum.
611 typedef enum BoolTestType
613 IS_TRUE, IS_NOT_TRUE, IS_FALSE, IS_NOT_FALSE, IS_UNKNOWN, IS_NOT_UNKNOWN
616 typedef struct BooleanTest
619 Expr *arg; /* input expression */
620 BoolTestType booltesttype; /* test type */
626 * CoerceToDomain represents the operation of coercing a value to a domain
627 * type. At runtime (and not before) the precise set of constraints to be
628 * checked will be determined. If the value passes, it is returned as the
629 * result; if not, an error is raised. Note that this is equivalent to
630 * RelabelType in the scenario where no constraints are applied.
632 typedef struct CoerceToDomain
635 Expr *arg; /* input expression */
636 Oid resulttype; /* domain type ID (result type) */
637 int32 resulttypmod; /* output typmod (currently always -1) */
638 CoercionForm coercionformat; /* how to display this node */
642 * Placeholder node for the value to be processed by a domain's check
643 * constraint. This is effectively like a Param, but can be implemented more
644 * simply since we need only one replacement value at a time.
646 * Note: the typeId/typeMod will be set from the domain's base type, not
647 * the domain itself. This is because we shouldn't consider the value to
648 * be a member of the domain if we haven't yet checked its constraints.
650 typedef struct CoerceToDomainValue
653 Oid typeId; /* type for substituted value */
654 int32 typeMod; /* typemod for substituted value */
655 } CoerceToDomainValue;
660 * a target entry (used in query target lists)
662 * Strictly speaking, a TargetEntry isn't an expression node (since it can't
663 * be evaluated by ExecEvalExpr). But we treat it as one anyway, since in
664 * very many places it's convenient to process a whole query targetlist as a
665 * single expression tree.
667 * The separation between TargetEntry and Resdom is historical. One of these
668 * days, Resdom should probably get folded into TargetEntry.
670 typedef struct TargetEntry
673 Resdom *resdom; /* descriptor for targetlist item */
674 Expr *expr; /* expression to evaluate */
678 /* ----------------------------------------------------------------
679 * node types for join trees
681 * The leaves of a join tree structure are RangeTblRef nodes. Above
682 * these, JoinExpr nodes can appear to denote a specific kind of join
683 * or qualified join. Also, FromExpr nodes can appear to denote an
684 * ordinary cross-product join ("FROM foo, bar, baz WHERE ...").
685 * FromExpr is like a JoinExpr of jointype JOIN_INNER, except that it
686 * may have any number of child nodes, not just two. Also, there is an
687 * implementation-defined difference: the planner is allowed to join the
688 * children of a FromExpr using whatever join order seems good to it.
689 * At present, JoinExpr nodes are always joined in exactly the order
690 * implied by the jointree structure (except the planner may choose to
691 * swap inner and outer members of a join pair).
693 * NOTE: the top level of a Query's jointree is always a FromExpr.
694 * Even if the jointree contains no rels, there will be a FromExpr.
696 * NOTE: the qualification expressions present in JoinExpr nodes are
697 * *in addition to* the query's main WHERE clause, which appears as the
698 * qual of the top-level FromExpr. The reason for associating quals with
699 * specific nodes in the jointree is that the position of a qual is critical
700 * when outer joins are present. (If we enforce a qual too soon or too late,
701 * that may cause the outer join to produce the wrong set of NULL-extended
702 * rows.) If all joins are inner joins then all the qual positions are
703 * semantically interchangeable.
705 * NOTE: in the raw output of gram.y, a join tree contains RangeVar,
706 * RangeSubselect, and RangeFunction nodes, which are all replaced by
707 * RangeTblRef nodes during the parse analysis phase. Also, the top-level
708 * FromExpr is added during parse analysis; the grammar regards FROM and
710 * ----------------------------------------------------------------
714 * RangeTblRef - reference to an entry in the query's rangetable
716 * We could use direct pointers to the RT entries and skip having these
717 * nodes, but multiple pointers to the same node in a querytree cause
718 * lots of headaches, so it seems better to store an index into the RT.
720 typedef struct RangeTblRef
727 * JoinExpr - for SQL JOIN expressions
729 * isNatural, using, and quals are interdependent. The user can write only
730 * one of NATURAL, USING(), or ON() (this is enforced by the grammar).
731 * If he writes NATURAL then parse analysis generates the equivalent USING()
732 * list, and from that fills in "quals" with the right equality comparisons.
733 * If he writes USING() then "quals" is filled with equality comparisons.
734 * If he writes ON() then only "quals" is set. Note that NATURAL/USING
735 * are not equivalent to ON() since they also affect the output column list.
737 * alias is an Alias node representing the AS alias-clause attached to the
738 * join expression, or NULL if no clause. NB: presence or absence of the
739 * alias has a critical impact on semantics, because a join with an alias
740 * restricts visibility of the tables/columns inside it.
742 * During parse analysis, an RTE is created for the Join, and its index
743 * is filled into rtindex. This RTE is present mainly so that Vars can
744 * be created that refer to the outputs of the join.
747 typedef struct JoinExpr
750 JoinType jointype; /* type of join */
751 bool isNatural; /* Natural join? Will need to shape table */
752 Node *larg; /* left subtree */
753 Node *rarg; /* right subtree */
754 List *using; /* USING clause, if any (list of String) */
755 Node *quals; /* qualifiers on join, if any */
756 Alias *alias; /* user-written alias clause, if any */
757 int rtindex; /* RT index assigned for join */
761 * FromExpr - represents a FROM ... WHERE ... construct
763 * This is both more flexible than a JoinExpr (it can have any number of
764 * children, including zero) and less so --- we don't need to deal with
765 * aliases and so on. The output column set is implicitly just the union
766 * of the outputs of the children.
769 typedef struct FromExpr
772 List *fromlist; /* List of join subtrees */
773 Node *quals; /* qualifiers on join, if any */
776 #endif /* PRIMNODES_H */