Standardize terminology for pg_statistic_ext entries.

Consistently refer to such an entry as a "statistics object", not just
"statistics" or "extended statistics".  Previously we had a mismash of
terms, accompanied by utter confusion as to whether the term was
singular or plural.  That's not only grating (at least to the ear of
a native English speaker) but could be outright misleading, eg in error
messages that seemed to be referring to multiple objects where only one
could be meant.

This commit fixes the code and a lot of comments (though I may have
missed a few).  I also renamed two new SQL functions,
pg_get_statisticsextdef -> pg_get_statisticsobjdef
pg_statistic_ext_is_visible -> pg_statistics_obj_is_visible
to conform better with this terminology.

I have not touched the SGML docs other than fixing those function
names; the docs certainly need work but it seems like a separable task.

Discussion: https://postgr.es/m/22676.1494557205@sss.pgh.pa.us

Author: tglsfdc

doc/src/sgml/func.sgml

@@ -16681,7 +16681,7 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
        <entry>is operator family visible in search path</entry>
       </row>
       <row>
-       <entry><literal><function>pg_statistic_ext_is_visible(<parameter>stat_oid</parameter>)</function></literal>
+       <entry><literal><function>pg_statistics_obj_is_visible(<parameter>stat_oid</parameter>)</function></literal>
        </entry>
        <entry><type>boolean</type></entry>
        <entry>is statistics object visible in search path</entry>
@@ -16745,7 +16745,7 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
     <primary>pg_opfamily_is_visible</primary>
    </indexterm>
    <indexterm>
-    <primary>pg_statistic_ext_is_visible</primary>
+    <primary>pg_statistics_obj_is_visible</primary>
    </indexterm>
    <indexterm>
     <primary>pg_table_is_visible</primary>
@@ -16836,7 +16836,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
    </indexterm>
 
    <indexterm>
-    <primary>pg_get_statisticsextdef</primary>
+    <primary>pg_get_statisticsobjdef</primary>
    </indexterm>
 
    <indexterm>
@@ -17009,9 +17009,9 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
        uses</entry>
       </row>
       <row>
-       <entry><literal><function>pg_get_statisticsextdef(<parameter>statext_oid</parameter>)</function></literal></entry>
+       <entry><literal><function>pg_get_statisticsobjdef(<parameter>statobj_oid</parameter>)</function></literal></entry>
        <entry><type>text</type></entry>
-       <entry>get <command>CREATE STATISTICS</> command for extended statistics objects</entry>
+       <entry>get <command>CREATE STATISTICS</> command for extended statistics object</entry>
       </row>
       <row>
        <entry><function>pg_get_triggerdef</function>(<parameter>trigger_oid</parameter>)</entry>
@@ -17158,7 +17158,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
   <para>
    <function>pg_get_constraintdef</function>,
    <function>pg_get_indexdef</function>, <function>pg_get_ruledef</function>,
