codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * supportnodes.h4 *	  Definitions for planner support functions.5 *6 * This file defines the API for "planner support functions", which7 * are SQL functions (normally written in C) that can be attached to8 * another "target" function to give the system additional knowledge9 * about the target function.  All the current capabilities have to do10 * with planning queries that use the target function, though it is11 * possible that future extensions will add functionality to be invoked12 * by the parser or executor.13 *14 * A support function must have the SQL signature15 *		supportfn(internal) returns internal16 * 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 on18 * which capability is being invoked.  In all cases, a NULL pointer result19 * (that's PG_RETURN_POINTER(NULL), not PG_RETURN_NULL()) indicates that20 * the support function cannot do anything useful for the given request.21 * Support functions must return a NULL pointer, not fail, if they do not22 * recognize the request node type or cannot handle the given case; this23 * allows for future extensions of the set of request cases.24 *25 *26 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group27 * Portions Copyright (c) 1994, Regents of the University of California28 *29 * src/include/nodes/supportnodes.h30 *31 *-------------------------------------------------------------------------32 */33#ifndef SUPPORTNODES_H34#define SUPPORTNODES_H35 36#include "nodes/plannodes.h"37 38struct PlannerInfo;				/* avoid including pathnodes.h here */39struct IndexOptInfo;40struct SpecialJoinInfo;41struct WindowClause;42 43/*44 * The Simplify request allows the support function to perform plan-time45 * simplification of a call to its target function.  For example, a varchar46 * length coercion that does not decrease the allowed length of its argument47 * could be replaced by a RelabelType node, or "x + 0" could be replaced by48 * "x".  This is invoked during the planner's constant-folding pass, so the49 * function's arguments can be presumed already simplified.50 *51 * The planner's PlannerInfo "root" is typically not needed, but can be52 * consulted if it's necessary to obtain info about Vars present in53 * 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 target56 * function.  (This is true even if the original parsetree node was an57 * 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 or61 * modify *fcall, as it isn't really a separately allocated Node.  But62 * it's okay to use fcall->args, or parts of it, in the result tree.63 */64typedef struct SupportRequestSimplify65{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 a74 * selectivity estimate for a function appearing at top level of a WHERE75 * clause (so it applies only to functions returning boolean).76 *77 * The input arguments are the same as are supplied to operator restriction78 * and join estimators, except that we unify those two APIs into just one79 * request type.  See clause_selectivity() for the details.80 *81 * If an estimate can be made, store it into the "selectivity" field and82 * return the address of the SupportRequestSelectivity node; the estimate83 * must be between 0 and 1 inclusive.  Return NULL if no estimate can be84 * 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's89 * restriction or join estimator is consulted instead.90 */91typedef struct SupportRequestSelectivity92{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 execution111 * cost estimate for its target function.  The cost estimate can include112 * both a one-time (query startup) component and a per-execution component.113 * The estimate should *not* include the costs of evaluating the target114 * function's arguments, only the target function itself.115 *116 * The "node" argument is normally the parse node that is invoking the117 * target function.  This is a FuncExpr in the simplest case, but it could118 * also be an OpExpr, DistinctExpr, NullIfExpr, or WindowFunc, or possibly119 * other cases in future.  NULL is passed if the function cannot presume120 * its arguments to be equivalent to what the calling node presents as121 * arguments; that happens for, e.g., aggregate support functions and122 * per-column comparison operators used by RowExprs.123 *124 * If an estimate can be made, store it into the cost fields and return the125 * address of the SupportRequestCost node.  Return NULL if no estimate can be126 * made, in which case the planner will rely on the target function's procost127 * 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 support129 * function must scale its results appropriately on its own.)130 */131typedef struct SupportRequestCost132{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 rowcount147 * estimate for its target function (so it applies only to set-returning148 * 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 the154 * address of the SupportRequestRows node.  Return NULL if no estimate can be155 * made, in which case the planner will rely on the target function's prorows156 * field.157 */158typedef struct SupportRequestRows159{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 generate173 * a directly-indexable condition based on a target function call that is174 * not itself indexable.  The target function call must appear at the top175 * level of WHERE or JOIN/ON, so this applies only to functions returning176 * 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 made180 * only if at least one function argument matches an index column's variable181 * or expression.  "indexarg" identifies the matching argument (it's the182 * argument's zero-based index in the node's args list).183 *184 * If the transformation is possible, return a List of directly-indexable185 * condition expressions, else return NULL.  (A List is used because it's186 * sometimes useful to generate more than one indexable condition, such as187 * when a LIKE with constant prefix gives rise to both >= and < conditions.)188 *189 * "Directly indexable" means that the condition must be directly executable190 * by the index machinery.  Typically this means that it is a binary OpExpr191 * 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.  Other193 * possibilities include RowCompareExpr, ScalarArrayOpExpr, and NullTest,194 * depending on the index type; but those seem less likely to be useful for195 * derived index conditions.  "Pseudo-constant" means that the right-hand196 * expression must not contain any volatile functions, nor any Vars of the197 * 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 verified199 * 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 the201 * 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 than204 * the function condition itself; for example, a LIKE with a constant prefix205 * can produce an index range check based on the prefix, but we still need206 * to execute the LIKE operator to verify the rest of the pattern.  We say207 * 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 core210 * 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 correct213 * one for the condition you want to generate.  Core support functions tend214 * to use the known OID of a built-in opfamily for this, but extensions need215 * to work harder, since their OIDs aren't fixed.  A possibly workable216 * answer for an index on an extension datatype is to verify the index AM's217 * OID instead, and then assume that there's only one relevant opclass for218 * your datatype so the opfamily must be the right one.  Generating OpExpr219 * nodes may also require knowing extension datatype OIDs (often you can220 * find these out by applying exprType() to a function argument) and221 * operator OIDs (which you can look up using get_opfamily_member).222 */223typedef struct SupportRequestIndexCondition224{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 exact239								 * equivalent of the function call */240} SupportRequestIndexCondition;241 242/* ----------243 * To support more efficient query execution of any monotonically increasing244 * and/or monotonically decreasing window functions, we support calling the245 * window function's prosupport function passing along this struct whenever246 * the planner sees an OpExpr qual directly reference a window function in a247 * subquery.  When the planner encounters this, we populate this struct and248 * pass it along to the window function's prosupport function so that it can249 * evaluate if the given WindowFunc is;250 *251 * a) monotonically increasing, or252 * b) monotonically decreasing, or253 * c) both monotonically increasing and decreasing, or254 * d) none of the above.255 *256 * A function that is monotonically increasing can never return a value that257 * is lower than a value returned in a "previous call".  A monotonically258 * decreasing function can never return a value higher than a value returned259 * in a previous call.  A function that is both must return the same value260 * each time.261 *262 * We define "previous call" to mean a previous call to the same WindowFunc263 * struct in the same window partition.264 *265 * row_number() is an example of a monotonically increasing function.  The266 * return value will be reset back to 1 in each new partition.  An example of267 * a monotonically increasing and decreasing function is COUNT(*) OVER ().268 * Since there is no ORDER BY clause in this example, all rows in the269 * partition are peers and all rows within the partition will be within the270 * frame bound.  Likewise for COUNT(*) OVER(ORDER BY a ROWS BETWEEN UNBOUNDED271 * 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 WindowFunc277 * 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 can283 *	use this to check frame bounds, etc.284 *285 * Outputs:286 *	'monotonic' the resulting MonotonicFunction value for the given input287 *	window function and window clause.288 * ----------289 */290typedef struct SupportRequestWFuncMonotonic291{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 in304 * the WindowClause's frameOptions.  For example, row_number() is coded in305 * 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 used307 * 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 functions309 * such as row_number() might want to change that to ROW.310 *311 * Here we allow a WindowFunc's support function to determine which, if312 * anything, can be changed about the WindowClause which the WindowFunc313 * 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 of317 * the frameOptions doesn't affect the result of the window function.  The318 * planner is responsible for only changing the frame options when all319 * WindowFuncs using this particular WindowClause agree on what the optimized320 * version of the frameOptions are.  If a particular WindowFunc being used321 * does not have a support function then the planner will not make any changes322 * to the WindowClause's frameOptions.323 *324 * 'window_func' and 'window_clause' are set by the planner before calling the325 * support function so that the support function has these fields available.326 * These may be required in order to determine which optimizations are327 * possible.328 *329 * 'frameOptions' is set by the planner to WindowClause.frameOptions.  The330 * support function must only adjust this if optimizations are possible for331 * the given WindowFunc.332 */333typedef struct SupportRequestOptimizeWindowClause334{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 no343								 * optimizations are possible. */344} SupportRequestOptimizeWindowClause;345 346#endif							/* SUPPORTNODES_H */347