| 1 |
/*------------------------------------------------------------------------- |
| 2 |
* |
| 3 |
* nodes.h |
| 4 |
* Definitions for tagged nodes. |
| 5 |
* |
| 6 |
* |
| 7 |
* Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group |
| 8 |
* Portions Copyright (c) 1994, Regents of the University of California |
| 9 |
* |
| 10 |
* src/include/nodes/nodes.h |
| 11 |
* |
| 12 |
*------------------------------------------------------------------------- |
| 13 |
*/ |
| 14 |
#ifndef NODES_H |
| 15 |
#define NODES_H |
| 16 |
|
| 17 |
/* |
| 18 |
* The first field of every node is NodeTag. Each node created (with makeNode) |
| 19 |
* will have one of the following tags as the value of its first field. |
| 20 |
* |
| 21 |
* Note that inserting or deleting node types changes the numbers of other |
| 22 |
* node types later in the list. This is no problem during development, since |
| 23 |
* the node numbers are never stored on disk. But don't do it in a released |
| 24 |
* branch, because that would represent an ABI break for extensions. |
| 25 |
*/ |
| 26 |
typedef enum NodeTag |
| 27 |
{ |
| 28 |
T_Invalid = 0, |
| 29 |
|
| 30 |
#include "nodes/nodetags.h" |
| 31 |
} NodeTag; |
| 32 |
|
| 33 |
/* |
| 34 |
* pg_node_attr() - Used in node definitions to set extra information for |
| 35 |
* gen_node_support.pl |
| 36 |
* |
| 37 |
* Attributes can be attached to a node as a whole (place the attribute |
| 38 |
* specification on the first line after the struct's opening brace) |
| 39 |
* or to a specific field (place it at the end of that field's line). The |
| 40 |
* argument is a comma-separated list of attributes. Unrecognized attributes |
| 41 |
* cause an error. |
| 42 |
* |
| 43 |
* Valid node attributes: |
| 44 |
* |
| 45 |
* - abstract: Abstract types are types that cannot be instantiated but that |
| 46 |
* can be supertypes of other types. We track their fields, so that |
| 47 |
* subtypes can use them, but we don't emit a node tag, so you can't |
| 48 |
* instantiate them. |
| 49 |
* |
| 50 |
* - custom_copy_equal: Has custom implementations in copyfuncs.c and |
| 51 |
* equalfuncs.c. |
| 52 |
* |
| 53 |
* - custom_read_write: Has custom implementations in outfuncs.c and |
| 54 |
* readfuncs.c. |
| 55 |
* |
| 56 |
* - custom_query_jumble: Has custom implementation in queryjumblefuncs.c. |
| 57 |
* Also available as a node field attribute. |
| 58 |
* |
| 59 |
* - no_copy: Does not support copyObject() at all. |
| 60 |
* |
| 61 |
* - no_equal: Does not support equal() at all. |
| 62 |
* |
| 63 |
* - no_copy_equal: Shorthand for both no_copy and no_equal. |
| 64 |
* |
| 65 |
* - no_query_jumble: Does not support JumbleQuery() at all. |
| 66 |
* |
| 67 |
* - no_read: Does not support nodeRead() at all. |
| 68 |
* |
| 69 |
* - nodetag_only: Does not support copyObject(), equal(), jumbleQuery() |
| 70 |
* outNode() or nodeRead(). |
| 71 |
* |
| 72 |
* - special_read_write: Has special treatment in outNode() and nodeRead(). |
| 73 |
* |
| 74 |
* - nodetag_number(VALUE): assign the specified nodetag number instead of |
| 75 |
* an auto-generated number. Typically this would only be used in stable |
| 76 |
* branches, to give a newly-added node type a number without breaking ABI |
| 77 |
* by changing the numbers of existing node types. |
| 78 |
* |
| 79 |
* Node types can be supertypes of other types whether or not they are marked |
| 80 |
* abstract: if a node struct appears as the first field of another struct |
| 81 |
* type, then it is the supertype of that type. The no_copy, no_equal, |
| 82 |
* no_query_jumble and no_read node attributes are automatically inherited |
| 83 |
* from the supertype. (Notice that nodetag_only does not inherit, so it's |
| 84 |
* not quite equivalent to a combination of other attributes.) |
| 85 |
* |
| 86 |
* Valid node field attributes: |
| 87 |
* |
| 88 |
* - array_size(OTHERFIELD): This field is a dynamically allocated array with |
| 89 |
* size indicated by the mentioned other field. The other field is either a |
| 90 |
* scalar or a list, in which case the length of the list is used. |
| 91 |
* |
| 92 |
* - copy_as(VALUE): In copyObject(), replace the field's value with VALUE. |
| 93 |
* |
| 94 |
* - copy_as_scalar: In copyObject(), copy the field as a scalar value |
| 95 |
* (e.g. a pointer) even if it is a node-type pointer. |
| 96 |
* |
| 97 |
* - equal_as_scalar: In equal(), compare the field as a scalar value |
| 98 |
* even if it is a node-type pointer. |
| 99 |
* |
| 100 |
* - equal_ignore: Ignore the field for equality. |
| 101 |
* |
| 102 |
* - equal_ignore_if_zero: Ignore the field for equality if it is zero. |
| 103 |
* (Otherwise, compare normally.) |
| 104 |
* |
| 105 |
* - custom_query_jumble: Has custom implementation in queryjumblefuncs.c |
| 106 |
* for the field of a node. Also available as a node attribute. |
| 107 |
* |
| 108 |
* - query_jumble_ignore: Ignore the field for the query jumbling. Note |
| 109 |
* that typmod and collation information are usually irrelevant for the |
| 110 |
* query jumbling. |
| 111 |
* |
| 112 |
* - query_jumble_squash: Squash multiple values during query jumbling. |
| 113 |
* |
| 114 |
* - query_jumble_location: Mark the field as a location to track. This is |
| 115 |
* only allowed for integer fields that include "location" in their name. |
| 116 |
* |
| 117 |
* - read_as(VALUE): In nodeRead(), replace the field's value with VALUE. |
| 118 |
* |
| 119 |
* - read_write_ignore: Ignore the field for read/write. This is only allowed |
| 120 |
* if the node type is marked no_read or read_as() is also specified. |
| 121 |
* |
| 122 |
* - write_only_relids, write_only_nondefault_pathtarget, write_only_req_outer: |
| 123 |
* Special handling for Path struct; see there. |
| 124 |
* |
| 125 |
*/ |
| 126 |
#define pg_node_attr(...) |
| 127 |
|
| 128 |
/* |
| 129 |
* The first field of a node of any type is guaranteed to be the NodeTag. |
| 130 |
* Hence the type of any node can be gotten by casting it to Node. Declaring |
| 131 |
* a variable to be of Node * (instead of void *) can also facilitate |
| 132 |
* debugging. |
| 133 |
*/ |
| 134 |
typedef struct Node |
| 135 |
{ |
| 136 |
NodeTag type; |
| 137 |
} Node; |
| 138 |
|
| 139 |
#define nodeTag(nodeptr) (((const Node*)(nodeptr))->type) |
| 140 |
|
| 141 |
/* |
| 142 |
* newNode - |
| 143 |
* create a new node of the specified size and tag the node with the |
| 144 |
* specified tag. |
| 145 |
* |
| 146 |
* !WARNING!: Avoid using newNode directly. You should be using the |
| 147 |
* macro makeNode. eg. to create a Query node, use makeNode(Query) |
| 148 |
*/ |
| 149 |
static inline Node * |
| 150 |
newNode(size_t size, NodeTag tag) |
| 151 |
{ |
| 152 |
Node *result; |
| 153 |
|
| 154 |
Assert(size >= sizeof(Node)); /* need the tag, at least */ |
| 155 |
result = (Node *) palloc0(size); |
| 156 |
result->type = tag; |
| 157 |
|
| 158 |
return result; |
| 159 |
} |
| 160 |
|
| 161 |
#define makeNode(_type_) ((_type_ *) newNode(sizeof(_type_),T_##_type_)) |
| 162 |
#define NodeSetTag(nodeptr,t) (((Node*)(nodeptr))->type = (t)) |
| 163 |
|
| 164 |
#define IsA(nodeptr,_type_) (nodeTag(nodeptr) == T_##_type_) |
| 165 |
|
| 166 |
/* |
| 167 |
* castNode(type, ptr) casts ptr to "type *", and if assertions are enabled, |
| 168 |
* verifies that the node has the appropriate type (using its nodeTag()). |
| 169 |
* |
| 170 |
* Use an inline function when assertions are enabled, to avoid multiple |
| 171 |
* evaluations of the ptr argument (which could e.g. be a function call). |
| 172 |
*/ |
| 173 |
#ifdef USE_ASSERT_CHECKING |
| 174 |
static inline Node * |
| 175 |
castNodeImpl(NodeTag type, void *ptr) |
| 176 |
{ |
| 177 |
Assert(ptr == NULL || nodeTag(ptr) == type); |
| 178 |
return (Node *) ptr; |
| 179 |
} |
| 180 |
#define castNode(_type_, nodeptr) ((_type_ *) castNodeImpl(T_##_type_, nodeptr)) |
| 181 |
#else |
| 182 |
#define castNode(_type_, nodeptr) ((_type_ *) (nodeptr)) |
| 183 |
#endif /* USE_ASSERT_CHECKING */ |
| 184 |
|
| 185 |
|
| 186 |
/* ---------------------------------------------------------------- |
| 187 |
* extern declarations follow |
| 188 |
* ---------------------------------------------------------------- |
| 189 |
*/ |
| 190 |
|
| 191 |
/* |
| 192 |
* nodes/{outfuncs.c,print.c} |
| 193 |
*/ |
| 194 |
struct Bitmapset; /* not to include bitmapset.h here */ |
| 195 |
struct StringInfoData; /* not to include stringinfo.h here */ |
| 196 |
|
| 197 |
extern void outNode(struct StringInfoData *str, const void *obj); |
| 198 |
extern void outToken(struct StringInfoData *str, const char *s); |
| 199 |
extern void outBitmapset(struct StringInfoData *str, |
| 200 |
const struct Bitmapset *bms); |
| 201 |
extern void outDatum(struct StringInfoData *str, uintptr_t value, |
| 202 |
int typlen, bool typbyval); |
| 203 |
extern char *nodeToString(const void *obj); |
| 204 |
extern char *nodeToStringWithLocations(const void *obj); |
| 205 |
extern char *bmsToString(const struct Bitmapset *bms); |
| 206 |
|
| 207 |
/* |
| 208 |
* nodes/{readfuncs.c,read.c} |
| 209 |
*/ |
| 210 |
extern void *stringToNode(const char *str); |
| 211 |
#ifdef DEBUG_NODE_TESTS_ENABLED |
| 212 |
extern void *stringToNodeWithLocations(const char *str); |
| 213 |
#endif |
| 214 |
extern struct Bitmapset *readBitmapset(void); |
| 215 |
extern uintptr_t readDatum(bool typbyval); |
| 216 |
extern bool *readBoolCols(int numCols); |
| 217 |
extern int *readIntCols(int numCols); |
| 218 |
extern Oid *readOidCols(int numCols); |
| 219 |
extern int16 *readAttrNumberCols(int numCols); |
| 220 |
|
| 221 |
/* |
| 222 |
* nodes/copyfuncs.c |
| 223 |
*/ |
| 224 |
extern void *copyObjectImpl(const void *from); |
| 225 |
|
| 226 |
/* cast result back to argument type, if supported by compiler */ |
| 227 |
#ifdef HAVE_TYPEOF |
| 228 |
#define copyObject(obj) ((typeof(obj)) copyObjectImpl(obj)) |
| 229 |
#else |
| 230 |
#define copyObject(obj) copyObjectImpl(obj) |
| 231 |
#endif |
| 232 |
|
| 233 |
/* |
| 234 |
* nodes/equalfuncs.c |
| 235 |
*/ |
| 236 |
extern bool equal(const void *a, const void *b); |
| 237 |
|
| 238 |
|
| 239 |
/* |
| 240 |
* Typedef for parse location. This is just an int, but this way |
| 241 |
* gen_node_support.pl knows which fields should get special treatment for |
| 242 |
* location values. |
| 243 |
* |
| 244 |
* -1 is used for unknown. |
| 245 |
*/ |
| 246 |
typedef int ParseLoc; |
| 247 |
|
| 248 |
/* |
| 249 |
* Typedefs for identifying qualifier selectivities, plan costs, and row |
| 250 |
* counts as such. These are just plain "double"s, but declaring a variable |
| 251 |
* as Selectivity, Cost, or Cardinality makes the intent more obvious. |
| 252 |
* |
| 253 |
* These could have gone into plannodes.h or some such, but many files |
| 254 |
* depend on them... |
| 255 |
*/ |
| 256 |
typedef double Selectivity; /* fraction of tuples a qualifier will pass */ |
| 257 |
typedef double Cost; /* execution cost (in page-access units) */ |
| 258 |
typedef double Cardinality; /* (estimated) number of rows or other integer |
| 259 |
* count */ |
| 260 |
|
| 261 |
|
| 262 |
/* |
| 263 |
* CmdType - |
| 264 |
* enums for type of operation represented by a Query or PlannedStmt |
| 265 |
* |
| 266 |
* This is needed in both parsenodes.h and plannodes.h, so put it here... |
| 267 |
*/ |
| 268 |
typedef enum CmdType |
| 269 |
{ |
| 270 |
CMD_UNKNOWN, |
| 271 |
CMD_SELECT, /* select stmt */ |
| 272 |
CMD_UPDATE, /* update stmt */ |
| 273 |
CMD_INSERT, /* insert stmt */ |
| 274 |
CMD_DELETE, /* delete stmt */ |
| 275 |
CMD_MERGE, /* merge stmt */ |
| 276 |
CMD_UTILITY, /* cmds like create, destroy, copy, vacuum, |
| 277 |
* etc. */ |
| 278 |
CMD_NOTHING, /* dummy command for instead nothing rules |
| 279 |
* with qual */ |
| 280 |
} CmdType; |
| 281 |
|
| 282 |
|
| 283 |
/* |
| 284 |
* JoinType - |
| 285 |
* enums for types of relation joins |
| 286 |
* |
| 287 |
* JoinType determines the exact semantics of joining two relations using |
| 288 |
* a matching qualification. For example, it tells what to do with a tuple |
| 289 |
* that has no match in the other relation. |
| 290 |
* |
| 291 |
* This is needed in both parsenodes.h and plannodes.h, so put it here... |
| 292 |
*/ |
| 293 |
typedef enum JoinType |
| 294 |
{ |
| 295 |
/* |
| 296 |
* The canonical kinds of joins according to the SQL JOIN syntax. Only |
| 297 |
* these codes can appear in parser output (e.g., JoinExpr nodes). |
| 298 |
*/ |
| 299 |
JOIN_INNER, /* matching tuple pairs only */ |
| 300 |
JOIN_LEFT, /* pairs + unmatched LHS tuples */ |
| 301 |
JOIN_FULL, /* pairs + unmatched LHS + unmatched RHS */ |
| 302 |
JOIN_RIGHT, /* pairs + unmatched RHS tuples */ |
| 303 |
|
| 304 |
/* |
| 305 |
* Semijoins and anti-semijoins (as defined in relational theory) do not |
| 306 |
* appear in the SQL JOIN syntax, but there are standard idioms for |
| 307 |
* representing them (e.g., using EXISTS). The planner recognizes these |
| 308 |
* cases and converts them to joins. So the planner and executor must |
| 309 |
* support these codes. NOTE: in JOIN_SEMI output, it is unspecified |
| 310 |
* which matching RHS row is joined to. In JOIN_ANTI output, the row is |
| 311 |
* guaranteed to be null-extended. |
| 312 |
*/ |
| 313 |
JOIN_SEMI, /* 1 copy of each LHS row that has match(es) */ |
| 314 |
JOIN_ANTI, /* 1 copy of each LHS row that has no match */ |
| 315 |
JOIN_RIGHT_SEMI, /* 1 copy of each RHS row that has match(es) */ |
| 316 |
JOIN_RIGHT_ANTI, /* 1 copy of each RHS row that has no match */ |
| 317 |
|
| 318 |
/* |
| 319 |
* These codes are used internally in the planner, but are not supported |
| 320 |
* by the executor (nor, indeed, by most of the planner). |
| 321 |
*/ |
| 322 |
JOIN_UNIQUE_OUTER, /* LHS path must be made unique */ |
| 323 |
JOIN_UNIQUE_INNER, /* RHS path must be made unique */ |
| 324 |
|
| 325 |
/* |
| 326 |
* We might need additional join types someday. |
| 327 |
*/ |
| 328 |
} JoinType; |
| 329 |
|
| 330 |
/* |
| 331 |
* OUTER joins are those for which pushed-down quals must behave differently |
| 332 |
* from the join's own quals. This is in fact everything except INNER, SEMI |
| 333 |
* and RIGHT_SEMI joins. However, this macro must also exclude the |
| 334 |
* JOIN_UNIQUE symbols since those are temporary proxies for what will |
| 335 |
* eventually be an INNER join. |
| 336 |
* |
| 337 |
* Note: semijoins are a hybrid case, but we choose to treat them as not |
| 338 |
* being outer joins. This is okay principally because the SQL syntax makes |
| 339 |
* it impossible to have a pushed-down qual that refers to the inner relation |
| 340 |
* of a semijoin; so there is no strong need to distinguish join quals from |
| 341 |
* pushed-down quals. This is convenient because for almost all purposes, |
| 342 |
* quals attached to a semijoin can be treated the same as innerjoin quals. |
| 343 |
*/ |
| 344 |
#define IS_OUTER_JOIN(jointype) \ |
| 345 |
(((1 << (jointype)) & \ |
| 346 |
((1 << JOIN_LEFT) | \ |
| 347 |
(1 << JOIN_FULL) | \ |
| 348 |
(1 << JOIN_RIGHT) | \ |
| 349 |
(1 << JOIN_ANTI) | \ |
| 350 |
(1 << JOIN_RIGHT_ANTI))) != 0) |
| 351 |
|
| 352 |
/* |
| 353 |
* AggStrategy - |
| 354 |
* overall execution strategies for Agg plan nodes |
| 355 |
* |
| 356 |
* This is needed in both pathnodes.h and plannodes.h, so put it here... |
| 357 |
*/ |
| 358 |
typedef enum AggStrategy |
| 359 |
{ |
| 360 |
AGG_PLAIN, /* simple agg across all input rows */ |
| 361 |
AGG_SORTED, /* grouped agg, input must be sorted */ |
| 362 |
AGG_HASHED, /* grouped agg, use internal hashtable */ |
| 363 |
AGG_MIXED, /* grouped agg, hash and sort both used */ |
| 364 |
} AggStrategy; |
| 365 |
|
| 366 |
/* |
| 367 |
* AggSplit - |
| 368 |
* splitting (partial aggregation) modes for Agg plan nodes |
| 369 |
* |
| 370 |
* This is needed in both pathnodes.h and plannodes.h, so put it here... |
| 371 |
*/ |
| 372 |
|
| 373 |
/* Primitive options supported by nodeAgg.c: */ |
| 374 |
#define AGGSPLITOP_COMBINE 0x01 /* substitute combinefn for transfn */ |
| 375 |
#define AGGSPLITOP_SKIPFINAL 0x02 /* skip finalfn, return state as-is */ |
| 376 |
#define AGGSPLITOP_SERIALIZE 0x04 /* apply serialfn to output */ |
| 377 |
#define AGGSPLITOP_DESERIALIZE 0x08 /* apply deserialfn to input */ |
| 378 |
|
| 379 |
/* Supported operating modes (i.e., useful combinations of these options): */ |
| 380 |
typedef enum AggSplit |
| 381 |
{ |
| 382 |
/* Basic, non-split aggregation: */ |
| 383 |
AGGSPLIT_SIMPLE = 0, |
| 384 |
/* Initial phase of partial aggregation, with serialization: */ |
| 385 |
AGGSPLIT_INITIAL_SERIAL = AGGSPLITOP_SKIPFINAL | AGGSPLITOP_SERIALIZE, |
| 386 |
/* Final phase of partial aggregation, with deserialization: */ |
| 387 |
AGGSPLIT_FINAL_DESERIAL = AGGSPLITOP_COMBINE | AGGSPLITOP_DESERIALIZE, |
| 388 |
} AggSplit; |
| 389 |
|
| 390 |
/* Test whether an AggSplit value selects each primitive option: */ |
| 391 |
#define DO_AGGSPLIT_COMBINE(as) (((as) & AGGSPLITOP_COMBINE) != 0) |
| 392 |
#define DO_AGGSPLIT_SKIPFINAL(as) (((as) & AGGSPLITOP_SKIPFINAL) != 0) |
| 393 |
#define DO_AGGSPLIT_SERIALIZE(as) (((as) & AGGSPLITOP_SERIALIZE) != 0) |
| 394 |
#define DO_AGGSPLIT_DESERIALIZE(as) (((as) & AGGSPLITOP_DESERIALIZE) != 0) |
| 395 |
|
| 396 |
/* |
| 397 |
* SetOpCmd and SetOpStrategy - |
| 398 |
* overall semantics and execution strategies for SetOp plan nodes |
| 399 |
* |
| 400 |
* This is needed in both pathnodes.h and plannodes.h, so put it here... |
| 401 |
*/ |
| 402 |
typedef enum SetOpCmd |
| 403 |
{ |
| 404 |
SETOPCMD_INTERSECT, |
| 405 |
SETOPCMD_INTERSECT_ALL, |
| 406 |
SETOPCMD_EXCEPT, |
| 407 |
SETOPCMD_EXCEPT_ALL, |
| 408 |
} SetOpCmd; |
| 409 |
|
| 410 |
typedef enum SetOpStrategy |
| 411 |
{ |
| 412 |
SETOP_SORTED, /* input must be sorted */ |
| 413 |
SETOP_HASHED, /* use internal hashtable */ |
| 414 |
} SetOpStrategy; |
| 415 |
|
| 416 |
/* |
| 417 |
* OnConflictAction - |
| 418 |
* "ON CONFLICT" clause type of query |
| 419 |
* |
| 420 |
* This is needed in both parsenodes.h and plannodes.h, so put it here... |
| 421 |
*/ |
| 422 |
typedef enum OnConflictAction |
| 423 |
{ |
| 424 |
ONCONFLICT_NONE, /* No "ON CONFLICT" clause */ |
| 425 |
ONCONFLICT_NOTHING, /* ON CONFLICT ... DO NOTHING */ |
| 426 |
ONCONFLICT_UPDATE, /* ON CONFLICT ... DO UPDATE */ |
| 427 |
} OnConflictAction; |
| 428 |
|
| 429 |
/* |
| 430 |
* LimitOption - |
| 431 |
* LIMIT option of query |
| 432 |
* |
| 433 |
* This is needed in both parsenodes.h and plannodes.h, so put it here... |
| 434 |
*/ |
| 435 |
typedef enum LimitOption |
| 436 |
{ |
| 437 |
LIMIT_OPTION_COUNT, /* FETCH FIRST... ONLY */ |
| 438 |
LIMIT_OPTION_WITH_TIES, /* FETCH FIRST... WITH TIES */ |
| 439 |
} LimitOption; |
| 440 |
|
| 441 |
#endif /* NODES_H */ |