pg_statistic.h 12 KB

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