Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT

Robert Haas

Author: tglsfdc

doc/src/sgml/catalogs.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.203 2009/07/29 20:56:17 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.204 2009/08/02 22:14:51 tgl Exp $ -->
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
  -->
@@ -886,6 +886,19 @@
       </entry>
      </row>
 
+     <row>
+      <entry><structfield>attdistinct</structfield></entry>
+      <entry><type>float4</type></entry>
+      <entry></entry>
+      <entry>
+       <structfield>attdistinct</structfield>, if nonzero, is a user-specified
+       number-of-distinct-values figure to be used instead of estimating the
+       number of distinct values during <command>ANALYZE</>.  Nonzero values
+       have the same meanings as for
+       <link linkend="catalog-pg-statistic"><structname>pg_statistic</></link>.<structfield>stadistinct</>
+      </entry>
+     </row>
+
      <row>
       <entry><structfield>attlen</structfield></entry>
       <entry><type>int2</type></entry>
@@ -4303,9 +4316,10 @@
       <entry></entry>
       <entry>The number of distinct nonnull data values in the column.
       A value greater than zero is the actual number of distinct values.
-      A value less than zero is the negative of a fraction of the number
-      of rows in the table (for example, a column in which values appear about
-      twice on the average could be represented by <structfield>stadistinct</> = -0.5).
+      A value less than zero is the negative of a multiplier for the number
+      of rows in the table; for example, a column in which values appear about
+      twice on the average could be represented by
+      <structfield>stadistinct</> = -0.5.
       A zero value means the number of distinct values is unknown
       </entry>
      </row>

doc/src/sgml/ref/alter_table.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.107 2009/07/20 02:42:27 adunstan Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.108 2009/08/02 22:14:51 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -39,6 +39,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> DROP DEFAULT
     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { SET | DROP } NOT NULL
     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET STATISTICS <replaceable class="PARAMETER">integer</replaceable>
+    ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET STATISTICS DISTINCT <replaceable class="PARAMETER">number</replaceable>
     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }
     ADD <replaceable class="PARAMETER">table_constraint</replaceable>
     DROP CONSTRAINT [ IF EXISTS ]  <replaceable class="PARAMETER">constraint_name</replaceable> [ RESTRICT | CASCADE ]
@@ -90,8 +91,8 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       dropped as well.  You will need to say <literal>CASCADE</> if
       anything outside the table depends on the column, for example,
       foreign key references or views.
-      If <literal>IF EXISTS</literal> is specified and the column 
-      does not exist, no error is thrown. In this case a notice 
+      If <literal>IF EXISTS</literal> is specified and the column
+      does not exist, no error is thrown. In this case a notice
       is issued instead.
      </para>
     </listitem>
@@ -156,6 +157,31 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><literal>SET STATISTICS DISTINCT</literal></term>
+    <listitem>
+     <para>
+      This form overrides the number-of-distinct-values estimate made by
+      subsequent <xref linkend="sql-analyze" endterm="sql-analyze-title">
+      operations.  When set to a positive value, <command>ANALYZE</> will
+      assume that the column contains exactly the specified number of distinct
+      nonnull values.  When set to a negative value, which must be greater
+      than or equal to -1, <command>ANALYZE</> will assume that the number of
+      distinct nonnull values in the column is linear in the size of the
+      table; the exact count is to be computed by multiplying the estimated
+      table size by the absolute value of the given number.  For example,
+      a value of -1 implies that all values in the column are distinct, while
+      a value of -0.5 implies that each value appears twice on the average.
+      This can be useful when the size of the table changes over time, since
+      the multiplication by the number of rows in the table is not performed
+      until query planning time.  Specify a value of 0 to revert to estimating
+      the number of distinct values normally.  For more information on the use
+      of statistics by the <productname>PostgreSQL</productname> query
+      planner, refer to <xref linkend="planner-stats">.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <indexterm>
      <primary>TOAST</primary>

