granicus.if.org Git - postgresql/blob - 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-2017, 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 which
  61          * non-null values appear about twice on the average could be represented
  62          * by stadistinct = -0.5 if there are no nulls, or -0.4 if 20% of the
  63          * column is nulls).  Because the number-of-rows statistic in pg_class may
  64          * be updated more frequently than pg_statistic is, it's important to be
  65          * able to describe such situations as a multiple of the number of rows,
  66          * rather than a fixed number of distinct values.  But in other cases a
  67          * fixed number is correct (eg, a boolean column).
  68          * ----------------
  69          */
  70         float4          stadistinct;
  71
  72         /* ----------------
  73          * To allow keeping statistics on different kinds of datatypes,
  74          * we do not hard-wire any particular meaning for the remaining
  75          * statistical fields.  Instead, we provide several "slots" in which
  76          * statistical data can be placed.  Each slot includes:
  77          *              kind                    integer code identifying kind of data (see below)
  78          *              op                              OID of associated operator, if needed
  79          *              numbers                 float4 array (for statistical values)
  80          *              values                  anyarray (for representations of data values)
  81          * The ID and operator fields are never NULL; they are zeroes in an
  82          * unused slot.  The numbers and values fields are NULL in an unused
  83          * slot, and might also be NULL in a used slot if the slot kind has
  84          * no need for one or the other.
  85          * ----------------
  86          */
  87
  88         int16           stakind1;
  89         int16           stakind2;
  90         int16           stakind3;
  91         int16           stakind4;
  92         int16           stakind5;
  93
  94         Oid                     staop1;
  95         Oid                     staop2;
  96         Oid                     staop3;
  97         Oid                     staop4;
  98         Oid                     staop5;
  99
 100 #ifdef CATALOG_VARLEN                   /* variable-length fields start here */
 101         float4          stanumbers1[1];
 102         float4          stanumbers2[1];
 103         float4          stanumbers3[1];
 104         float4          stanumbers4[1];
 105         float4          stanumbers5[1];
 106
 107         /*
 108          * Values in these arrays are values of the column's data type, or of some
 109          * related type such as an array element type.  We presently have to cheat
 110          * quite a bit to allow polymorphic arrays of this kind, but perhaps
 111          * someday it'll be a less bogus facility.
 112          */
 113         anyarray        stavalues1;
 114         anyarray        stavalues2;
 115         anyarray        stavalues3;
 116         anyarray        stavalues4;
 117         anyarray        stavalues5;
 118 #endif
 119 } FormData_pg_statistic;
 120
 121 #define STATISTIC_NUM_SLOTS  5
 122
 123
 124 /* ----------------
 125  *              Form_pg_statistic corresponds to a pointer to a tuple with
 126  *              the format of pg_statistic relation.
 127  * ----------------
 128  */
 129 typedef FormData_pg_statistic *Form_pg_statistic;
 130
 131 /* ----------------
 132  *              compiler constants for pg_statistic
 133  * ----------------
 134  */
 135 #define Natts_pg_statistic                              26
 136 #define Anum_pg_statistic_starelid              1
 137 #define Anum_pg_statistic_staattnum             2
 138 #define Anum_pg_statistic_stainherit    3
 139 #define Anum_pg_statistic_stanullfrac   4
 140 #define Anum_pg_statistic_stawidth              5
 141 #define Anum_pg_statistic_stadistinct   6
 142 #define Anum_pg_statistic_stakind1              7
 143 #define Anum_pg_statistic_stakind2              8
 144 #define Anum_pg_statistic_stakind3              9
 145 #define Anum_pg_statistic_stakind4              10
 146 #define Anum_pg_statistic_stakind5              11
 147 #define Anum_pg_statistic_staop1                12
 148 #define Anum_pg_statistic_staop2                13
 149 #define Anum_pg_statistic_staop3                14
 150 #define Anum_pg_statistic_staop4                15
 151 #define Anum_pg_statistic_staop5                16
 152 #define Anum_pg_statistic_stanumbers1   17
 153 #define Anum_pg_statistic_stanumbers2   18
 154 #define Anum_pg_statistic_stanumbers3   19
 155 #define Anum_pg_statistic_stanumbers4   20
 156 #define Anum_pg_statistic_stanumbers5   21
 157 #define Anum_pg_statistic_stavalues1    22
 158 #define Anum_pg_statistic_stavalues2    23
 159 #define Anum_pg_statistic_stavalues3    24
 160 #define Anum_pg_statistic_stavalues4    25
 161 #define Anum_pg_statistic_stavalues5    26
 162
 163 /*
 164  * Currently, five statistical slot "kinds" are defined by core PostgreSQL,
 165  * as documented below.  Additional "kinds" will probably appear in
 166  * future to help cope with non-scalar datatypes.  Also, custom data types
 167  * can define their own "kind" codes by mutual agreement between a custom
 168  * typanalyze routine and the selectivity estimation functions of the type's
 169  * operators.
 170  *
 171  * Code reading the pg_statistic relation should not assume that a particular
 172  * data "kind" will appear in any particular slot.  Instead, search the
 173  * stakind fields to see if the desired data is available.  (The standard
 174  * function get_attstatsslot() may be used for this.)
 175  */
 176
 177 /*
 178  * The present allocation of "kind" codes is:
 179  *
 180  *      1-99:           reserved for assignment by the core PostgreSQL project
 181  *                              (values in this range will be documented in this file)
 182  *      100-199:        reserved for assignment by the PostGIS project
 183  *                              (values to be documented in PostGIS documentation)
 184  *      200-299:        reserved for assignment by the ESRI ST_Geometry project
 185  *                              (values to be documented in ESRI ST_Geometry documentation)
 186  *      300-9999:       reserved for future public assignments
 187  *
 188  * For private use you may choose a "kind" code at random in the range
 189  * 10000-30000.  However, for code that is to be widely disseminated it is
 190  * better to obtain a publicly defined "kind" code by request from the
 191  * PostgreSQL Global Development Group.
 192  */
 193
 194 /*
 195  * In a "most common values" slot, staop is the OID of the "=" operator
 196  * used to decide whether values are the same or not.  stavalues contains
 197  * the K most common non-null values appearing in the column, and stanumbers
 198  * contains their frequencies (fractions of total row count).  The values
 199  * shall be ordered in decreasing frequency.  Note that since the arrays are
 200  * variable-size, K may be chosen by the statistics collector.  Values should
 201  * not appear in MCV unless they have been observed to occur more than once;
 202  * a unique column will have no MCV slot.
 203  */
 204 #define STATISTIC_KIND_MCV      1
 205
 206 /*
 207  * A "histogram" slot describes the distribution of scalar data.  staop is
 208  * the OID of the "<" operator that describes the sort ordering.  (In theory,
 209  * more than one histogram could appear, if a datatype has more than one
 210  * useful sort operator.)  stavalues contains M (>=2) non-null values that
 211  * divide the non-null column data values into M-1 bins of approximately equal
 212  * population.  The first stavalues item is the MIN and the last is the MAX.
 213  * stanumbers is not used and should be NULL.  IMPORTANT POINT: if an MCV
 214  * slot is also provided, then the histogram describes the data distribution
 215  * *after removing the values listed in MCV* (thus, it's a "compressed
 216  * histogram" in the technical parlance).  This allows a more accurate
 217  * representation of the distribution of a column with some very-common
 218  * values.  In a column with only a few distinct values, it's possible that
 219  * the MCV list describes the entire data population; in this case the
 220  * histogram reduces to empty and should be omitted.
 221  */
 222 #define STATISTIC_KIND_HISTOGRAM  2
 223
 224 /*
 225  * A "correlation" slot describes the correlation between the physical order
 226  * of table tuples and the ordering of data values of this column, as seen
 227  * by the "<" operator identified by staop.  (As with the histogram, more
 228  * than one entry could theoretically appear.)  stavalues is not used and
 229  * should be NULL.  stanumbers contains a single entry, the correlation
 230  * coefficient between the sequence of data values and the sequence of
 231  * their actual tuple positions.  The coefficient ranges from +1 to -1.
 232  */
 233 #define STATISTIC_KIND_CORRELATION      3
 234
 235 /*
 236  * A "most common elements" slot is similar to a "most common values" slot,
 237  * except that it stores the most common non-null *elements* of the column
 238  * values.  This is useful when the column datatype is an array or some other
 239  * type with identifiable elements (for instance, tsvector).  staop contains
 240  * the equality operator appropriate to the element type.  stavalues contains
 241  * the most common element values, and stanumbers their frequencies.  Unlike
 242  * MCV slots, frequencies are measured as the fraction of non-null rows the
 243  * element value appears in, not the frequency of all rows.  Also unlike
 244  * MCV slots, the values are sorted into the element type's default order
 245  * (to support binary search for a particular value).  Since this puts the
 246  * minimum and maximum frequencies at unpredictable spots in stanumbers,
 247  * there are two extra members of stanumbers, holding copies of the minimum
 248  * and maximum frequencies.  Optionally, there can be a third extra member,
 249  * which holds the frequency of null elements (expressed in the same terms:
 250  * the fraction of non-null rows that contain at least one null element).  If
 251  * this member is omitted, the column is presumed to contain no null elements.
 252  *
 253  * Note: in current usage for tsvector columns, the stavalues elements are of
 254  * type text, even though their representation within tsvector is not
 255  * exactly text.
 256  */
 257 #define STATISTIC_KIND_MCELEM  4
 258
 259 /*
 260  * A "distinct elements count histogram" slot describes the distribution of
 261  * the number of distinct element values present in each row of an array-type
 262  * column.  Only non-null rows are considered, and only non-null elements.
 263  * staop contains the equality operator appropriate to the element type.
 264  * stavalues is not used and should be NULL.  The last member of stanumbers is
 265  * the average count of distinct element values over all non-null rows.  The
 266  * preceding M (>=2) members form a histogram that divides the population of
 267  * distinct-elements counts into M-1 bins of approximately equal population.
 268  * The first of these is the minimum observed count, and the last the maximum.
 269  */
 270 #define STATISTIC_KIND_DECHIST  5
 271
 272 /*
 273  * A "length histogram" slot describes the distribution of range lengths in
 274  * rows of a range-type column. stanumbers contains a single entry, the
 275  * fraction of empty ranges. stavalues is a histogram of non-empty lengths, in
 276  * a format similar to STATISTIC_KIND_HISTOGRAM: it contains M (>=2) range
 277  * values that divide the column data values into M-1 bins of approximately
 278  * equal population. The lengths are stored as float8s, as measured by the
 279  * range type's subdiff function. Only non-null rows are considered.
 280  */
 281 #define STATISTIC_KIND_RANGE_LENGTH_HISTOGRAM  6
 282
 283 /*
 284  * A "bounds histogram" slot is similar to STATISTIC_KIND_HISTOGRAM, but for
 285  * a range-type column.  stavalues contains M (>=2) range values that divide
 286  * the column data values into M-1 bins of approximately equal population.
 287  * Unlike a regular scalar histogram, this is actually two histograms combined
 288  * into a single array, with the lower bounds of each value forming a
 289  * histogram of lower bounds, and the upper bounds a histogram of upper
 290  * bounds.  Only non-NULL, non-empty ranges are included.
 291  */
 292 #define STATISTIC_KIND_BOUNDS_HISTOGRAM  7
 293
 294 #endif                                                  /* PG_STATISTIC_H */