PostgreSQL Source Code git master
selfuncs.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * selfuncs.h
4 * Selectivity functions for standard operators, and assorted
5 * infrastructure for selectivity and cost estimation.
6 *
7 *
8 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
9 * Portions Copyright (c) 1994, Regents of the University of California
10 *
11 * src/include/utils/selfuncs.h
12 *
13 *-------------------------------------------------------------------------
14 */
15#ifndef SELFUNCS_H
16#define SELFUNCS_H
17
18#include "access/htup.h"
19#include "fmgr.h"
20#include "nodes/pathnodes.h"
21
22
23/*
24 * Note: the default selectivity estimates are not chosen entirely at random.
25 * We want them to be small enough to ensure that indexscans will be used if
26 * available, for typical table densities of ~100 tuples/page. Thus, for
27 * example, 0.01 is not quite small enough, since that makes it appear that
28 * nearly all pages will be hit anyway. Also, since we sometimes estimate
29 * eqsel as 1/num_distinct, we probably want DEFAULT_NUM_DISTINCT to equal
30 * 1/DEFAULT_EQ_SEL.
31 */
32
33/* default selectivity estimate for equalities such as "A = b" */
34#define DEFAULT_EQ_SEL 0.005
35
36/* default selectivity estimate for inequalities such as "A < b" */
37#define DEFAULT_INEQ_SEL 0.3333333333333333
38
39/* default selectivity estimate for range inequalities "A > b AND A < c" */
40#define DEFAULT_RANGE_INEQ_SEL 0.005
41
42/* default selectivity estimate for multirange inequalities "A > b AND A < c" */
43#define DEFAULT_MULTIRANGE_INEQ_SEL 0.005
44
45/* default selectivity estimate for pattern-match operators such as LIKE */
46#define DEFAULT_MATCH_SEL 0.005
47
48/* default selectivity estimate for other matching operators */
49#define DEFAULT_MATCHING_SEL 0.010
50
51/* default number of distinct values in a table */
52#define DEFAULT_NUM_DISTINCT 200
53
54/* default selectivity estimate for boolean and null test nodes */
55#define DEFAULT_UNK_SEL 0.005
56#define DEFAULT_NOT_UNK_SEL (1.0 - DEFAULT_UNK_SEL)
57
58
59/*
60 * Clamp a computed probability estimate (which may suffer from roundoff or
61 * estimation errors) to valid range. Argument must be a float variable.
62 */
63#define CLAMP_PROBABILITY(p) \
64 do { \
65 if (p < 0.0) \
66 p = 0.0; \
67 else if (p > 1.0) \
68 p = 1.0; \
69 } while (0)
70
71/*
72 * A set of flags which some selectivity estimation functions can pass back to
73 * callers to provide further details about some assumptions which were made
74 * during the estimation.
75 */
76#define SELFLAG_USED_DEFAULT (1 << 0) /* Estimation fell back on one
77 * of the DEFAULTs as defined
78 * above. */
79
80typedef struct EstimationInfo
81{
82 uint32 flags; /* Flags, as defined above to mark special
83 * properties of the estimation. */
86/* Return data from examine_variable and friends */
87typedef struct VariableStatData
89 Node *var; /* the Var or expression tree */
90 RelOptInfo *rel; /* Relation, or NULL if not identifiable */
91 HeapTuple statsTuple; /* pg_statistic tuple, or NULL if none */
92 /* NB: if statsTuple!=NULL, it must be freed when caller is done */
93 void (*freefunc) (HeapTuple tuple); /* how to free statsTuple */
94 Oid vartype; /* exposed type of expression */
95 Oid atttype; /* actual type (after stripping relabel) */
96 int32 atttypmod; /* actual typmod (after stripping relabel) */
97 bool isunique; /* matches unique index, DISTINCT or GROUP-BY
98 * clause */
99 bool acl_ok; /* result of ACL check on table or column */
101
102#define ReleaseVariableStats(vardata) \
103 do { \
104 if (HeapTupleIsValid((vardata).statsTuple)) \
105 (vardata).freefunc((vardata).statsTuple); \
106 } while(0)
107
108
109/*
110 * genericcostestimate is a general-purpose estimator that can be used for
111 * most index types. In some cases we use genericcostestimate as the base
112 * code and then incorporate additional index-type-specific knowledge in
113 * the type-specific calling function. To avoid code duplication, we make
114 * genericcostestimate return a number of intermediate values as well as
115 * its preliminary estimates of the output cost values. The GenericCosts
116 * struct includes all these values.
117 *
118 * Callers should initialize all fields of GenericCosts to zero. In addition,
119 * they can set numIndexTuples to some positive value if they have a better
120 * than default way of estimating the number of leaf index tuples visited.
121 * Similarly, they can set num_sa_scans to some value >= 1 for an index AM
122 * that doesn't necessarily perform exactly one primitive index scan per
123 * distinct combination of ScalarArrayOp array elements.
124 */
125typedef struct
127 /* These are the values the cost estimator must return to the planner */
128 Cost indexStartupCost; /* index-related startup cost */
129 Cost indexTotalCost; /* total index-related scan cost */
130 Selectivity indexSelectivity; /* selectivity of index */
131 double indexCorrelation; /* order correlation of index */
133 /* Intermediate values we obtain along the way */
134 double numIndexPages; /* number of leaf pages visited */
135 double numIndexTuples; /* number of leaf tuples visited */
136 double spc_random_page_cost; /* relevant random_page_cost value */
137 double num_sa_scans; /* # indexscans from ScalarArrayOpExprs */
140/* Hooks for plugins to get control when we ask for stats */
142 RangeTblEntry *rte,
147 Oid indexOid,
148 AttrNumber indexattnum,
149 VariableStatData *vardata);
151
152/* Functions in selfuncs.c */
153
154extern void examine_variable(PlannerInfo *root, Node *node, int varRelid,
155 VariableStatData *vardata);
156extern bool statistic_proc_security_check(VariableStatData *vardata, Oid func_oid);
158 int varRelid,
159 VariableStatData *vardata, Node **other,
160 bool *varonleft);
162 SpecialJoinInfo *sjinfo,
163 VariableStatData *vardata1,
164 VariableStatData *vardata2,
165 bool *join_is_reversed);
166extern double get_variable_numdistinct(VariableStatData *vardata,
167 bool *isdefault);
168extern double mcv_selectivity(VariableStatData *vardata,
169 FmgrInfo *opproc, Oid collation,
170 Datum constval, bool varonleft,
171 double *sumcommonp);
172extern double histogram_selectivity(VariableStatData *vardata,
173 FmgrInfo *opproc, Oid collation,
174 Datum constval, bool varonleft,
175 int min_hist_size, int n_skip,
176 int *hist_size);
178 Oid oproid, Oid collation,
179 List *args, int varRelid,
180 double default_selectivity);
182 VariableStatData *vardata,
183 Oid opoid, FmgrInfo *opproc,
184 bool isgt, bool iseq,
185 Oid collation,
186 Datum constval, Oid consttype);
187extern double var_eq_const(VariableStatData *vardata,
188 Oid oproid, Oid collation,
189 Datum constval, bool constisnull,
190 bool varonleft, bool negate);
191extern double var_eq_non_const(VariableStatData *vardata,
192 Oid oproid, Oid collation,
193 Node *other,
194 bool varonleft, bool negate);
195
196extern Selectivity boolvarsel(PlannerInfo *root, Node *arg, int varRelid);
198 Node *arg, int varRelid,
199 JoinType jointype, SpecialJoinInfo *sjinfo);
201 Node *arg, int varRelid,
202 JoinType jointype, SpecialJoinInfo *sjinfo);
204 ScalarArrayOpExpr *clause,
205 bool is_join_clause,
206 int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo);
207extern double estimate_array_length(PlannerInfo *root, Node *arrayexpr);
209 RowCompareExpr *clause,
210 int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo);
211
212extern void mergejoinscansel(PlannerInfo *root, Node *clause,
213 Oid opfamily, int strategy, bool nulls_first,
214 Selectivity *leftstart, Selectivity *leftend,
215 Selectivity *rightstart, Selectivity *rightend);
216
217extern double estimate_num_groups(PlannerInfo *root, List *groupExprs,
218 double input_rows, List **pgset,
219 EstimationInfo *estinfo);
220
222 RelOptInfo *inner,
223 List *hashclauses,
224 Selectivity *innerbucketsize);
226 Node *hashkey, double nbuckets,
227 Selectivity *mcv_freq,
228 Selectivity *bucketsize_frac);
229extern double estimate_hashagg_tablesize(PlannerInfo *root, Path *path,
230 const AggClauseCosts *agg_costs,
231 double dNumGroups);
232
233extern List *get_quals_from_indexclauses(List *indexclauses);
235 List *indexquals);
237 List *indexQuals);
239 double loop_count,
240 GenericCosts *costs);
241
242/* Functions in array_selfuncs.c */
243
245 Node *leftop, Node *rightop,
246 Oid elemtype, bool isEquality, bool useOr,
247 int varRelid);
248
249#endif /* SELFUNCS_H */
int16 AttrNumber
Definition: attnum.h:21
#define PGDLLIMPORT
Definition: c.h:1291
int32_t int32
Definition: c.h:498
uint32_t uint32
Definition: c.h:502
double Cost
Definition: nodes.h:253
double Selectivity
Definition: nodes.h:252
JoinType
Definition: nodes.h:290
int16 attnum
Definition: pg_attribute.h:74
void * arg
uintptr_t Datum
Definition: postgres.h:69
unsigned int Oid
Definition: postgres_ext.h:32
BoolTestType
Definition: primnodes.h:1980
NullTestType
Definition: primnodes.h:1956
tree ctl root
Definition: radixtree.h:1857
Selectivity scalararraysel_containment(PlannerInfo *root, Node *leftop, Node *rightop, Oid elemtype, bool isEquality, bool useOr, int varRelid)
bool get_restriction_variable(PlannerInfo *root, List *args, int varRelid, VariableStatData *vardata, Node **other, bool *varonleft)
Definition: selfuncs.c:5079
List * get_quals_from_indexclauses(List *indexclauses)
Definition: selfuncs.c:6678
double var_eq_const(VariableStatData *vardata, Oid oproid, Oid collation, Datum constval, bool constisnull, bool varonleft, bool negate)
Definition: selfuncs.c:296
List * add_predicate_to_index_quals(IndexOptInfo *index, List *indexQuals)
Definition: selfuncs.c:6985
double generic_restriction_selectivity(PlannerInfo *root, Oid oproid, Oid collation, List *args, int varRelid, double default_selectivity)
Definition: selfuncs.c:915
Selectivity booltestsel(PlannerInfo *root, BoolTestType booltesttype, Node *arg, int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo)
Definition: selfuncs.c:1541
double estimate_array_length(PlannerInfo *root, Node *arrayexpr)
Definition: selfuncs.c:2140
double mcv_selectivity(VariableStatData *vardata, FmgrInfo *opproc, Oid collation, Datum constval, bool varonleft, double *sumcommonp)
Definition: selfuncs.c:733
Selectivity nulltestsel(PlannerInfo *root, NullTestType nulltesttype, Node *arg, int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo)
Definition: selfuncs.c:1699
PGDLLIMPORT get_relation_stats_hook_type get_relation_stats_hook
Definition: selfuncs.c:148
struct VariableStatData VariableStatData
void examine_variable(PlannerInfo *root, Node *node, int varRelid, VariableStatData *vardata)
Definition: selfuncs.c:5208
void mergejoinscansel(PlannerInfo *root, Node *clause, Oid opfamily, int strategy, bool nulls_first, Selectivity *leftstart, Selectivity *leftend, Selectivity *rightstart, Selectivity *rightend)
Definition: selfuncs.c:2956
bool(* get_relation_stats_hook_type)(PlannerInfo *root, RangeTblEntry *rte, AttrNumber attnum, VariableStatData *vardata)
Definition: selfuncs.h:139
struct EstimationInfo EstimationInfo
double estimate_num_groups(PlannerInfo *root, List *groupExprs, double input_rows, List **pgset, EstimationInfo *estinfo)
Definition: selfuncs.c:3430
double ineq_histogram_selectivity(PlannerInfo *root, VariableStatData *vardata, Oid opoid, FmgrInfo *opproc, bool isgt, bool iseq, Oid collation, Datum constval, Oid consttype)
Definition: selfuncs.c:1042
void genericcostestimate(PlannerInfo *root, IndexPath *path, double loop_count, GenericCosts *costs)
Definition: selfuncs.c:6762
List * estimate_multivariate_bucketsize(PlannerInfo *root, RelOptInfo *inner, List *hashclauses, Selectivity *innerbucketsize)
Definition: selfuncs.c:3782
bool(* get_index_stats_hook_type)(PlannerInfo *root, Oid indexOid, AttrNumber indexattnum, VariableStatData *vardata)
Definition: selfuncs.h:144
double histogram_selectivity(VariableStatData *vardata, FmgrInfo *opproc, Oid collation, Datum constval, bool varonleft, int min_hist_size, int n_skip, int *hist_size)
Definition: selfuncs.c:824
Selectivity boolvarsel(PlannerInfo *root, Node *arg, int varRelid)
Definition: selfuncs.c:1513
Selectivity scalararraysel(PlannerInfo *root, ScalarArrayOpExpr *clause, bool is_join_clause, int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo)
Definition: selfuncs.c:1817
double var_eq_non_const(VariableStatData *vardata, Oid oproid, Oid collation, Node *other, bool varonleft, bool negate)
Definition: selfuncs.c:467
double get_variable_numdistinct(VariableStatData *vardata, bool *isdefault)
Definition: selfuncs.c:5982
PGDLLIMPORT get_index_stats_hook_type get_index_stats_hook
Definition: selfuncs.c:149
bool statistic_proc_security_check(VariableStatData *vardata, Oid func_oid)
Definition: selfuncs.c:5953
double estimate_hashagg_tablesize(PlannerInfo *root, Path *path, const AggClauseCosts *agg_costs, double dNumGroups)
Definition: selfuncs.c:4106
void estimate_hash_bucket_stats(PlannerInfo *root, Node *hashkey, double nbuckets, Selectivity *mcv_freq, Selectivity *bucketsize_frac)
Definition: selfuncs.c:3987
Cost index_other_operands_eval_cost(PlannerInfo *root, List *indexquals)
Definition: selfuncs.c:6708
Selectivity rowcomparesel(PlannerInfo *root, RowCompareExpr *clause, int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo)
Definition: selfuncs.c:2206
void get_join_variables(PlannerInfo *root, List *args, SpecialJoinInfo *sjinfo, VariableStatData *vardata1, VariableStatData *vardata2, bool *join_is_reversed)
Definition: selfuncs.c:5139
uint32 flags
Definition: selfuncs.h:80
Definition: fmgr.h:57
Definition: pg_list.h:54
Definition: nodes.h:131
HeapTuple statsTuple
Definition: selfuncs.h:89
int32 atttypmod
Definition: selfuncs.h:94
RelOptInfo * rel
Definition: selfuncs.h:88
void(* freefunc)(HeapTuple tuple)
Definition: selfuncs.h:91
Definition: type.h:96