Line data Source code
1 : /*-------------------------------------------------------------------------
2 : *
3 : * nodes.h
4 : * Definitions for tagged nodes.
5 : *
6 : *
7 : * Portions Copyright (c) 1996-2026, 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 query jumbling.
109 : *
110 : * - query_jumble_squash: Squash multiple values during query jumbling.
111 : *
112 : * - query_jumble_location: Mark the field as a location to track. This is
113 : * only used for fields of type ParseLoc, which otherwise are not jumbled.
114 : *
115 : * - read_as(VALUE): In nodeRead(), replace the field's value with VALUE.
116 : *
117 : * - read_write_ignore: Ignore the field for read/write. This is only allowed
118 : * if the node type is marked no_read or read_as() is also specified.
119 : *
120 : * - write_only_relids, write_only_nondefault_pathtarget, write_only_req_outer:
121 : * Special handling for Path struct; see there.
122 : *
123 : */
124 : #define pg_node_attr(...)
125 :
126 : /*
127 : * The first field of a node of any type is guaranteed to be the NodeTag.
128 : * Hence the type of any node can be gotten by casting it to Node. Declaring
129 : * a variable to be of Node * (instead of void *) can also facilitate
130 : * debugging.
131 : */
132 : typedef struct Node
133 : {
134 : NodeTag type;
135 : } Node;
136 :
137 : #define nodeTag(nodeptr) (((const Node*)(nodeptr))->type)
138 :
139 : /*
140 : * newNode -
141 : * create a new node of the specified size and tag the node with the
142 : * specified tag.
143 : *
144 : * !WARNING!: Avoid using newNode directly. You should be using the
145 : * macro makeNode. eg. to create a Query node, use makeNode(Query)
146 : */
147 : static inline Node *
148 184456306 : newNode(size_t size, NodeTag tag)
149 : {
150 : Node *result;
151 :
152 : Assert(size >= sizeof(Node)); /* need the tag, at least */
153 184456306 : result = (Node *) palloc0(size);
154 184456306 : result->type = tag;
155 :
156 184456306 : return result;
157 : }
158 :
159 : #define makeNode(_type_) ((_type_ *) newNode(sizeof(_type_),T_##_type_))
160 : #define NodeSetTag(nodeptr,t) (((Node*)(nodeptr))->type = (t))
161 :
162 : #define IsA(nodeptr,_type_) (nodeTag(nodeptr) == T_##_type_)
163 :
164 : /*
165 : * castNode(type, ptr) casts ptr to "type *", and if assertions are enabled,
166 : * verifies that the node has the appropriate type (using its nodeTag()).
167 : *
168 : * Use an inline function when assertions are enabled, to avoid multiple
169 : * evaluations of the ptr argument (which could e.g. be a function call).
170 : */
171 : #ifdef USE_ASSERT_CHECKING
172 : static inline Node *
173 : castNodeImpl(NodeTag type, void *ptr)
174 : {
175 : Assert(ptr == NULL || nodeTag(ptr) == type);
176 : return (Node *) ptr;
177 : }
178 : #define castNode(_type_, nodeptr) ((_type_ *) castNodeImpl(T_##_type_, nodeptr))
179 : #else
180 : #define castNode(_type_, nodeptr) ((_type_ *) (nodeptr))
181 : #endif /* USE_ASSERT_CHECKING */
182 :
183 :
184 : /* ----------------------------------------------------------------
185 : * extern declarations follow
186 : * ----------------------------------------------------------------
187 : */
188 :
189 : #ifndef FRONTEND
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, Datum 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/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 :
215 : /*
216 : * nodes/copyfuncs.c
217 : */
218 : extern void *copyObjectImpl(const void *from);
219 :
220 : /* cast result back to argument type, if supported by compiler */
221 : #ifdef HAVE_TYPEOF_UNQUAL
222 : #define copyObject(obj) ((typeof_unqual(*(obj)) *) copyObjectImpl(obj))
223 : #else
224 : #define copyObject(obj) copyObjectImpl(obj)
225 : #endif
226 :
227 : /*
228 : * nodes/equalfuncs.c
229 : */
230 : extern bool equal(const void *a, const void *b);
231 :
232 : #endif /* !FRONTEND */
233 :
234 :
235 : /*
236 : * Typedef for parse location. This is just an int, but this way
237 : * gen_node_support.pl knows which fields should get special treatment for
238 : * location values.
239 : *
240 : * -1 is used for unknown.
241 : */
242 : typedef int ParseLoc;
243 :
244 : /*
245 : * Typedefs for identifying qualifier selectivities, plan costs, and row
246 : * counts as such. These are just plain "double"s, but declaring a variable
247 : * as Selectivity, Cost, or Cardinality makes the intent more obvious.
248 : *
249 : * These could have gone into plannodes.h or some such, but many files
250 : * depend on them...
251 : */
252 : typedef double Selectivity; /* fraction of tuples a qualifier will pass */
253 : typedef double Cost; /* execution cost (in page-access units) */
254 : typedef double Cardinality; /* (estimated) number of rows or other integer
255 : * count */
256 :
257 :
258 : /*
259 : * CmdType -
260 : * enums for type of operation represented by a Query or PlannedStmt
261 : *
262 : * This is needed in both parsenodes.h and plannodes.h, so put it here...
263 : */
264 : typedef enum CmdType
265 : {
266 : CMD_UNKNOWN,
267 : CMD_SELECT, /* select stmt */
268 : CMD_UPDATE, /* update stmt */
269 : CMD_INSERT, /* insert stmt */
270 : CMD_DELETE, /* delete stmt */
271 : CMD_MERGE, /* merge stmt */
272 : CMD_UTILITY, /* cmds like create, destroy, copy, vacuum,
273 : * etc. */
274 : CMD_NOTHING, /* dummy command for instead nothing rules
275 : * with qual */
276 : } CmdType;
277 :
278 :
279 : /*
280 : * JoinType -
281 : * enums for types of relation joins
282 : *
283 : * JoinType determines the exact semantics of joining two relations using
284 : * a matching qualification. For example, it tells what to do with a tuple
285 : * that has no match in the other relation.
286 : *
287 : * This is needed in both parsenodes.h and plannodes.h, so put it here...
288 : */
289 : typedef enum JoinType
290 : {
291 : /*
292 : * The canonical kinds of joins according to the SQL JOIN syntax. Only
293 : * these codes can appear in parser output (e.g., JoinExpr nodes).
294 : */
295 : JOIN_INNER, /* matching tuple pairs only */
296 : JOIN_LEFT, /* pairs + unmatched LHS tuples */
297 : JOIN_FULL, /* pairs + unmatched LHS + unmatched RHS */
298 : JOIN_RIGHT, /* pairs + unmatched RHS tuples */
299 :
300 : /*
301 : * Semijoins and anti-semijoins (as defined in relational theory) do not
302 : * appear in the SQL JOIN syntax, but there are standard idioms for
303 : * representing them (e.g., using EXISTS). The planner recognizes these
304 : * cases and converts them to joins. So the planner and executor must
305 : * support these codes. NOTE: in JOIN_SEMI output, it is unspecified
306 : * which matching RHS row is joined to. In JOIN_ANTI output, the row is
307 : * guaranteed to be null-extended.
308 : */
309 : JOIN_SEMI, /* 1 copy of each LHS row that has match(es) */
310 : JOIN_ANTI, /* 1 copy of each LHS row that has no match */
311 : JOIN_RIGHT_SEMI, /* 1 copy of each RHS row that has match(es) */
312 : JOIN_RIGHT_ANTI, /* 1 copy of each RHS row that has no match */
313 :
314 : /*
315 : * These codes are used internally in the planner, but are not supported
316 : * by the executor (nor, indeed, by most of the planner).
317 : */
318 : JOIN_UNIQUE_OUTER, /* LHS has be made unique */
319 : JOIN_UNIQUE_INNER, /* RHS has be made unique */
320 :
321 : /*
322 : * We might need additional join types someday.
323 : */
324 : } JoinType;
325 :
326 : /*
327 : * OUTER joins are those for which pushed-down quals must behave differently
328 : * from the join's own quals. This is in fact everything except INNER, SEMI
329 : * and RIGHT_SEMI joins. However, this macro must also exclude the
330 : * JOIN_UNIQUE symbols since those are temporary proxies for what will
331 : * eventually be an INNER join.
332 : *
333 : * Note: semijoins are a hybrid case, but we choose to treat them as not
334 : * being outer joins. This is okay principally because the SQL syntax makes
335 : * it impossible to have a pushed-down qual that refers to the inner relation
336 : * of a semijoin; so there is no strong need to distinguish join quals from
337 : * pushed-down quals. This is convenient because for almost all purposes,
338 : * quals attached to a semijoin can be treated the same as innerjoin quals.
339 : */
340 : #define IS_OUTER_JOIN(jointype) \
341 : (((1 << (jointype)) & \
342 : ((1 << JOIN_LEFT) | \
343 : (1 << JOIN_FULL) | \
344 : (1 << JOIN_RIGHT) | \
345 : (1 << JOIN_ANTI) | \
346 : (1 << JOIN_RIGHT_ANTI))) != 0)
347 :
348 : /*
349 : * AggStrategy -
350 : * overall execution strategies for Agg plan nodes
351 : *
352 : * This is needed in both pathnodes.h and plannodes.h, so put it here...
353 : */
354 : typedef enum AggStrategy
355 : {
356 : AGG_PLAIN, /* simple agg across all input rows */
357 : AGG_SORTED, /* grouped agg, input must be sorted */
358 : AGG_HASHED, /* grouped agg, use internal hashtable */
359 : AGG_MIXED, /* grouped agg, hash and sort both used */
360 : } AggStrategy;
361 :
362 : /*
363 : * AggSplit -
364 : * splitting (partial aggregation) modes for Agg plan nodes
365 : *
366 : * This is needed in both pathnodes.h and plannodes.h, so put it here...
367 : */
368 :
369 : /* Primitive options supported by nodeAgg.c: */
370 : #define AGGSPLITOP_COMBINE 0x01 /* substitute combinefn for transfn */
371 : #define AGGSPLITOP_SKIPFINAL 0x02 /* skip finalfn, return state as-is */
372 : #define AGGSPLITOP_SERIALIZE 0x04 /* apply serialfn to output */
373 : #define AGGSPLITOP_DESERIALIZE 0x08 /* apply deserialfn to input */
374 :
375 : /* Supported operating modes (i.e., useful combinations of these options): */
376 : typedef enum AggSplit
377 : {
378 : /* Basic, non-split aggregation: */
379 : AGGSPLIT_SIMPLE = 0,
380 : /* Initial phase of partial aggregation, with serialization: */
381 : AGGSPLIT_INITIAL_SERIAL = AGGSPLITOP_SKIPFINAL | AGGSPLITOP_SERIALIZE,
382 : /* Final phase of partial aggregation, with deserialization: */
383 : AGGSPLIT_FINAL_DESERIAL = AGGSPLITOP_COMBINE | AGGSPLITOP_DESERIALIZE,
384 : } AggSplit;
385 :
386 : /* Test whether an AggSplit value selects each primitive option: */
387 : #define DO_AGGSPLIT_COMBINE(as) (((as) & AGGSPLITOP_COMBINE) != 0)
388 : #define DO_AGGSPLIT_SKIPFINAL(as) (((as) & AGGSPLITOP_SKIPFINAL) != 0)
389 : #define DO_AGGSPLIT_SERIALIZE(as) (((as) & AGGSPLITOP_SERIALIZE) != 0)
390 : #define DO_AGGSPLIT_DESERIALIZE(as) (((as) & AGGSPLITOP_DESERIALIZE) != 0)
391 :
392 : /*
393 : * SetOpCmd and SetOpStrategy -
394 : * overall semantics and execution strategies for SetOp plan nodes
395 : *
396 : * This is needed in both pathnodes.h and plannodes.h, so put it here...
397 : */
398 : typedef enum SetOpCmd
399 : {
400 : SETOPCMD_INTERSECT,
401 : SETOPCMD_INTERSECT_ALL,
402 : SETOPCMD_EXCEPT,
403 : SETOPCMD_EXCEPT_ALL,
404 : } SetOpCmd;
405 :
406 : typedef enum SetOpStrategy
407 : {
408 : SETOP_SORTED, /* input must be sorted */
409 : SETOP_HASHED, /* use internal hashtable */
410 : } SetOpStrategy;
411 :
412 : /*
413 : * OnConflictAction -
414 : * "ON CONFLICT" clause type of query
415 : *
416 : * This is needed in both parsenodes.h and plannodes.h, so put it here...
417 : */
418 : typedef enum OnConflictAction
419 : {
420 : ONCONFLICT_NONE, /* No "ON CONFLICT" clause */
421 : ONCONFLICT_NOTHING, /* ON CONFLICT ... DO NOTHING */
422 : ONCONFLICT_UPDATE, /* ON CONFLICT ... DO UPDATE */
423 : ONCONFLICT_SELECT, /* ON CONFLICT ... DO SELECT */
424 : } OnConflictAction;
425 :
426 : /*
427 : * LimitOption -
428 : * LIMIT option of query
429 : *
430 : * This is needed in both parsenodes.h and plannodes.h, so put it here...
431 : */
432 : typedef enum LimitOption
433 : {
434 : LIMIT_OPTION_COUNT, /* FETCH FIRST... ONLY */
435 : LIMIT_OPTION_WITH_TIES, /* FETCH FIRST... WITH TIES */
436 : } LimitOption;
437 :
438 : #endif /* NODES_H */
|