-   <function>pg_get_statisticsextdef</function>, and
+   <function>pg_get_statisticsobjdef</function>, and
    <function>pg_get_triggerdef</function>, respectively reconstruct the
    creating command for a constraint, index, rule, extended statistics object,
    or trigger. (Note that this is a decompiled reconstruction, not the

src/backend/catalog/aclchk.c

@@ -3321,7 +3321,7 @@ static const char *const no_priv_msg[MAX_ACL_KIND] =
 	/* ACL_KIND_CONVERSION */
 	gettext_noop("permission denied for conversion %s"),
 	/* ACL_KIND_STATISTICS */
-	gettext_noop("permission denied for statistics %s"),
+	gettext_noop("permission denied for statistics object %s"),
 	/* ACL_KIND_TABLESPACE */
 	gettext_noop("permission denied for tablespace %s"),
 	/* ACL_KIND_TSDICTIONARY */
@@ -3373,7 +3373,7 @@ static const char *const not_owner_msg[MAX_ACL_KIND] =
 	/* ACL_KIND_CONVERSION */
 	gettext_noop("must be owner of conversion %s"),
 	/* ACL_KIND_STATISTICS */
-	gettext_noop("must be owner of statistics %s"),
+	gettext_noop("must be owner of statistics object %s"),
 	/* ACL_KIND_TABLESPACE */
 	gettext_noop("must be owner of tablespace %s"),
 	/* ACL_KIND_TSDICTIONARY */
@@ -3490,7 +3490,7 @@ pg_aclmask(AclObjectKind objkind, Oid table_oid, AttrNumber attnum, Oid roleid,
 		case ACL_KIND_NAMESPACE:
 			return pg_namespace_aclmask(table_oid, roleid, mask, how);
 		case ACL_KIND_STATISTICS:
-			elog(ERROR, "grantable rights not supported for statistics");
+			elog(ERROR, "grantable rights not supported for statistics objects");
 			/* not reached, but keep compiler quiet */
 			return ACL_NO_RIGHTS;
 		case ACL_KIND_TABLESPACE:
@@ -5130,10 +5130,10 @@ pg_subscription_ownercheck(Oid sub_oid, Oid roleid)
 }
 
 /*
- * Ownership check for a extended statistics (specified by OID).
+ * Ownership check for a statistics object (specified by OID).
  */
 bool
-pg_statistics_ownercheck(Oid stat_oid, Oid roleid)
+pg_statistics_object_ownercheck(Oid stat_oid, Oid roleid)
 {
 	HeapTuple	tuple;
 	Oid			ownerId;
@@ -5146,7 +5146,8 @@ pg_statistics_ownercheck(Oid stat_oid, Oid roleid)
 	if (!HeapTupleIsValid(tuple))
 		ereport(ERROR,
 				(errcode(ERRCODE_UNDEFINED_OBJECT),
-				 errmsg("statistics with OID %u do not exist", stat_oid)));
+				 errmsg("statistics object with OID %u does not exist",
+						stat_oid)));
 
 	ownerId = ((Form_pg_statistic_ext) GETSTRUCT(tuple))->stxowner;
 

src/backend/catalog/namespace.c

@@ -2087,12 +2087,12 @@ ConversionIsVisible(Oid conid)
 }
 
 /*
- * get_statistics_oid - find a statistics by possibly qualified name
+ * get_statistics_object_oid - find a statistics object by possibly qualified name
  *
  * If not found, returns InvalidOid if missing_ok, else throws error
  */
 Oid
-get_statistics_oid(List *names, bool missing_ok)
+get_statistics_object_oid(List *names, bool missing_ok)
 {
 	char	   *schemaname;
 	char	   *stats_name;
@@ -2136,7 +2136,7 @@ get_statistics_oid(List *names, bool missing_ok)
 	if (!OidIsValid(stats_oid) && !missing_ok)
 		ereport(ERROR,
 				(errcode(ERRCODE_UNDEFINED_OBJECT),
-				 errmsg("statistics \"%s\" do not exist",
+				 errmsg("statistics object \"%s\" does not exist",
 						NameListToString(names))));
 
 	return stats_oid;
@@ -4303,7 +4303,7 @@ pg_conversion_is_visible(PG_FUNCTION_ARGS)
 }
 
 Datum
-pg_statistic_ext_is_visible(PG_FUNCTION_ARGS)
+pg_statistics_obj_is_visible(PG_FUNCTION_ARGS)
 {
 	Oid			oid = PG_GETARG_OID(0);
 

src/backend/catalog/objectaddress.c

@@ -712,7 +712,7 @@ static const struct object_type_map
 	},
 	/* OBJECT_STATISTIC_EXT */
 	{
-		"statistics", OBJECT_STATISTIC_EXT
+		"statistics object", OBJECT_STATISTIC_EXT
 	}
 };
 
