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-2008, 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.36 2008/07/14 00:51:45 tgl 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 #include "catalog/genbki.h"
  23
  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
  33
  34 /* ----------------
  35  *              pg_statistic definition.  cpp turns this into
  36  *              typedef struct FormData_pg_statistic
  37  * ----------------
  38  */
  39 #define StatisticRelationId  2619
  40
  41 CATALOG(pg_statistic,2619) BKI_WITHOUT_OIDS
  42 {
  43         /* These fields form the unique key for the entry: */
  44         Oid                     starelid;               /* relation containing attribute */
  45         int2            staattnum;              /* attribute (column) stats are for */
  46
  47         /* the fraction of the column's entries that are NULL: */
  48         float4          stanullfrac;
  49
  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;
  61
  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;
  79
  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          */
  95
  96         int2            stakind1;
  97         int2            stakind2;
  98         int2            stakind3;
  99         int2            stakind4;
 100
 101         Oid                     staop1;
 102         Oid                     staop2;
 103         Oid                     staop3;
 104         Oid                     staop4;
 105
 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          */
 112
 113         float4          stanumbers1[1];
 114         float4          stanumbers2[1];
 115         float4          stanumbers3[1];
 116         float4          stanumbers4[1];
 117
 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;
 127 } FormData_pg_statistic;
 128
 129 #define STATISTIC_NUM_SLOTS  4
 130
 131 #undef anyarray
 132
 133
 134 /* ----------------
 135  *              Form_pg_statistic corresponds to a pointer to a tuple with
 136  *              the format of pg_statistic relation.
 137  * ----------------
 138  */
 139 typedef FormData_pg_statistic *Form_pg_statistic;
 140
 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
 167
 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  */
 181
 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  */
 198
 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
 210
 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
 228
 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
 239
 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
 254
 255 #endif   /* PG_STATISTIC_H */