doc/src/sgml/ref/analyze.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.25 2008/12/13 19:13:44 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.26 2009/08/02 22:14:51 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -165,6 +165,17 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ ( <re
    the target causes a proportional increase in the time and space needed
    to do <command>ANALYZE</command>.
   </para>
+
+  <para>
+   One of the values estimated by <command>ANALYZE</command> is the number of
+   distinct values that appear in each column.  Because only a subset of the
+   rows are examined, this estimate can sometimes be quite inaccurate, even
+   with the largest possible statistics target.  If this inaccuracy leads to
+   bad query plans, a more accurate value can be determined manually and then
+   installed with
+   <command>ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT</>
+   (see <xref linkend="sql-altertable" endterm="sql-altertable-title">).
+  </para>
  </refsect1>
 
  <refsect1>

src/backend/access/common/tupdesc.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/access/common/tupdesc.c,v 1.127 2009/07/16 06:33:42 petere Exp $
+ *	  $PostgreSQL: pgsql/src/backend/access/common/tupdesc.c,v 1.128 2009/08/02 22:14:51 tgl Exp $
  *
  * NOTES
  *	  some of the executor utility code such as "ExecTypeFromTL" should be
@@ -338,6 +338,8 @@ equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2)
 			return false;
 		if (attr1->attstattarget != attr2->attstattarget)
 			return false;
+		if (attr1->attdistinct != attr2->attdistinct)
+			return false;
 		if (attr1->attlen != attr2->attlen)
 			return false;
 		if (attr1->attndims != attr2->attndims)
@@ -465,6 +467,7 @@ TupleDescInitEntry(TupleDesc desc,
 		MemSet(NameStr(att->attname), 0, NAMEDATALEN);
 
 	att->attstattarget = -1;
+	att->attdistinct = 0;
 	att->attcacheoff = -1;
 	att->atttypmod = typmod;
 

src/backend/bootstrap/bootstrap.c

@@ -8,7 +8,7 @@
  * Portions Copyright (c) 1994, Regents of the University of California
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/bootstrap/bootstrap.c,v 1.251 2009/07/31 20:26:22 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/backend/bootstrap/bootstrap.c,v 1.252 2009/08/02 22:14:51 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -757,6 +757,7 @@ DefineAttr(char *name, char *type, int attnum)
 	}
 
 	attrtypes[attnum]->attstattarget = -1;
+	attrtypes[attnum]->attdistinct = 0;
 	attrtypes[attnum]->attcacheoff = -1;
 	attrtypes[attnum]->atttypmod = -1;
 	attrtypes[attnum]->attislocal = true;

src/backend/catalog/heap.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/catalog/heap.c,v 1.356 2009/07/30 02:45:36 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/backend/catalog/heap.c,v 1.357 2009/08/02 22:14:52 tgl Exp $
  *
  *
  * INTERFACE ROUTINES
@@ -111,37 +111,37 @@ static List *insert_ordered_unique_oid(List *list, Oid datum);
  */
 
 static FormData_pg_attribute a1 = {
-	0, {"ctid"}, TIDOID, 0, sizeof(ItemPointerData),
+	0, {"ctid"}, TIDOID, 0, 0, sizeof(ItemPointerData),
 	SelfItemPointerAttributeNumber, 0, -1, -1,
 	false, 'p', 's', true, false, false, true, 0, {0}
 };
 
 static FormData_pg_attribute a2 = {
-	0, {"oid"}, OIDOID, 0, sizeof(Oid),
+	0, {"oid"}, OIDOID, 0, 0, sizeof(Oid),
 	ObjectIdAttributeNumber, 0, -1, -1,
 	true, 'p', 'i', true, false, false, true, 0, {0}
 };
 
 static FormData_pg_attribute a3 = {
-	0, {"xmin"}, XIDOID, 0, sizeof(TransactionId),
+	0, {"xmin"}, XIDOID, 0, 0, sizeof(TransactionId),
 	MinTransactionIdAttributeNumber, 0, -1, -1,
 	true, 'p', 'i', true, false, false, true, 0, {0}
 };
 
 static FormData_pg_attribute a4 = {
-	0, {"cmin"}, CIDOID, 0, sizeof(CommandId),
+	0, {"cmin"}, CIDOID, 0, 0, sizeof(CommandId),
 	MinCommandIdAttributeNumber, 0, -1, -1,
 	true, 'p', 'i', true, false, false, true, 0, {0}
 };
 
 static FormData_pg_attribute a5 = {
-	0, {"xmax"}, XIDOID, 0, sizeof(TransactionId),
+	0, {"xmax"}, XIDOID, 0, 0, sizeof(TransactionId),
 	MaxTransactionIdAttributeNumber, 0, -1, -1,
 	true, 'p', 'i', true, false, false, true, 0, {0}
 };
 
 static FormData_pg_attribute a6 = {
-	0, {"cmax"}, CIDOID, 0, sizeof(CommandId),
+	0, {"cmax"}, CIDOID, 0, 0, sizeof(CommandId),
 	MaxCommandIdAttributeNumber, 0, -1, -1,
 	true, 'p', 'i', true, false, false, true, 0, {0}
 };