@@ -993,8 +993,8 @@ get_object_address(ObjectType objtype, Node *object,
 				break;
 			case OBJECT_STATISTIC_EXT:
 				address.classId = StatisticExtRelationId;
-				address.objectId = get_statistics_oid(castNode(List, object),
-													  missing_ok);
+				address.objectId = get_statistics_object_oid(castNode(List, object),
+															 missing_ok);
 				address.objectSubId = 0;
 				break;
 			default:
@@ -2398,7 +2398,7 @@ check_object_ownership(Oid roleid, ObjectType objtype, ObjectAddress address,
 						 errmsg("must be superuser")));
 			break;
 		case OBJECT_STATISTIC_EXT:
-			if (!pg_statistics_ownercheck(address.objectId, roleid))
+			if (!pg_statistics_object_ownercheck(address.objectId, roleid))
 				aclcheck_error_type(ACLCHECK_NOT_OWNER, address.objectId);
 			break;
 		default:
@@ -3907,11 +3907,12 @@ getObjectTypeDescription(const ObjectAddress *object)
 			break;
 
 		case OCLASS_STATISTIC_EXT:
-			appendStringInfoString(&buffer, "statistics");
+			appendStringInfoString(&buffer, "statistics object");
 			break;
 
 		default:
-			appendStringInfo(&buffer, "unrecognized %u", object->classId);
+			appendStringInfo(&buffer, "unrecognized object class %u",
+							 object->classId);
 			break;
 	}
 
