PostgreSQL Source Code git master
supportnodes.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * supportnodes.h
4 * Definitions for planner support functions.
5 *
6 * This file defines the API for "planner support functions", which
7 * are SQL functions (normally written in C) that can be attached to
8 * another "target" function to give the system additional knowledge
9 * about the target function. The name is now something of a misnomer,
10 * since some of the call sites are in the executor not the planner,
11 * but "function support function" would be a confusing name so we
12 * stick with "planner support function".
13 *
14 * A support function must have the SQL signature
15 * supportfn(internal) returns internal
16 * The argument is a pointer to one of the Node types defined in this file.
17 * The result is usually also a Node pointer, though its type depends on
18 * which capability is being invoked. In all cases, a NULL pointer result
19 * (that's PG_RETURN_POINTER(NULL), not PG_RETURN_NULL()) indicates that
20 * the support function cannot do anything useful for the given request.
21 * Support functions must return a NULL pointer, not fail, if they do not
22 * recognize the request node type or cannot handle the given case; this
23 * allows for future extensions of the set of request cases.
24 *
25 *
26 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
27 * Portions Copyright (c) 1994, Regents of the University of California
28 *
29 * src/include/nodes/supportnodes.h
30 *
31 *-------------------------------------------------------------------------
32 */
33#ifndef SUPPORTNODES_H
34#define SUPPORTNODES_H
35
36#include "nodes/plannodes.h"
37
38typedef struct PlannerInfo PlannerInfo; /* avoid including pathnodes.h here */
42typedef struct RangeTblFunction RangeTblFunction; /* ditto for parsenodes.h */
43typedef struct HeapTupleData *HeapTuple; /* and htup.h too */
44
45/*
46 * The Simplify request allows the support function to perform plan-time
47 * simplification of a call to its target function. For example, a varchar
48 * length coercion that does not decrease the allowed length of its argument
49 * could be replaced by a RelabelType node, or "x + 0" could be replaced by
50 * "x". This is invoked during the planner's constant-folding pass, so the
51 * function's arguments can be presumed already simplified.
52 *
53 * The planner's PlannerInfo "root" is typically not needed, but can be
54 * consulted if it's necessary to obtain info about Vars present in
55 * the given node tree. Beware that root could be NULL in some usages.
56 *
57 * "fcall" will be a FuncExpr invoking the support function's target
58 * function. (This is true even if the original parsetree node was an
59 * operator call; a FuncExpr is synthesized for this purpose.)
60 *
61 * The result should be a semantically-equivalent transformed node tree,
62 * or NULL if no simplification could be performed. Do *not* return or
63 * modify *fcall, as it isn't really a separately allocated Node. But
64 * it's okay to use fcall->args, or parts of it, in the result tree.
65 */
67{
69
70 PlannerInfo *root; /* Planner's infrastructure */
71 FuncExpr *fcall; /* Function call to be simplified */
73
74/*
75 * The InlineInFrom request allows the support function to perform plan-time
76 * simplification of a call to its target function that appears in FROM.
77 * The rules for this are sufficiently different from ordinary expressions
78 * that it's best to make this a separate request from Simplify.
79 *
80 * The planner's PlannerInfo "root" is typically not needed, but can be
81 * consulted if it's necessary to obtain info about Vars present in
82 * the given node tree. Beware that root could be NULL in some usages.
83 *
84 * "rtfunc" will be a RangeTblFunction node for the support function's target
85 * function. The call appeared alone (and without ORDINALITY) in FROM.
86 *
87 * "proc" will be the HeapTuple for the pg_proc row of the target function.
88 *
89 * The result should be a semantically-equivalent SELECT Query tree,
90 * or NULL if no simplification could be performed. The tree must have
91 * been passed through parse analysis and rewrite.
92 */
94{
96
97 PlannerInfo *root; /* Planner's infrastructure */
98 RangeTblFunction *rtfunc; /* Function call to be simplified */
99 HeapTuple proc; /* Function definition from pg_proc */
101
102/*
103 * The Selectivity request allows the support function to provide a
104 * selectivity estimate for a function appearing at top level of a WHERE
105 * clause (so it applies only to functions returning boolean).
106 *
107 * The input arguments are the same as are supplied to operator restriction
108 * and join estimators, except that we unify those two APIs into just one
109 * request type. See clause_selectivity() for the details.
110 *
111 * If an estimate can be made, store it into the "selectivity" field and
112 * return the address of the SupportRequestSelectivity node; the estimate
113 * must be between 0 and 1 inclusive. Return NULL if no estimate can be
114 * made (in which case the planner will fall back to a default estimate,
115 * traditionally 1/3).
116 *
117 * If the target function is being used as the implementation of an operator,
118 * the support function will not be used for this purpose; the operator's
119 * restriction or join estimator is consulted instead.
120 */
122{
124
125 /* Input fields: */
126 PlannerInfo *root; /* Planner's infrastructure */
127 Oid funcid; /* function we are inquiring about */
128 List *args; /* pre-simplified arguments to function */
129 Oid inputcollid; /* function's input collation */
130 bool is_join; /* is this a join or restriction case? */
131 int varRelid; /* if restriction, RTI of target relation */
132 JoinType jointype; /* if join, outer join type */
133 SpecialJoinInfo *sjinfo; /* if outer join, info about join */
134
135 /* Output fields: */
136 Selectivity selectivity; /* returned selectivity estimate */
138
139/*
140 * The Cost request allows the support function to provide an execution
141 * cost estimate for its target function. The cost estimate can include
142 * both a one-time (query startup) component and a per-execution component.
143 * The estimate should *not* include the costs of evaluating the target
144 * function's arguments, only the target function itself.
145 *
146 * The "node" argument is normally the parse node that is invoking the
147 * target function. This is a FuncExpr in the simplest case, but it could
148 * also be an OpExpr, DistinctExpr, NullIfExpr, or WindowFunc, or possibly
149 * other cases in future. NULL is passed if the function cannot presume
150 * its arguments to be equivalent to what the calling node presents as
151 * arguments; that happens for, e.g., aggregate support functions and
152 * per-column comparison operators used by RowExprs.
153 *
154 * If an estimate can be made, store it into the cost fields and return the
155 * address of the SupportRequestCost node. Return NULL if no estimate can be
156 * made, in which case the planner will rely on the target function's procost
157 * field. (Note: while procost is automatically scaled by cpu_operator_cost,
158 * this is not the case for the outputs of the Cost request; the support
159 * function must scale its results appropriately on its own.)
160 */
161typedef struct SupportRequestCost
162{
164
165 /* Input fields: */
166 PlannerInfo *root; /* Planner's infrastructure (could be NULL) */
167 Oid funcid; /* function we are inquiring about */
168 Node *node; /* parse node invoking function, or NULL */
169
170 /* Output fields: */
171 Cost startup; /* one-time cost */
172 Cost per_tuple; /* per-evaluation cost */
174
175/*
176 * The Rows request allows the support function to provide an output rowcount
177 * estimate for its target function (so it applies only to set-returning
178 * functions).
179 *
180 * The "node" argument is the parse node that is invoking the target function;
181 * currently this will always be a FuncExpr or OpExpr.
182 *
183 * If an estimate can be made, store it into the rows field and return the
184 * address of the SupportRequestRows node. Return NULL if no estimate can be
185 * made, in which case the planner will rely on the target function's prorows
186 * field.
187 */
188typedef struct SupportRequestRows
189{
191
192 /* Input fields: */
193 PlannerInfo *root; /* Planner's infrastructure (could be NULL) */
194 Oid funcid; /* function we are inquiring about */
195 Node *node; /* parse node invoking function */
196
197 /* Output fields: */
198 double rows; /* number of rows expected to be returned */
200
201/*
202 * The IndexCondition request allows the support function to generate
203 * a directly-indexable condition based on a target function call that is
204 * not itself indexable. The target function call must appear at the top
205 * level of WHERE or JOIN/ON, so this applies only to functions returning
206 * boolean.
207 *
208 * The "node" argument is the parse node that is invoking the target function;
209 * currently this will always be a FuncExpr or OpExpr. The call is made
210 * only if at least one function argument matches an index column's variable
211 * or expression. "indexarg" identifies the matching argument (it's the
212 * argument's zero-based index in the node's args list).
213 *
214 * If the transformation is possible, return a List of directly-indexable
215 * condition expressions, else return NULL. (A List is used because it's
216 * sometimes useful to generate more than one indexable condition, such as
217 * when a LIKE with constant prefix gives rise to both >= and < conditions.)
218 *
219 * "Directly indexable" means that the condition must be directly executable
220 * by the index machinery. Typically this means that it is a binary OpExpr
221 * with the index column value on the left, a pseudo-constant on the right,
222 * and an operator that is in the index column's operator family. Other
223 * possibilities include RowCompareExpr, ScalarArrayOpExpr, and NullTest,
224 * depending on the index type; but those seem less likely to be useful for
225 * derived index conditions. "Pseudo-constant" means that the right-hand
226 * expression must not contain any volatile functions, nor any Vars of the
227 * table the index is for; use is_pseudo_constant_for_index() to check this.
228 * (Note: if the passed "node" is an OpExpr, the core planner already verified
229 * that the non-indexkey operand is pseudo-constant; but when the "node"
230 * is a FuncExpr, it does not check, since it doesn't know which of the
231 * function's arguments you might need to use in an index comparison value.)
232 *
233 * In many cases, an index condition can be generated but it is weaker than
234 * the function condition itself; for example, a LIKE with a constant prefix
235 * can produce an index range check based on the prefix, but we still need
236 * to execute the LIKE operator to verify the rest of the pattern. We say
237 * that such an index condition is "lossy". When returning an index condition,
238 * you should set the "lossy" request field to true if the condition is lossy,
239 * or false if it is an exact equivalent of the function's result. The core
240 * code will initialize that field to true, which is the common case.
241 *
242 * It is important to verify that the index operator family is the correct
243 * one for the condition you want to generate. Core support functions tend
244 * to use the known OID of a built-in opfamily for this, but extensions need
245 * to work harder, since their OIDs aren't fixed. A possibly workable
246 * answer for an index on an extension datatype is to verify the index AM's
247 * OID instead, and then assume that there's only one relevant opclass for
248 * your datatype so the opfamily must be the right one. Generating OpExpr
249 * nodes may also require knowing extension datatype OIDs (often you can
250 * find these out by applying exprType() to a function argument) and
251 * operator OIDs (which you can look up using get_opfamily_member).
252 */
254{
256
257 /* Input fields: */
258 PlannerInfo *root; /* Planner's infrastructure */
259 Oid funcid; /* function we are inquiring about */
260 Node *node; /* parse node invoking function */
261 int indexarg; /* index of function arg matching indexcol */
262 IndexOptInfo *index; /* planner's info about target index */
263 int indexcol; /* index of target index column (0-based) */
264 Oid opfamily; /* index column's operator family */
265 Oid indexcollation; /* index column's collation */
266
267 /* Output fields: */
268 bool lossy; /* set to false if index condition is an exact
269 * equivalent of the function call */
271
272/* ----------
273 * To support more efficient query execution of any monotonically increasing
274 * and/or monotonically decreasing window functions, we support calling the
275 * window function's prosupport function passing along this struct whenever
276 * the planner sees an OpExpr qual directly reference a window function in a
277 * subquery. When the planner encounters this, we populate this struct and
278 * pass it along to the window function's prosupport function so that it can
279 * evaluate if the given WindowFunc is;
280 *
281 * a) monotonically increasing, or
282 * b) monotonically decreasing, or
283 * c) both monotonically increasing and decreasing, or
284 * d) none of the above.
285 *
286 * A function that is monotonically increasing can never return a value that
287 * is lower than a value returned in a "previous call". A monotonically
288 * decreasing function can never return a value higher than a value returned
289 * in a previous call. A function that is both must return the same value
290 * each time.
291 *
292 * We define "previous call" to mean a previous call to the same WindowFunc
293 * struct in the same window partition.
294 *
295 * row_number() is an example of a monotonically increasing function. The
296 * return value will be reset back to 1 in each new partition. An example of
297 * a monotonically increasing and decreasing function is COUNT(*) OVER ().
298 * Since there is no ORDER BY clause in this example, all rows in the
299 * partition are peers and all rows within the partition will be within the
300 * frame bound. Likewise for COUNT(*) OVER(ORDER BY a ROWS BETWEEN UNBOUNDED
301 * PRECEDING AND UNBOUNDED FOLLOWING).
302 *
303 * COUNT(*) OVER (ORDER BY a ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING)
304 * is an example of a monotonically decreasing function.
305 *
306 * Implementations must only concern themselves with the given WindowFunc
307 * being monotonic in a single partition.
308 *
309 * Inputs:
310 * 'window_func' is the pointer to the window function being called.
311 *
312 * 'window_clause' pointer to the WindowClause data. Support functions can
313 * use this to check frame bounds, etc.
314 *
315 * Outputs:
316 * 'monotonic' the resulting MonotonicFunction value for the given input
317 * window function and window clause.
318 * ----------
319 */
321{
323
324 /* Input fields: */
325 WindowFunc *window_func; /* Pointer to the window function data */
326 WindowClause *window_clause; /* Pointer to the window clause data */
327
328 /* Output fields: */
331
332/*
333 * Some WindowFunc behavior might not be affected by certain variations in
334 * the WindowClause's frameOptions. For example, row_number() is coded in
335 * such a way that the frame options don't change the returned row number.
336 * nodeWindowAgg.c will have less work to do if the ROWS option is used
337 * instead of the RANGE option as no check needs to be done for peer rows.
338 * Since RANGE is included in the default frame options, window functions
339 * such as row_number() might want to change that to ROW.
340 *
341 * Here we allow a WindowFunc's support function to determine which, if
342 * anything, can be changed about the WindowClause which the WindowFunc
343 * belongs to. Currently only the frameOptions can be modified. However,
344 * we may want to allow more optimizations in the future.
345 *
346 * The support function is responsible for ensuring the optimized version of
347 * the frameOptions doesn't affect the result of the window function. The
348 * planner is responsible for only changing the frame options when all
349 * WindowFuncs using this particular WindowClause agree on what the optimized
350 * version of the frameOptions are. If a particular WindowFunc being used
351 * does not have a support function then the planner will not make any changes
352 * to the WindowClause's frameOptions.
353 *
354 * 'window_func' and 'window_clause' are set by the planner before calling the
355 * support function so that the support function has these fields available.
356 * These may be required in order to determine which optimizations are
357 * possible.
358 *
359 * 'frameOptions' is set by the planner to WindowClause.frameOptions. The
360 * support function must only adjust this if optimizations are possible for
361 * the given WindowFunc.
362 */
364{
366
367 /* Input fields: */
368 WindowFunc *window_func; /* Pointer to the window function data */
369 WindowClause *window_clause; /* Pointer to the window clause data */
370
371 /* Input/Output fields: */
372 int frameOptions; /* New frameOptions, or left untouched if no
373 * optimizations are possible. */
375
376/*
377 * The ModifyInPlace request allows the support function to detect whether
378 * a call to its target function can be allowed to modify a read/write
379 * expanded object in-place. The context is that we are considering a
380 * PL/pgSQL (or similar PL) assignment of the form "x := f(x, ...)" where
381 * the variable x is of a type that can be represented as an expanded object
382 * (see utils/expandeddatum.h). If f() can usefully optimize by modifying
383 * the passed-in object in-place, then this request can be implemented to
384 * instruct PL/pgSQL to pass a read-write expanded pointer to the variable's
385 * value. (Note that there is no guarantee that later calls to f() will
386 * actually do so. If f() receives a read-only pointer, or a pointer to a
387 * non-expanded object, it must follow the usual convention of not modifying
388 * the pointed-to object.) There are two requirements that must be met
389 * to make this safe:
390 * 1. f() must guarantee that it will not have modified the object if it
391 * fails. Otherwise the variable's value might change unexpectedly.
392 * 2. If the other arguments to f() ("..." in the above example) contain
393 * references to x, f() must be able to cope with that; or if that's not
394 * safe, the support function must scan the other arguments to verify that
395 * there are no other references to x. An example of the concern here is
396 * that in "arr := array_append(arr, arr[1])", if the array element type
397 * is pass-by-reference then array_append would receive a second argument
398 * that points into the array object it intends to modify. array_append is
399 * coded to make that safe, but other functions might not be able to cope.
400 *
401 * "args" is a node tree list representing the function's arguments.
402 * One or more nodes within the node tree will be PARAM_EXTERN Params
403 * with ID "paramid", which represent the assignment target variable.
404 * (Note that such references are not necessarily at top level in the list,
405 * for example we might have "x := f(x, g(x))". Generally it's only safe
406 * to optimize a reference that is at top level, else we're making promises
407 * about the behavior of g() as well as f().)
408 *
409 * If modify-in-place is safe, the support function should return the
410 * address of the Param node that is to return a read-write pointer.
411 * (At most one of the references is allowed to do so.) Otherwise,
412 * return NULL.
413 */
415{
417
418 Oid funcid; /* PG_PROC OID of the target function */
419 List *args; /* Arguments to the function */
420 int paramid; /* ID of Param(s) representing variable */
422
423#endif /* SUPPORTNODES_H */
double Cost
Definition: nodes.h:261
NodeTag
Definition: nodes.h:27
double Selectivity
Definition: nodes.h:260
JoinType
Definition: nodes.h:298
MonotonicFunction
Definition: plannodes.h:1817
unsigned int Oid
Definition: postgres_ext.h:32
Definition: pg_list.h:54
Definition: nodes.h:135
PlannerInfo * root
Definition: supportnodes.h:166
RangeTblFunction * rtfunc
Definition: supportnodes.h:98
PlannerInfo * root
Definition: supportnodes.h:193
SpecialJoinInfo * sjinfo
Definition: supportnodes.h:133
PlannerInfo * root
Definition: supportnodes.h:70
MonotonicFunction monotonic
Definition: supportnodes.h:329
struct SupportRequestModifyInPlace SupportRequestModifyInPlace
struct HeapTupleData * HeapTuple
Definition: supportnodes.h:43
struct SupportRequestSimplify SupportRequestSimplify
struct SupportRequestCost SupportRequestCost
struct SupportRequestIndexCondition SupportRequestIndexCondition
struct SupportRequestInlineInFrom SupportRequestInlineInFrom
struct SupportRequestOptimizeWindowClause SupportRequestOptimizeWindowClause
struct SupportRequestSelectivity SupportRequestSelectivity
struct SupportRequestRows SupportRequestRows
struct SupportRequestWFuncMonotonic SupportRequestWFuncMonotonic