PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
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-2017, 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 "fmgr.h"
19 #include "access/htup.h"
20 #include "nodes/relation.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 pattern-match operators such as LIKE */
43 #define DEFAULT_MATCH_SEL 0.005
44 
45 /* default number of distinct values in a table */
46 #define DEFAULT_NUM_DISTINCT 200
47 
48 /* default selectivity estimate for boolean and null test nodes */
49 #define DEFAULT_UNK_SEL 0.005
50 #define DEFAULT_NOT_UNK_SEL (1.0 - DEFAULT_UNK_SEL)
51 
52 
53 /*
54  * Clamp a computed probability estimate (which may suffer from roundoff or
55  * estimation errors) to valid range. Argument must be a float variable.
56  */
57 #define CLAMP_PROBABILITY(p) \
58  do { \
59  if (p < 0.0) \
60  p = 0.0; \
61  else if (p > 1.0) \
62  p = 1.0; \
63  } while (0)
64 
65 
66 /* Return data from examine_variable and friends */
67 typedef struct VariableStatData
68 {
69  Node *var; /* the Var or expression tree */
70  RelOptInfo *rel; /* Relation, or NULL if not identifiable */
71  HeapTuple statsTuple; /* pg_statistic tuple, or NULL if none */
72  /* NB: if statsTuple!=NULL, it must be freed when caller is done */
73  void (*freefunc) (HeapTuple tuple); /* how to free statsTuple */
74  Oid vartype; /* exposed type of expression */
75  Oid atttype; /* actual type (after stripping relabel) */
76  int32 atttypmod; /* actual typmod (after stripping relabel) */
77  bool isunique; /* matches unique index or DISTINCT clause */
78  bool acl_ok; /* result of ACL check on table or column */
80 
81 #define ReleaseVariableStats(vardata) \
82  do { \
83  if (HeapTupleIsValid((vardata).statsTuple)) \
84  (vardata).freefunc((vardata).statsTuple); \
85  } while(0)
86 
87 
88 typedef enum
89 {
92 } Pattern_Type;
93 
94 typedef enum
95 {
98 
99 /*
100  * deconstruct_indexquals is a simple function to examine the indexquals
101  * attached to a proposed IndexPath. It returns a list of IndexQualInfo
102  * structs, one per qual expression.
103  */
104 typedef struct
105 {
106  RestrictInfo *rinfo; /* the indexqual itself */
107  int indexcol; /* zero-based index column number */
108  bool varonleft; /* true if index column is on left of qual */
109  Oid clause_op; /* qual's operator OID, if relevant */
110  Node *other_operand; /* non-index operand of qual's operator */
111 } IndexQualInfo;
112 
113 /*
114  * genericcostestimate is a general-purpose estimator that can be used for
115  * most index types. In some cases we use genericcostestimate as the base
116  * code and then incorporate additional index-type-specific knowledge in
117  * the type-specific calling function. To avoid code duplication, we make
118  * genericcostestimate return a number of intermediate values as well as
119  * its preliminary estimates of the output cost values. The GenericCosts
120  * struct includes all these values.
121  *
122  * Callers should initialize all fields of GenericCosts to zero. In addition,
123  * they can set numIndexTuples to some positive value if they have a better
124  * than default way of estimating the number of leaf index tuples visited.
125  */
126 typedef struct
127 {
128  /* These are the values the cost estimator must return to the planner */
129  Cost indexStartupCost; /* index-related startup cost */
130  Cost indexTotalCost; /* total index-related scan cost */
131  Selectivity indexSelectivity; /* selectivity of index */
132  double indexCorrelation; /* order correlation of index */
133 
134  /* Intermediate values we obtain along the way */
135  double numIndexPages; /* number of leaf pages visited */
136  double numIndexTuples; /* number of leaf tuples visited */
137  double spc_random_page_cost; /* relevant random_page_cost value */
138  double num_sa_scans; /* # indexscans from ScalarArrayOps */
139 } GenericCosts;
140 
141 /* Hooks for plugins to get control when we ask for stats */
143  RangeTblEntry *rte,
144  AttrNumber attnum,
145  VariableStatData *vardata);
148  Oid indexOid,
149  AttrNumber indexattnum,
150  VariableStatData *vardata);
152 
153 /* Functions in selfuncs.c */
154 
155 extern void examine_variable(PlannerInfo *root, Node *node, int varRelid,
156  VariableStatData *vardata);
157 extern bool statistic_proc_security_check(VariableStatData *vardata, Oid func_oid);
158 extern bool get_restriction_variable(PlannerInfo *root, List *args,
159  int varRelid,
160  VariableStatData *vardata, Node **other,
161  bool *varonleft);
162 extern void get_join_variables(PlannerInfo *root, List *args,
163  SpecialJoinInfo *sjinfo,
164  VariableStatData *vardata1,
165  VariableStatData *vardata2,
166  bool *join_is_reversed);
167 extern double get_variable_numdistinct(VariableStatData *vardata,
168  bool *isdefault);
169 extern double mcv_selectivity(VariableStatData *vardata, FmgrInfo *opproc,
170  Datum constval, bool varonleft,
171  double *sumcommonp);
172 extern double histogram_selectivity(VariableStatData *vardata, FmgrInfo *opproc,
173  Datum constval, bool varonleft,
174  int min_hist_size, int n_skip,
175  int *hist_size);
176 
178  Pattern_Type ptype,
179  Oid collation,
180  Const **prefix,
181  Selectivity *rest_selec);
182 extern Const *make_greater_string(const Const *str_const, FmgrInfo *ltproc,
183  Oid collation);
184 
185 extern Selectivity boolvarsel(PlannerInfo *root, Node *arg, int varRelid);
186 extern Selectivity booltestsel(PlannerInfo *root, BoolTestType booltesttype,
187  Node *arg, int varRelid,
188  JoinType jointype, SpecialJoinInfo *sjinfo);
189 extern Selectivity nulltestsel(PlannerInfo *root, NullTestType nulltesttype,
190  Node *arg, int varRelid,
191  JoinType jointype, SpecialJoinInfo *sjinfo);
193  ScalarArrayOpExpr *clause,
194  bool is_join_clause,
195  int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo);
196 extern int estimate_array_length(Node *arrayexpr);
198  RowCompareExpr *clause,
199  int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo);
200 
201 extern void mergejoinscansel(PlannerInfo *root, Node *clause,
202  Oid opfamily, int strategy, bool nulls_first,
203  Selectivity *leftstart, Selectivity *leftend,
204  Selectivity *rightstart, Selectivity *rightend);
205 
206 extern double estimate_num_groups(PlannerInfo *root, List *groupExprs,
207  double input_rows, List **pgset);
208 
209 extern void estimate_hash_bucket_stats(PlannerInfo *root,
210  Node *hashkey, double nbuckets,
211  Selectivity *mcv_freq,
212  Selectivity *bucketsize_frac);
213 
214 extern List *deconstruct_indexquals(IndexPath *path);
215 extern void genericcostestimate(PlannerInfo *root, IndexPath *path,
216  double loop_count,
217  List *qinfos,
218  GenericCosts *costs);
219 
220 /* Functions in array_selfuncs.c */
221 
223  Node *leftop, Node *rightop,
224  Oid elemtype, bool isEquality, bool useOr,
225  int varRelid);
226 
227 #endif /* SELFUNCS_H */
Selectivity indexSelectivity
Definition: selfuncs.h:131
Definition: fmgr.h:56
HeapTuple statsTuple
Definition: selfuncs.h:71
Selectivity rowcomparesel(PlannerInfo *root, RowCompareExpr *clause, int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo)
Definition: selfuncs.c:2205
PGDLLIMPORT get_relation_stats_hook_type get_relation_stats_hook
Definition: selfuncs.c:155
BoolTestType
Definition: primnodes.h:1195
double estimate_num_groups(PlannerInfo *root, List *groupExprs, double input_rows, List **pgset)
Definition: selfuncs.c:3360
RelOptInfo * rel
Definition: selfuncs.h:70
bool(* get_index_stats_hook_type)(PlannerInfo *root, Oid indexOid, AttrNumber indexattnum, VariableStatData *vardata)
Definition: selfuncs.h:147
Pattern_Type
Definition: selfuncs.h:88
bool statistic_proc_security_check(VariableStatData *vardata, Oid func_oid)
Definition: selfuncs.c:5041
Definition: nodes.h:510
Selectivity scalararraysel(PlannerInfo *root, ScalarArrayOpExpr *clause, bool is_join_clause, int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo)
Definition: selfuncs.c:1848
double Selectivity
Definition: nodes.h:640
NullTestType
Definition: primnodes.h:1172
unsigned int Oid
Definition: postgres_ext.h:31
List * deconstruct_indexquals(IndexPath *path)
Definition: selfuncs.c:6425
int32 atttypmod
Definition: selfuncs.h:76
RestrictInfo * rinfo
Definition: selfuncs.h:106
void examine_variable(PlannerInfo *root, Node *node, int varRelid, VariableStatData *vardata)
Definition: selfuncs.c:4663
#define PGDLLIMPORT
Definition: c.h:1069
char bool
Definition: c.h:202
signed int int32
Definition: c.h:246
JoinType
Definition: nodes.h:674
Selectivity boolvarsel(PlannerInfo *root, Node *arg, int varRelid)
Definition: selfuncs.c:1542
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:4541
double num_sa_scans
Definition: selfuncs.h:138
Selectivity nulltestsel(PlannerInfo *root, NullTestType nulltesttype, Node *arg, int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo)
Definition: selfuncs.c:1739
double histogram_selectivity(VariableStatData *vardata, FmgrInfo *opproc, Datum constval, bool varonleft, int min_hist_size, int n_skip, int *hist_size)
Definition: selfuncs.c:709
int estimate_array_length(Node *arrayexpr)
Definition: selfuncs.c:2167
Cost indexTotalCost
Definition: selfuncs.h:130
Const * make_greater_string(const Const *str_const, FmgrInfo *ltproc, Oid collation)
Definition: selfuncs.c:6199
double indexCorrelation
Definition: selfuncs.h:132
double mcv_selectivity(VariableStatData *vardata, FmgrInfo *opproc, Datum constval, bool varonleft, double *sumcommonp)
Definition: selfuncs.c:637
uintptr_t Datum
Definition: postgres.h:372
double get_variable_numdistinct(VariableStatData *vardata, bool *isdefault)
Definition: selfuncs.c:5070
bool varonleft
Definition: selfuncs.h:108
double spc_random_page_cost
Definition: selfuncs.h:137
Pattern_Prefix_Status pattern_fixed_prefix(Const *patt, Pattern_Type ptype, Oid collation, Const **prefix, Selectivity *rest_selec)
Definition: selfuncs.c:5833
struct VariableStatData VariableStatData
PGDLLIMPORT get_index_stats_hook_type get_index_stats_hook
Definition: selfuncs.c:156
double numIndexTuples
Definition: selfuncs.h:136
Selectivity booltestsel(PlannerInfo *root, BoolTestType booltesttype, Node *arg, int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo)
Definition: selfuncs.c:1581
void estimate_hash_bucket_stats(PlannerInfo *root, Node *hashkey, double nbuckets, Selectivity *mcv_freq, Selectivity *bucketsize_frac)
Definition: selfuncs.c:3696
bool(* get_relation_stats_hook_type)(PlannerInfo *root, RangeTblEntry *rte, AttrNumber attnum, VariableStatData *vardata)
Definition: selfuncs.h:142
Cost indexStartupCost
Definition: selfuncs.h:129
void genericcostestimate(PlannerInfo *root, IndexPath *path, double loop_count, List *qinfos, GenericCosts *costs)
Definition: selfuncs.c:6574
Node * other_operand
Definition: selfuncs.h:110
void * arg
void mergejoinscansel(PlannerInfo *root, Node *clause, Oid opfamily, int strategy, bool nulls_first, Selectivity *leftstart, Selectivity *leftend, Selectivity *rightstart, Selectivity *rightend)
Definition: selfuncs.c:2936
void(* freefunc)(HeapTuple tuple)
Definition: selfuncs.h:73
Definition: pg_list.h:45
int16 AttrNumber
Definition: attnum.h:21
double Cost
Definition: nodes.h:641
Pattern_Prefix_Status
Definition: selfuncs.h:94
void get_join_variables(PlannerInfo *root, List *args, SpecialJoinInfo *sjinfo, VariableStatData *vardata1, VariableStatData *vardata2, bool *join_is_reversed)
Definition: selfuncs.c:4601
double numIndexPages
Definition: selfuncs.h:135