| 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 |
|
| 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 |
{ |
| 66 |
NodeTag type; |
| 67 |
|
| 68 |
struct PlannerInfo *root; /* Planner's infrastructure */ |
| 69 |
FuncExpr *fcall; /* Function call to be simplified */ |
| 70 |
} SupportRequestSimplify; |
| 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 |
*/ |
| 91 |
typedef struct SupportRequestSelectivity |
| 92 |
{ |
| 93 |
NodeTag type; |
| 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 */ |
| 107 |
} SupportRequestSelectivity; |
| 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 |
{ |
| 133 |
NodeTag type; |
| 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 */ |
| 143 |
} SupportRequestCost; |
| 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 |
{ |
| 160 |
NodeTag type; |
| 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 */ |
| 169 |
} SupportRequestRows; |
| 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 |
*/ |
| 223 |
typedef struct SupportRequestIndexCondition |
| 224 |
{ |
| 225 |
NodeTag type; |
| 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 */ |
| 240 |
} SupportRequestIndexCondition; |
| 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 |
*/ |
| 290 |
typedef struct SupportRequestWFuncMonotonic |
| 291 |
{ |
| 292 |
NodeTag type; |
| 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: */ |
| 299 |
MonotonicFunction monotonic; |
| 300 |
} SupportRequestWFuncMonotonic; |
| 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 |
*/ |
| 333 |
typedef struct SupportRequestOptimizeWindowClause |
| 334 |
{ |
| 335 |
NodeTag type; |
| 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. */ |
| 344 |
} SupportRequestOptimizeWindowClause; |
| 345 |
|
| 346 |
/* |
| 347 |
* The ModifyInPlace request allows the support function to detect whether |
| 348 |
* a call to its target function can be allowed to modify a read/write |
| 349 |
* expanded object in-place. The context is that we are considering a |
| 350 |
* PL/pgSQL (or similar PL) assignment of the form "x := f(x, ...)" where |
| 351 |
* the variable x is of a type that can be represented as an expanded object |
| 352 |
* (see utils/expandeddatum.h). If f() can usefully optimize by modifying |
| 353 |
* the passed-in object in-place, then this request can be implemented to |
| 354 |
* instruct PL/pgSQL to pass a read-write expanded pointer to the variable's |
| 355 |
* value. (Note that there is no guarantee that later calls to f() will |
| 356 |
* actually do so. If f() receives a read-only pointer, or a pointer to a |
| 357 |
* non-expanded object, it must follow the usual convention of not modifying |
| 358 |
* the pointed-to object.) There are two requirements that must be met |
| 359 |
* to make this safe: |
| 360 |
* 1. f() must guarantee that it will not have modified the object if it |
| 361 |
* fails. Otherwise the variable's value might change unexpectedly. |
| 362 |
* 2. If the other arguments to f() ("..." in the above example) contain |
| 363 |
* references to x, f() must be able to cope with that; or if that's not |
| 364 |
* safe, the support function must scan the other arguments to verify that |
| 365 |
* there are no other references to x. An example of the concern here is |
| 366 |
* that in "arr := array_append(arr, arr[1])", if the array element type |
| 367 |
* is pass-by-reference then array_append would receive a second argument |
| 368 |
* that points into the array object it intends to modify. array_append is |
| 369 |
* coded to make that safe, but other functions might not be able to cope. |
| 370 |
* |
| 371 |
* "args" is a node tree list representing the function's arguments. |
| 372 |
* One or more nodes within the node tree will be PARAM_EXTERN Params |
| 373 |
* with ID "paramid", which represent the assignment target variable. |
| 374 |
* (Note that such references are not necessarily at top level in the list, |
| 375 |
* for example we might have "x := f(x, g(x))". Generally it's only safe |
| 376 |
* to optimize a reference that is at top level, else we're making promises |
| 377 |
* about the behavior of g() as well as f().) |
| 378 |
* |
| 379 |
* If modify-in-place is safe, the support function should return the |
| 380 |
* address of the Param node that is to return a read-write pointer. |
| 381 |
* (At most one of the references is allowed to do so.) Otherwise, |
| 382 |
* return NULL. |
| 383 |
*/ |
| 384 |
typedef struct SupportRequestModifyInPlace |
| 385 |
{ |
| 386 |
NodeTag type; |
| 387 |
|
| 388 |
Oid funcid; /* PG_PROC OID of the target function */ |
| 389 |
List *args; /* Arguments to the function */ |
| 390 |
int paramid; /* ID of Param(s) representing variable */ |
| 391 |
} SupportRequestModifyInPlace; |
| 392 |
|
| 393 |
#endif /* SUPPORTNODES_H */ |