util/X86MAC64/include/postgresql/server/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-2014, PostgreSQL Global Development Group
   9  * Portions Copyright (c) 1994, Regents of the University of California
  10  *
  11  * src/include/catalog/pg_statistic.h
  12  *
  13  * NOTES
  14  *        the genbki.pl 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 #include "catalog/genbki.h"
  23
  24 /* ----------------
  25  *              pg_statistic definition.  cpp turns this into
  26  *              typedef struct FormData_pg_statistic
  27  * ----------------
  28  */
  29 #define StatisticRelationId  2619
  30
  31 CATALOG(pg_statistic,2619) BKI_WITHOUT_OIDS
  32 {
  33         /* These fields form the unique key for the entry: */
  34         Oid                     starelid;               /* relation containing attribute */
  35         int16           staattnum;              /* attribute (column) stats are for */
  36         bool            stainherit;             /* true if inheritance children are included */
  37
  38         /* the fraction of the column's entries that are NULL: */
  39         float4          stanullfrac;
  40
  41         /*
  42          * stawidth is the average width in bytes of non-null entries.  For
  43          * fixed-width datatypes this is of course the same as the typlen, but for
  44          * var-width types it is more useful.  Note that this is the average width
  45          * of the data as actually stored, post-TOASTing (eg, for a
  46          * moved-out-of-line value, only the size of the pointer object is
  47          * counted).  This is the appropriate definition for the primary use of
  48          * the statistic, which is to estimate sizes of in-memory hash tables of
  49          * tuples.
  50          */
  51         int32           stawidth;
  52
  53         /* ----------------
  54          * stadistinct indicates the (approximate) number of distinct non-null
  55          * data values in the column.  The interpretation is:
  56          *              0               unknown or not computed
  57          *              > 0             actual number of distinct values
  58          *              < 0             negative of multiplier for number of rows
  59          * The special negative case allows us to cope with columns that are
  60          * unique (stadistinct = -1) or nearly so (for example, a column in
  61          * which values appear about twice on the average could be represented
  62          * by stadistinct = -0.5).  Because the number-of-rows statistic in
  63          * pg_class may be updated more frequently than pg_statistic is, it's
  64          * important to be able to describe such situations as a multiple of
  65          * the number of rows, rather than a fixed number of distinct values.
  66          * But in other cases a fixed number is correct (eg, a boolean column).
  67          * ----------------
  68          */
  69         float4          stadistinct;
  70
  71         /* ----------------
  72          * To allow keeping statistics on different kinds of datatypes,
  73          * we do not hard-wire any particular meaning for the remaining
  74          * statistical fields.  Instead, we provide several "slots" in which
  75          * statistical data can be placed.  Each slot includes:
  76          *              kind                    integer code identifying kind of data (see below)
  77          *              op                              OID of associated operator, if needed
  78          *              numbers                 float4 array (for statistical values)
  79          *              values                  anyarray (for representations of data values)
  80          * The ID and operator fields are never NULL; they are zeroes in an
  81          * unused slot.  The numbers and values fields are NULL in an unused
  82          * slot, and might also be NULL in a used slot if the slot kind has
  83          * no need for one or the other.
  84          * ----------------
  85          */
  86
  87         int16           stakind1;
  88         int16           stakind2;
  89         int16           stakind3;
  90         int16           stakind4;
  91         int16           stakind5;
  92
  93         Oid                     staop1;
  94         Oid                     staop2;
  95         Oid                     staop3;
  96         Oid                     staop4;
  97         Oid                     staop5;
  98
  99 #ifdef CATALOG_VARLEN                   /* variable-length fields start here */
 100         float4          stanumbers1[1];
 101         float4          stanumbers2[1];
 102         float4          stanumbers3[1];
 103         float4          stanumbers4[1];
 104         float4          stanumbers5[1];
 105
 106         /*
 107          * Values in these arrays are values of the column's data type, or of some
 108          * related type such as an array element type.  We presently have to cheat
 109          * quite a bit to allow polymorphic arrays of this kind, but perhaps
 110          * someday it'll be a less bogus facility.
 111          */
 112         anyarray        stavalues1;
 113         anyarray        stavalues2;
 114         anyarray        stavalues3;
 115         anyarray        stavalues4;
 116         anyarray        stavalues5;
 117 #endif
 118 } FormData_pg_statistic;
 119
 120 #define STATISTIC_NUM_SLOTS  5
 121
 122
 123 /* ----------------
 124  *              Form_pg_statistic corresponds to a pointer to a tuple with
 125  *              the format of pg_statistic relation.
 126  * ----------------
 127  */
 128 typedef FormData_pg_statistic *Form_pg_statistic;
 129
 130 /* ----------------
 131  *              compiler constants for pg_statistic
 132  * ----------------
 133  */
 134 #define Natts_pg_statistic                              26
 135 #define Anum_pg_statistic_starelid              1
 136 #define Anum_pg_statistic_staattnum             2
 137 #define Anum_pg_statistic_stainherit    3
 138 #define Anum_pg_statistic_stanullfrac   4
 139 #define Anum_pg_statistic_stawidth              5
 140 #define Anum_pg_statistic_stadistinct   6
 141 #define Anum_pg_statistic_stakind1              7
 142 #define Anum_pg_statistic_stakind2              8
 143 #define Anum_pg_statistic_stakind3              9
 144 #define Anum_pg_statistic_stakind4              10
 145 #define Anum_pg_statistic_stakind5              11
 146 #define Anum_pg_statistic_staop1                12
 147 #define Anum_pg_statistic_staop2                13
 148 #define Anum_pg_statistic_staop3                14
 149 #define Anum_pg_statistic_staop4                15
 150 #define Anum_pg_statistic_staop5                16
 151 #define Anum_pg_statistic_stanumbers1   17
 152 #define Anum_pg_statistic_stanumbers2   18
 153 #define Anum_pg_statistic_stanumbers3   19
 154 #define Anum_pg_statistic_stanumbers4   20
 155 #define Anum_pg_statistic_stanumbers5   21
 156 #define Anum_pg_statistic_stavalues1    22
 157 #define Anum_pg_statistic_stavalues2    23
 158 #define Anum_pg_statistic_stavalues3    24
 159 #define Anum_pg_statistic_stavalues4    25
 160 #define Anum_pg_statistic_stavalues5    26
 161
 162 /*
 163  * Currently, five statistical slot "kinds" are defined by core PostgreSQL,
 164  * as documented below.  Additional "kinds" will probably appear in
 165  * future to help cope with non-scalar datatypes.  Also, custom data types
 166  * can define their own "kind" codes by mutual agreement between a custom
 167  * typanalyze routine and the selectivity estimation functions of the type's
 168  * operators.
 169  *
 170  * Code reading the pg_statistic relation should not assume that a particular
 171  * data "kind" will appear in any particular slot.  Instead, search the
 172  * stakind fields to see if the desired data is available.  (The standard
 173  * function get_attstatsslot() may be used for this.)
 174  */
 175
 176 /*
 177  * The present allocation of "kind" codes is:
 178  *
 179  *      1-99:           reserved for assignment by the core PostgreSQL project
 180  *                              (values in this range will be documented in this file)
 181  *      100-199:        reserved for assignment by the PostGIS project
 182  *                              (values to be documented in PostGIS documentation)
 183  *      200-299:        reserved for assignment by the ESRI ST_Geometry project
 184  *                              (values to be documented in ESRI ST_Geometry documentation)
 185  *      300-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 /*
 235  * A "most common elements" slot is similar to a "most common values" slot,
 236  * except that it stores the most common non-null *elements* of the column
 237  * values.  This is useful when the column datatype is an array or some other
 238  * type with identifiable elements (for instance, tsvector).  staop contains
 239  * the equality operator appropriate to the element type.  stavalues contains
 240  * the most common element values, and stanumbers their frequencies.  Unlike
 241  * MCV slots, frequencies are measured as the fraction of non-null rows the
 242  * element value appears in, not the frequency of all rows.  Also unlike
 243  * MCV slots, the values are sorted into the element type's default order
 244  * (to support binary search for a particular value).  Since this puts the
 245  * minimum and maximum frequencies at unpredictable spots in stanumbers,
 246  * there are two extra members of stanumbers, holding copies of the minimum
 247  * and maximum frequencies.  Optionally, there can be a third extra member,
 248  * which holds the frequency of null elements (expressed in the same terms:
 249  * the fraction of non-null rows that contain at least one null element).  If
 250  * this member is omitted, the column is presumed to contain no null elements.
 251  *
 252  * Note: in current usage for tsvector columns, the stavalues elements are of
 253  * type text, even though their representation within tsvector is not
 254  * exactly text.
 255  */
 256 #define STATISTIC_KIND_MCELEM  4
 257
 258 /*
 259  * A "distinct elements count histogram" slot describes the distribution of
 260  * the number of distinct element values present in each row of an array-type
 261  * column.  Only non-null rows are considered, and only non-null elements.
 262  * staop contains the equality operator appropriate to the element type.
 263  * stavalues is not used and should be NULL.  The last member of stanumbers is
 264  * the average count of distinct element values over all non-null rows.  The
 265  * preceding M (>=2) members form a histogram that divides the population of
 266  * distinct-elements counts into M-1 bins of approximately equal population.
 267  * The first of these is the minimum observed count, and the last the maximum.
 268  */
 269 #define STATISTIC_KIND_DECHIST  5
 270
 271 /*
 272  * A "length histogram" slot describes the distribution of range lengths in
 273  * rows of a range-type column. stanumbers contains a single entry, the
 274  * fraction of empty ranges. stavalues is a histogram of non-empty lengths, in
 275  * a format similar to STATISTIC_KIND_HISTOGRAM: it contains M (>=2) range
 276  * values that divide the column data values into M-1 bins of approximately
 277  * equal population. The lengths are stores as float8s, as measured by the
 278  * range type's subdiff function. Only non-null rows are considered.
 279  */
 280 #define STATISTIC_KIND_RANGE_LENGTH_HISTOGRAM  6
 281
 282 /*
 283  * A "bounds histogram" slot is similar to STATISTIC_KIND_HISTOGRAM, but for
 284  * a range-type column.  stavalues contains M (>=2) range values that divide
 285  * the column data values into M-1 bins of approximately equal population.
 286  * Unlike a regular scalar histogram, this is actually two histograms combined
 287  * into a single array, with the lower bounds of each value forming a
 288  * histogram of lower bounds, and the upper bounds a histogram of upper
 289  * bounds.  Only non-NULL, non-empty ranges are included.
 290  */
 291 #define STATISTIC_KIND_BOUNDS_HISTOGRAM  7
 292
 293 #endif   /* PG_STATISTIC_H */