| blob | 541e72ad81f0225a0c9da46d05c1ea1b2a8743a0 |
1 /*-------------------------------------------------------------------------
2 *
3 * pg_statistic.h
4 * definition of the system "statistic" relation (pg_statistic)
5 * along with the relation's initial contents.
6 *
7 *
8 * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
9 * Portions Copyright (c) 1994, Regents of the University of California
10 *
11 * $PostgreSQL$
12 *
13 * NOTES
14 * the genbki.sh script reads this file and generates .bki
15 * information from the DATA() statements.
16 *
17 *-------------------------------------------------------------------------
18 */
19 #ifndef PG_STATISTIC_H
20 #define PG_STATISTIC_H
24 /*
25 * The CATALOG definition has to refer to the type of stavaluesN as
26 * "anyarray" so that bootstrap mode recognizes it. There is no real
27 * typedef for that, however. Since the fields are potentially-null and
28 * therefore can't be accessed directly from C code, there is no particular
29 * need for the C struct definition to show a valid field type --- instead
30 * we just make it int.
31 */
32 #define anyarray int
34 /* ----------------
35 * pg_statistic definition. cpp turns this into
36 * typedef struct FormData_pg_statistic
37 * ----------------
38 */
39 #define StatisticRelationId 2619
42 {
43 /* These fields form the unique key for the entry: */
47 /* the fraction of the column's entries that are NULL: */
48 float4 stanullfrac;
50 /*
51 * stawidth is the average width in bytes of non-null entries. For
52 * fixed-width datatypes this is of course the same as the typlen, but for
53 * var-width types it is more useful. Note that this is the average width
54 * of the data as actually stored, post-TOASTing (eg, for a
55 * moved-out-of-line value, only the size of the pointer object is
56 * counted). This is the appropriate definition for the primary use of
57 * the statistic, which is to estimate sizes of in-memory hash tables of
58 * tuples.
59 */
60 int4 stawidth;
62 /* ----------------
63 * stadistinct indicates the (approximate) number of distinct non-null
64 * data values in the column. The interpretation is:
65 * 0 unknown or not computed
66 * > 0 actual number of distinct values
67 * < 0 negative of multiplier for number of rows
68 * The special negative case allows us to cope with columns that are
69 * unique (stadistinct = -1) or nearly so (for example, a column in
70 * which values appear about twice on the average could be represented
71 * by stadistinct = -0.5). Because the number-of-rows statistic in
72 * pg_class may be updated more frequently than pg_statistic is, it's
73 * important to be able to describe such situations as a multiple of
74 * the number of rows, rather than a fixed number of distinct values.
75 * But in other cases a fixed number is correct (eg, a boolean column).
76 * ----------------
77 */
78 float4 stadistinct;
80 /* ----------------
81 * To allow keeping statistics on different kinds of datatypes,
82 * we do not hard-wire any particular meaning for the remaining
83 * statistical fields. Instead, we provide several "slots" in which
84 * statistical data can be placed. Each slot includes:
85 * kind integer code identifying kind of data
86 * op OID of associated operator, if needed
87 * numbers float4 array (for statistical values)
88 * values anyarray (for representations of data values)
89 * The ID and operator fields are never NULL; they are zeroes in an
90 * unused slot. The numbers and values fields are NULL in an unused
91 * slot, and might also be NULL in a used slot if the slot kind has
92 * no need for one or the other.
93 * ----------------
94 */
96 int2 stakind1;
97 int2 stakind2;
98 int2 stakind3;
99 int2 stakind4;
101 Oid staop1;
102 Oid staop2;
103 Oid staop3;
104 Oid staop4;
106 /*
107 * THE REST OF THESE ARE VARIABLE LENGTH FIELDS, and may even be absent
108 * (NULL). They cannot be accessed as C struct entries; you have to use
109 * the full field access machinery (heap_getattr) for them. We declare
110 * them here for the catalog machinery.
111 */
118 /*
119 * Values in these arrays are values of the column's data type. We
120 * presently have to cheat quite a bit to allow polymorphic arrays of this
121 * kind, but perhaps someday it'll be a less bogus facility.
122 */
123 anyarray stavalues1;
124 anyarray stavalues2;
125 anyarray stavalues3;
126 anyarray stavalues4;
129 #define STATISTIC_NUM_SLOTS 4
131 #undef anyarray
134 /* ----------------
135 * Form_pg_statistic corresponds to a pointer to a tuple with
136 * the format of pg_statistic relation.
137 * ----------------
138 */
141 /* ----------------
142 * compiler constants for pg_statistic
143 * ----------------
144 */
145 #define Natts_pg_statistic 21
146 #define Anum_pg_statistic_starelid 1
147 #define Anum_pg_statistic_staattnum 2
148 #define Anum_pg_statistic_stanullfrac 3
149 #define Anum_pg_statistic_stawidth 4
150 #define Anum_pg_statistic_stadistinct 5
151 #define Anum_pg_statistic_stakind1 6
152 #define Anum_pg_statistic_stakind2 7
153 #define Anum_pg_statistic_stakind3 8
154 #define Anum_pg_statistic_stakind4 9
155 #define Anum_pg_statistic_staop1 10
156 #define Anum_pg_statistic_staop2 11
157 #define Anum_pg_statistic_staop3 12
158 #define Anum_pg_statistic_staop4 13
159 #define Anum_pg_statistic_stanumbers1 14
160 #define Anum_pg_statistic_stanumbers2 15
161 #define Anum_pg_statistic_stanumbers3 16
162 #define Anum_pg_statistic_stanumbers4 17
163 #define Anum_pg_statistic_stavalues1 18
164 #define Anum_pg_statistic_stavalues2 19
165 #define Anum_pg_statistic_stavalues3 20
166 #define Anum_pg_statistic_stavalues4 21
168 /*
169 * Currently, three statistical slot "kinds" are defined: most common values,
170 * histogram, and correlation. Additional "kinds" will probably appear in
171 * future to help cope with non-scalar datatypes. Also, custom data types
172 * can define their own "kind" codes by mutual agreement between a custom
173 * typanalyze routine and the selectivity estimation functions of the type's
174 * operators.
175 *
176 * Code reading the pg_statistic relation should not assume that a particular
177 * data "kind" will appear in any particular slot. Instead, search the
178 * stakind fields to see if the desired data is available. (The standard
179 * function get_attstatsslot() may be used for this.)
180 */
182 /*
183 * The present allocation of "kind" codes is:
184 *
185 * 1-99: reserved for assignment by the core PostgreSQL project
186 * (values in this range will be documented in this file)
187 * 100-199: reserved for assignment by the PostGIS project
188 * (values to be documented in PostGIS documentation)
189 * 200-299: reserved for assignment by the ESRI ST_Geometry project
190 * (values to be documented in ESRI ST_Geometry documentation)
191 * 300-9999: reserved for future public assignments
192 *
193 * For private use you may choose a "kind" code at random in the range
194 * 10000-30000. However, for code that is to be widely disseminated it is
195 * better to obtain a publicly defined "kind" code by request from the
196 * PostgreSQL Global Development Group.
197 */
199 /*
200 * In a "most common values" slot, staop is the OID of the "=" operator
201 * used to decide whether values are the same or not. stavalues contains
202 * the K most common non-null values appearing in the column, and stanumbers
203 * contains their frequencies (fractions of total row count). The values
204 * shall be ordered in decreasing frequency. Note that since the arrays are
205 * variable-size, K may be chosen by the statistics collector. Values should
206 * not appear in MCV unless they have been observed to occur more than once;
207 * a unique column will have no MCV slot.
208 */
209 #define STATISTIC_KIND_MCV 1
211 /*
212 * A "histogram" slot describes the distribution of scalar data. staop is
213 * the OID of the "<" operator that describes the sort ordering. (In theory,
214 * more than one histogram could appear, if a datatype has more than one
215 * useful sort operator.) stavalues contains M (>=2) non-null values that
216 * divide the non-null column data values into M-1 bins of approximately equal
217 * population. The first stavalues item is the MIN and the last is the MAX.
218 * stanumbers is not used and should be NULL. IMPORTANT POINT: if an MCV
219 * slot is also provided, then the histogram describes the data distribution
220 * *after removing the values listed in MCV* (thus, it's a "compressed
221 * histogram" in the technical parlance). This allows a more accurate
222 * representation of the distribution of a column with some very-common
223 * values. In a column with only a few distinct values, it's possible that
224 * the MCV list describes the entire data population; in this case the
225 * histogram reduces to empty and should be omitted.
226 */
227 #define STATISTIC_KIND_HISTOGRAM 2
229 /*
230 * A "correlation" slot describes the correlation between the physical order
231 * of table tuples and the ordering of data values of this column, as seen
232 * by the "<" operator identified by staop. (As with the histogram, more
233 * than one entry could theoretically appear.) stavalues is not used and
234 * should be NULL. stanumbers contains a single entry, the correlation
235 * coefficient between the sequence of data values and the sequence of
236 * their actual tuple positions. The coefficient ranges from +1 to -1.
237 */
238 #define STATISTIC_KIND_CORRELATION 3
240 /*
241 * A "most common elements" slot is similar to a "most common values" slot,
242 * except that it stores the most common non-null *elements* of the column
243 * values. This is useful when the column datatype is an array or some other
244 * type with identifiable elements (for instance, tsvector). staop contains
245 * the equality operator appropriate to the element type. stavalues contains
246 * the most common element values, and stanumbers their frequencies, with the
247 * same rules as for MCV slots.
248 *
249 * Note: in current usage for tsvector columns, the stavalues elements are of
250 * type text, even though their representation within tsvector is not
251 * exactly text.
252 */
253 #define STATISTIC_KIND_MCELEM 4