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-2019, 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/primnodes.h"
37
38struct PlannerInfo; /* avoid including pathnodes.h here */
39struct IndexOptInfo;
40struct SpecialJoinInfo;
41
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 */
64typedef 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 */
91typedef 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 */
131typedef 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 */
158typedef 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 */
223typedef 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#endif /* SUPPORTNODES_H */
243