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. All the current capabilities have to do
10  * with planning queries that use the target function, though it is
11  * possible that future extensions will add functionality to be invoked
12  * by the parser or executor.
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-2024, 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 
38 struct PlannerInfo; /* avoid including pathnodes.h here */
39 struct IndexOptInfo;
40 struct SpecialJoinInfo;
41 struct WindowClause;
42 
43 /*
44  * The Simplify request allows the support function to perform plan-time
45  * simplification of a call to its target function. For example, a varchar
46  * length coercion that does not decrease the allowed length of its argument
47  * could be replaced by a RelabelType node, or "x + 0" could be replaced by
48  * "x". This is invoked during the planner's constant-folding pass, so the
49  * function's arguments can be presumed already simplified.
50  *
51  * The planner's PlannerInfo "root" is typically not needed, but can be
52  * consulted if it's necessary to obtain info about Vars present in
53  * the given node tree. Beware that root could be NULL in some usages.
54  *
55  * "fcall" will be a FuncExpr invoking the support function's target
56  * function. (This is true even if the original parsetree node was an
57  * operator call; a FuncExpr is synthesized for this purpose.)
58  *
59  * The result should be a semantically-equivalent transformed node tree,
60  * or NULL if no simplification could be performed. Do *not* return or
61  * modify *fcall, as it isn't really a separately allocated Node. But
62  * it's okay to use fcall->args, or parts of it, in the result tree.
63  */
64 typedef struct SupportRequestSimplify
65 {
67 
68  struct PlannerInfo *root; /* Planner's infrastructure */
69  FuncExpr *fcall; /* Function call to be simplified */
71 
72 /*
73  * The Selectivity request allows the support function to provide a
74  * selectivity estimate for a function appearing at top level of a WHERE
75  * clause (so it applies only to functions returning boolean).
76  *
77  * The input arguments are the same as are supplied to operator restriction
78  * and join estimators, except that we unify those two APIs into just one
79  * request type. See clause_selectivity() for the details.
80  *
81  * If an estimate can be made, store it into the "selectivity" field and
82  * return the address of the SupportRequestSelectivity node; the estimate
83  * must be between 0 and 1 inclusive. Return NULL if no estimate can be
84  * made (in which case the planner will fall back to a default estimate,
85  * traditionally 1/3).
86  *
87  * If the target function is being used as the implementation of an operator,
88  * the support function will not be used for this purpose; the operator's
89  * restriction or join estimator is consulted instead.
90  */
92 {
94 
95  /* Input fields: */
96  struct PlannerInfo *root; /* Planner's infrastructure */
97  Oid funcid; /* function we are inquiring about */
98  List *args; /* pre-simplified arguments to function */
99  Oid inputcollid; /* function's input collation */
100  bool is_join; /* is this a join or restriction case? */
101  int varRelid; /* if restriction, RTI of target relation */
102  JoinType jointype; /* if join, outer join type */
103  struct SpecialJoinInfo *sjinfo; /* if outer join, info about join */
104 
105  /* Output fields: */
106  Selectivity selectivity; /* returned selectivity estimate */
108 
109 /*
110  * The Cost request allows the support function to provide an execution
111  * cost estimate for its target function. The cost estimate can include
112  * both a one-time (query startup) component and a per-execution component.
113  * The estimate should *not* include the costs of evaluating the target
114  * function's arguments, only the target function itself.
115  *
116  * The "node" argument is normally the parse node that is invoking the
117  * target function. This is a FuncExpr in the simplest case, but it could
118  * also be an OpExpr, DistinctExpr, NullIfExpr, or WindowFunc, or possibly
119  * other cases in future. NULL is passed if the function cannot presume
120  * its arguments to be equivalent to what the calling node presents as
121  * arguments; that happens for, e.g., aggregate support functions and
122  * per-column comparison operators used by RowExprs.
123  *
124  * If an estimate can be made, store it into the cost fields and return the
125  * address of the SupportRequestCost node. Return NULL if no estimate can be
126  * made, in which case the planner will rely on the target function's procost
127  * field. (Note: while procost is automatically scaled by cpu_operator_cost,
128  * this is not the case for the outputs of the Cost request; the support
129  * function must scale its results appropriately on its own.)
130  */
131 typedef struct SupportRequestCost
132 {
134 
135  /* Input fields: */
136  struct PlannerInfo *root; /* Planner's infrastructure (could be NULL) */
137  Oid funcid; /* function we are inquiring about */
138  Node *node; /* parse node invoking function, or NULL */
139 
140  /* Output fields: */
141  Cost startup; /* one-time cost */
142  Cost per_tuple; /* per-evaluation cost */
144 
145 /*
146  * The Rows request allows the support function to provide an output rowcount
147  * estimate for its target function (so it applies only to set-returning
148  * functions).
149  *
150  * The "node" argument is the parse node that is invoking the target function;
151  * currently this will always be a FuncExpr or OpExpr.
152  *
153  * If an estimate can be made, store it into the rows field and return the
154  * address of the SupportRequestRows node. Return NULL if no estimate can be
155  * made, in which case the planner will rely on the target function's prorows
156  * field.
157  */
158 typedef struct SupportRequestRows
159 {
161 
162  /* Input fields: */
163  struct PlannerInfo *root; /* Planner's infrastructure (could be NULL) */
164  Oid funcid; /* function we are inquiring about */
165  Node *node; /* parse node invoking function */
166 
167  /* Output fields: */
168  double rows; /* number of rows expected to be returned */
170 
171 /*
172  * The IndexCondition request allows the support function to generate
173  * a directly-indexable condition based on a target function call that is
174  * not itself indexable. The target function call must appear at the top
175  * level of WHERE or JOIN/ON, so this applies only to functions returning
176  * boolean.
177  *
178  * The "node" argument is the parse node that is invoking the target function;
179  * currently this will always be a FuncExpr or OpExpr. The call is made
180  * only if at least one function argument matches an index column's variable
181  * or expression. "indexarg" identifies the matching argument (it's the
182  * argument's zero-based index in the node's args list).
183  *
184  * If the transformation is possible, return a List of directly-indexable
185  * condition expressions, else return NULL. (A List is used because it's
186  * sometimes useful to generate more than one indexable condition, such as
187  * when a LIKE with constant prefix gives rise to both >= and < conditions.)
188  *
189  * "Directly indexable" means that the condition must be directly executable
190  * by the index machinery. Typically this means that it is a binary OpExpr
191  * with the index column value on the left, a pseudo-constant on the right,
192  * and an operator that is in the index column's operator family. Other
193  * possibilities include RowCompareExpr, ScalarArrayOpExpr, and NullTest,
194  * depending on the index type; but those seem less likely to be useful for
195  * derived index conditions. "Pseudo-constant" means that the right-hand
196  * expression must not contain any volatile functions, nor any Vars of the
197  * table the index is for; use is_pseudo_constant_for_index() to check this.
198  * (Note: if the passed "node" is an OpExpr, the core planner already verified
199  * that the non-indexkey operand is pseudo-constant; but when the "node"
200  * is a FuncExpr, it does not check, since it doesn't know which of the
201  * function's arguments you might need to use in an index comparison value.)
202  *
203  * In many cases, an index condition can be generated but it is weaker than
204  * the function condition itself; for example, a LIKE with a constant prefix
205  * can produce an index range check based on the prefix, but we still need
206  * to execute the LIKE operator to verify the rest of the pattern. We say
207  * that such an index condition is "lossy". When returning an index condition,
208  * you should set the "lossy" request field to true if the condition is lossy,
209  * or false if it is an exact equivalent of the function's result. The core
210  * code will initialize that field to true, which is the common case.
211  *
212  * It is important to verify that the index operator family is the correct
213  * one for the condition you want to generate. Core support functions tend
214  * to use the known OID of a built-in opfamily for this, but extensions need
215  * to work harder, since their OIDs aren't fixed. A possibly workable
216  * answer for an index on an extension datatype is to verify the index AM's
217  * OID instead, and then assume that there's only one relevant opclass for
218  * your datatype so the opfamily must be the right one. Generating OpExpr
219  * nodes may also require knowing extension datatype OIDs (often you can
220  * find these out by applying exprType() to a function argument) and
221  * operator OIDs (which you can look up using get_opfamily_member).
222  */
224 {
226 
227  /* Input fields: */
228  struct PlannerInfo *root; /* Planner's infrastructure */
229  Oid funcid; /* function we are inquiring about */
230  Node *node; /* parse node invoking function */
231  int indexarg; /* index of function arg matching indexcol */
232  struct IndexOptInfo *index; /* planner's info about target index */
233  int indexcol; /* index of target index column (0-based) */
234  Oid opfamily; /* index column's operator family */
235  Oid indexcollation; /* index column's collation */
236 
237  /* Output fields: */
238  bool lossy; /* set to false if index condition is an exact
239  * equivalent of the function call */
241 
242 /* ----------
243  * To support more efficient query execution of any monotonically increasing
244  * and/or monotonically decreasing window functions, we support calling the
245  * window function's prosupport function passing along this struct whenever
246  * the planner sees an OpExpr qual directly reference a window function in a
247  * subquery. When the planner encounters this, we populate this struct and
248  * pass it along to the window function's prosupport function so that it can
249  * evaluate if the given WindowFunc is;
250  *
251  * a) monotonically increasing, or
252  * b) monotonically decreasing, or
253  * c) both monotonically increasing and decreasing, or
254  * d) none of the above.
255  *
256  * A function that is monotonically increasing can never return a value that
257  * is lower than a value returned in a "previous call". A monotonically
258  * decreasing function can never return a value higher than a value returned
259  * in a previous call. A function that is both must return the same value
260  * each time.
261  *
262  * We define "previous call" to mean a previous call to the same WindowFunc
263  * struct in the same window partition.
264  *
265  * row_number() is an example of a monotonically increasing function. The
266  * return value will be reset back to 1 in each new partition. An example of
267  * a monotonically increasing and decreasing function is COUNT(*) OVER ().
268  * Since there is no ORDER BY clause in this example, all rows in the
269  * partition are peers and all rows within the partition will be within the
270  * frame bound. Likewise for COUNT(*) OVER(ORDER BY a ROWS BETWEEN UNBOUNDED
271  * PRECEDING AND UNBOUNDED FOLLOWING).
272  *
273  * COUNT(*) OVER (ORDER BY a ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING)
274  * is an example of a monotonically decreasing function.
275  *
276  * Implementations must only concern themselves with the given WindowFunc
277  * being monotonic in a single partition.
278  *
279  * Inputs:
280  * 'window_func' is the pointer to the window function being called.
281  *
282  * 'window_clause' pointer to the WindowClause data. Support functions can
283  * use this to check frame bounds, etc.
284  *
285  * Outputs:
286  * 'monotonic' the resulting MonotonicFunction value for the given input
287  * window function and window clause.
288  * ----------
289  */
291 {
293 
294  /* Input fields: */
295  WindowFunc *window_func; /* Pointer to the window function data */
296  struct WindowClause *window_clause; /* Pointer to the window clause data */
297 
298  /* Output fields: */
301 
302 /*
303  * Some WindowFunc behavior might not be affected by certain variations in
304  * the WindowClause's frameOptions. For example, row_number() is coded in
305  * such a way that the frame options don't change the returned row number.
306  * nodeWindowAgg.c will have less work to do if the ROWS option is used
307  * instead of the RANGE option as no check needs to be done for peer rows.
308  * Since RANGE is included in the default frame options, window functions
309  * such as row_number() might want to change that to ROW.
310  *
311  * Here we allow a WindowFunc's support function to determine which, if
312  * anything, can be changed about the WindowClause which the WindowFunc
313  * belongs to. Currently only the frameOptions can be modified. However,
314  * we may want to allow more optimizations in the future.
315  *
316  * The support function is responsible for ensuring the optimized version of
317  * the frameOptions doesn't affect the result of the window function. The
318  * planner is responsible for only changing the frame options when all
319  * WindowFuncs using this particular WindowClause agree on what the optimized
320  * version of the frameOptions are. If a particular WindowFunc being used
321  * does not have a support function then the planner will not make any changes
322  * to the WindowClause's frameOptions.
323  *
324  * 'window_func' and 'window_clause' are set by the planner before calling the
325  * support function so that the support function has these fields available.
326  * These may be required in order to determine which optimizations are
327  * possible.
328  *
329  * 'frameOptions' is set by the planner to WindowClause.frameOptions. The
330  * support function must only adjust this if optimizations are possible for
331  * the given WindowFunc.
332  */
334 {
336 
337  /* Input fields: */
338  WindowFunc *window_func; /* Pointer to the window function data */
339  struct WindowClause *window_clause; /* Pointer to the window clause data */
340 
341  /* Input/Output fields: */
342  int frameOptions; /* New frameOptions, or left untouched if no
343  * optimizations are possible. */
345 
346 #endif /* SUPPORTNODES_H */
double Cost
Definition: nodes.h:241
NodeTag
Definition: nodes.h:27
double Selectivity
Definition: nodes.h:240
JoinType
Definition: nodes.h:278
MonotonicFunction
Definition: plannodes.h:1584
unsigned int Oid
Definition: postgres_ext.h:31
Definition: pg_list.h:54
Definition: nodes.h:129
struct PlannerInfo * root
Definition: supportnodes.h:136
struct IndexOptInfo * index
Definition: supportnodes.h:232
struct PlannerInfo * root
Definition: supportnodes.h:228
struct WindowClause * window_clause
Definition: supportnodes.h:339
struct PlannerInfo * root
Definition: supportnodes.h:163
struct PlannerInfo * root
Definition: supportnodes.h:96
struct SpecialJoinInfo * sjinfo
Definition: supportnodes.h:103
struct PlannerInfo * root
Definition: supportnodes.h:68
struct WindowClause * window_clause
Definition: supportnodes.h:296
MonotonicFunction monotonic
Definition: supportnodes.h:299
struct SupportRequestSimplify SupportRequestSimplify
struct SupportRequestCost SupportRequestCost
struct SupportRequestIndexCondition SupportRequestIndexCondition
struct SupportRequestOptimizeWindowClause SupportRequestOptimizeWindowClause
struct SupportRequestSelectivity SupportRequestSelectivity
struct SupportRequestRows SupportRequestRows
struct SupportRequestWFuncMonotonic SupportRequestWFuncMonotonic