@@ -153,7 +153,7 @@ static FormData_pg_attribute a6 = {
  * used in SQL.
  */
 static FormData_pg_attribute a7 = {
-	0, {"tableoid"}, OIDOID, 0, sizeof(Oid),
+	0, {"tableoid"}, OIDOID, 0, 0, sizeof(Oid),
 	TableOidAttributeNumber, 0, -1, -1,
 	true, 'p', 'i', true, false, false, true, 0, {0}
 };
@@ -501,6 +501,7 @@ InsertPgAttributeTuple(Relation pg_attribute_rel,
 	values[Anum_pg_attribute_attname - 1] = NameGetDatum(&new_attribute->attname);
 	values[Anum_pg_attribute_atttypid - 1] = ObjectIdGetDatum(new_attribute->atttypid);
 	values[Anum_pg_attribute_attstattarget - 1] = Int32GetDatum(new_attribute->attstattarget);
+	values[Anum_pg_attribute_attdistinct - 1] = Float4GetDatum(new_attribute->attdistinct);
 	values[Anum_pg_attribute_attlen - 1] = Int16GetDatum(new_attribute->attlen);
 	values[Anum_pg_attribute_attnum - 1] = Int16GetDatum(new_attribute->attnum);
 	values[Anum_pg_attribute_attndims - 1] = Int32GetDatum(new_attribute->attndims);
@@ -571,6 +572,7 @@ AddNewAttributeTuples(Oid new_rel_oid,
 		attr->attrelid = new_rel_oid;
 		/* Make sure these are OK, too */
 		attr->attstattarget = -1;
+		attr->attdistinct = 0;
 		attr->attcacheoff = -1;
 
 		InsertPgAttributeTuple(rel, attr, indstate);

src/backend/catalog/index.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/catalog/index.c,v 1.320 2009/07/29 20:56:18 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/backend/catalog/index.c,v 1.321 2009/08/02 22:14:52 tgl Exp $
  *
  *
  * INTERFACE ROUTINES
@@ -192,6 +192,7 @@ ConstructTupleDescriptor(Relation heapRelation,
 			to->attnum = i + 1;
 
 			to->attstattarget = -1;
+			to->attdistinct = 0;
 			to->attcacheoff = -1;
 			to->attnotnull = false;
 			to->atthasdef = false;

src/backend/commands/analyze.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/commands/analyze.c,v 1.139 2009/06/11 14:48:55 momjian Exp $
+ *	  $PostgreSQL: pgsql/src/backend/commands/analyze.c,v 1.140 2009/08/02 22:14:52 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -425,6 +425,11 @@ analyze_rel(Oid relid, VacuumStmt *vacstmt,
 									 std_fetch_func,
 									 numrows,
 									 totalrows);
+
+			/* If attdistinct is set, override with that value */
+			if (stats->attr->attdistinct != 0)
+				stats->stadistinct = stats->attr->attdistinct;
+
 			MemoryContextResetAndDeleteChildren(col_context);
 		}
 
@@ -679,6 +684,9 @@ compute_index_stats(Relation onerel, double totalrows,
 										 ind_fetch_func,
 										 numindexrows,
 										 totalindexrows);
+				/* If attdistinct is set, override with that value */
+				if (stats->attr->attdistinct != 0)
+					stats->stadistinct = stats->attr->attdistinct;
 				MemoryContextResetAndDeleteChildren(col_context);
 			}
 		}