← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to src/include/catalog/pg_statistic.h

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

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