@@ -4946,7 +4947,7 @@ getObjectIdentityParts(const ObjectAddress *object,
 				tup = SearchSysCache1(STATEXTOID,
 									  ObjectIdGetDatum(object->objectId));
 				if (!HeapTupleIsValid(tup))
-					elog(ERROR, "cache lookup failed for statistics %u",
+					elog(ERROR, "cache lookup failed for statistics object %u",
 						 object->objectId);
 				formStatistic = (Form_pg_statistic_ext) GETSTRUCT(tup);
 				schema = get_namespace_name_or_temp(formStatistic->stxnamespace);

src/backend/commands/alter.c

@@ -123,7 +123,7 @@ report_namespace_conflict(Oid classId, const char *name, Oid nspOid)
 			break;
 		case StatisticExtRelationId:
 			Assert(OidIsValid(nspOid));
-			msgfmt = gettext_noop("statistics \"%s\" already exists in schema \"%s\"");
+			msgfmt = gettext_noop("statistics object \"%s\" already exists in schema \"%s\"");
 			break;
 		case TSParserRelationId:
 			Assert(OidIsValid(nspOid));

src/backend/commands/dropcmds.c

@@ -289,7 +289,7 @@ does_not_exist_skipping(ObjectType objtype, Node *object)
 		case OBJECT_STATISTIC_EXT:
 			if (!schema_does_not_exist_skipping(castNode(List, object), &msg, &name))
 			{
-				msg = gettext_noop("extended statistics \"%s\" do not exist, skipping");
+				msg = gettext_noop("statistics object \"%s\" does not exist, skipping");
 				name = NameListToString(castNode(List, object));
 			}
 			break;

src/backend/commands/statscmds.c

@@ -1,7 +1,7 @@
 /*-------------------------------------------------------------------------
  *
  * statscmds.c
- *	  Commands for creating and altering extended statistics
+ *	  Commands for creating and altering extended statistics objects
  *
  * Portions Copyright (c) 1996-2017, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
@@ -64,7 +64,7 @@ CreateStatistics(CreateStatsStmt *stmt)
 	Oid			relid;
 	ObjectAddress parentobject,
 				myself;
-	Datum		types[2];		/* one for each possible type of statistics */
+	Datum		types[2];		/* one for each possible type of statistic */
 	int			ntypes;
 	ArrayType  *stxkind;
 	bool		build_ndistinct;
@@ -80,7 +80,7 @@ CreateStatistics(CreateStatsStmt *stmt)
 	namestrcpy(&stxname, namestr);
 
 	/*
-	 * Deal with the possibility that the named statistics already exist.
+	 * Deal with the possibility that the statistics object already exists.
 	 */
 	if (SearchSysCacheExists2(STATEXTNAMENSP,
 							  NameGetDatum(&stxname),
@@ -90,14 +90,14 @@ CreateStatistics(CreateStatsStmt *stmt)
 		{
 			ereport(NOTICE,
 					(errcode(ERRCODE_DUPLICATE_OBJECT),
-					 errmsg("statistics \"%s\" already exist, skipping",
+					 errmsg("statistics object \"%s\" already exists, skipping",
 							namestr)));
 			return InvalidObjectAddress;
 		}
 
 		ereport(ERROR,
 				(errcode(ERRCODE_DUPLICATE_OBJECT),
-				 errmsg("statistics \"%s\" already exist", namestr)));
+				 errmsg("statistics object \"%s\" already exists", namestr)));
 	}
 
 	/*
@@ -263,7 +263,7 @@ CreateStatistics(CreateStatsStmt *stmt)
 		else
 			ereport(ERROR,
 					(errcode(ERRCODE_SYNTAX_ERROR),
-					 errmsg("unrecognized statistics type \"%s\"",
+					 errmsg("unrecognized statistic type \"%s\"",
 							type)));
 	}
 	/* If no statistic type was specified, build them all. */
@@ -307,7 +307,7 @@ CreateStatistics(CreateStatsStmt *stmt)
 	relation_close(statrel, RowExclusiveLock);
 
 	/*
-	 * Invalidate relcache so that others see the new statistics.
+	 * Invalidate relcache so that others see the new statistics object.
 	 */
 	CacheInvalidateRelcache(rel);
 
@@ -346,7 +346,7 @@ CreateStatistics(CreateStatsStmt *stmt)
 }
 
 /*
- * Guts of statistics deletion.
+ * Guts of statistics object deletion.
  */
 void
 RemoveStatisticsById(Oid statsOid)
@@ -365,7 +365,7 @@ RemoveStatisticsById(Oid statsOid)
 	tup = SearchSysCache1(STATEXTOID, ObjectIdGetDatum(statsOid));
 
 	if (!HeapTupleIsValid(tup)) /* should not happen */
-		elog(ERROR, "cache lookup failed for statistics %u", statsOid);
+		elog(ERROR, "cache lookup failed for statistics object %u", statsOid);
 
 	statext = (Form_pg_statistic_ext) GETSTRUCT(tup);
 	relid = statext->stxrelid;

src/backend/optimizer/util/plancat.c

@@ -1285,13 +1285,13 @@ get_relation_statistics(RelOptInfo *rel, Relation relation)
 
 		htup = SearchSysCache1(STATEXTOID, ObjectIdGetDatum(statOid));
 		if (!htup)
-			elog(ERROR, "cache lookup failed for statistics %u", statOid);
+			elog(ERROR, "cache lookup failed for statistics object %u", statOid);
 		staForm = (Form_pg_statistic_ext) GETSTRUCT(htup);
 
 		/*
 		 * First, build the array of columns covered.  This is ultimately
-		 * wasted if no stats are actually built, but it doesn't seem worth
-		 * troubling over that case.
+		 * wasted if no stats within the object have actually been built, but
+		 * it doesn't seem worth troubling over that case.
 		 */
 		for (i = 0; i < staForm->stxkeys.dim1; i++)
 			keys = bms_add_member(keys, staForm->stxkeys.values[i]);

src/backend/statistics/README

@@ -12,7 +12,7 @@ hopefully improving the estimates and producing better plans.
 Types of statistics
 -------------------
 
-There are two kinds of extended statistics:
+There are currently two kinds of extended statistics:
 
     (a) ndistinct coefficients
 
@@ -36,7 +36,7 @@ Complex clauses
 
 We also support estimating more complex clauses - essentially AND/OR clauses
 with (Var op Const) as leaves, as long as all the referenced attributes are
-covered by a single statistics.
+covered by a single statistics object.
 
 For example this condition
 
@@ -59,7 +59,7 @@ Selectivity estimation
 Throughout the planner clauselist_selectivity() still remains in charge of
 most selectivity estimate requests. clauselist_selectivity() can be instructed
 to try to make use of any extended statistics on the given RelOptInfo, which
-it will do, if:
+it will do if:
 
     (a) An actual valid RelOptInfo was given. Join relations are passed in as
         NULL, therefore are invalid.
@@ -77,6 +77,7 @@ performing estimations knows which clauses are to be skipped.
 
 Size of sample in ANALYZE
 -------------------------
+
 When performing ANALYZE, the number of rows to sample is determined as
 
     (300 * statistics_target)
@@ -93,4 +94,4 @@ those are not necessarily limited by statistics_target.
 This however merits further discussion, because collecting the sample is quite
 expensive and increasing it further would make ANALYZE even more painful.
 Judging by the experiments with the current implementation, the fixed size
-seems to work reasonably well for now, so we leave this as a future work.
+seems to work reasonably well for now, so we leave this as future work.

src/backend/statistics/README.dependencies

@@ -48,7 +48,7 @@ rendering the approach mostly useless even for slightly noisy data sets, or
 result in sudden changes in behavior depending on minor differences between
 samples provided to ANALYZE.
 
-For this reason, the statistics implements "soft" functional dependencies,
+For this reason, extended statistics implement "soft" functional dependencies,
 associating each functional dependency with a degree of validity (a number
 between 0 and 1). This degree is then used to combine selectivities in a
 smooth manner.

src/backend/statistics/dependencies.c

@@ -342,8 +342,8 @@ dependency_degree(int numrows, HeapTuple *rows, int k, AttrNumber *dependency,
  * detects functional dependencies between groups of columns
  *
  * Generates all possible subsets of columns (variations) and computes
- * the degree of validity for each one. For example with a statistic on
- * three columns (a,b,c) there are 9 possible dependencies
+ * the degree of validity for each one. For example when creating statistics
+ * on three columns (a,b,c) there are 9 possible dependencies
  *
  *	   two columns			  three columns
  *	   -----------			  -------------
@@ -383,8 +383,8 @@ statext_dependencies_build(int numrows, HeapTuple *rows, Bitmapset *attrs,
 	/*
 	 * We'll try build functional dependencies starting from the smallest ones
 	 * covering just 2 columns, to the largest ones, covering all columns
-	 * included in the statistics. We start from the smallest ones because we
-	 * want to be able to skip already implied ones.
+	 * included in the statistics object.  We start from the smallest ones
+	 * because we want to be able to skip already implied ones.
 	 */
 	for (k = 2; k <= numattrs; k++)
 	{
@@ -644,7 +644,7 @@ staext_dependencies_load(Oid mvoid)
 	HeapTuple	htup = SearchSysCache1(STATEXTOID, ObjectIdGetDatum(mvoid));
 
 	if (!HeapTupleIsValid(htup))
-		elog(ERROR, "cache lookup failed for extended statistics %u", mvoid);
+		elog(ERROR, "cache lookup failed for statistics object %u", mvoid);
 
 	deps = SysCacheGetAttr(STATEXTOID, htup,
 						   Anum_pg_statistic_ext_stxdependencies, &isnull);
@@ -975,7 +975,7 @@ dependencies_clauselist_selectivity(PlannerInfo *root,
 		return 1.0;
 	}
 
-	/* find the best suited statistics for these attnums */
+	/* find the best suited statistics object for these attnums */
 	stat = choose_best_statistics(rel->statlist, clauses_attnums,
 								  STATS_EXT_DEPENDENCIES);
 
@@ -986,7 +986,7 @@ dependencies_clauselist_selectivity(PlannerInfo *root,
 		return 1.0;
 	}
 
-	/* load the dependency items stored in the statistics */
+	/* load the dependency items stored in the statistics object */
 	dependencies = staext_dependencies_load(stat->statOid);
 
 	/*