Move index statistics into their own stats kind

This commit splits the relation and index stats data, where the index
data is now moved to a new kind called PGSTAT_KIND_INDEX.  A benefit of
this refactoring is a reduction of the shared memory required for each
index, the new PgStat_StatIdxEntry including only the fields required
for indexes.  This leads to less data flushed to disk on shutdown.
Another benefit is that the addition of new fields for relation-level
stats is easier to think about.  Note that indexes have no need for most
of the xact-level fields that relations care about, clarifying the role
of each counter for each relkind.

System views are updated to use the index-level functions.  Note this
split means a possible break for tools that had the idea to call the
SQL functions for relation stats (not documented), as now these would
return 0 when queried for an index.  These tools can use the new index
functions to achieve the same result.

As of this change, the pending statistics are still controlled by
PgStat_TableStatus for both relation and index kinds.  This is left as a
follow-up piece, this one being good enough on its own.  This commit is
focused on the changes required for the SQL interface, shared memory
management and the on-disk format.

Bump catalog version.
Bump PGSTAT_FILE_FORMAT_ID.

Author: Bertrand Drouvot <bertranddrouvot.pg@gmail.com>
Author: Michael Paquier <michael@paquier.xyz>
Discussion: https://postgr.es/m/f572abe7-a1bb-e13b-48c7-2ca150546822@gmail.com

Author: michaelpq

doc/src/sgml/monitoring.sgml

@@ -5877,6 +5877,24 @@ description | Waiting for a newly initialized WAL file to reach durable storage
        </para></entry>
       </row>
 
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>pg_stat_reset_single_index_counters</primary>
+        </indexterm>
+        <function>pg_stat_reset_single_index_counters</function> ( <type>oid</type> )
+        <returnvalue>void</returnvalue>
+       </para>
+       <para>
+        Resets statistics for a single index in the current database
+        or shared across all databases in the cluster to zero.
+       </para>
+       <para>
+        This function is restricted to superusers by default, but other users
+        can be granted EXECUTE to run the function.
+       </para></entry>
+      </row>
+
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
@@ -6022,7 +6040,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
         <returnvalue>void</returnvalue>
        </para>
        <para>
-        Resets statistics for a single table or index in the current database
+        Resets statistics for a single table in the current database
         or shared across all databases in the cluster to zero.
         It also resets statistics for a single sequence or materialized view
         in the current database.

src/backend/catalog/system_views.sql

@@ -722,9 +722,9 @@ CREATE VIEW pg_stat_all_tables AS
             pg_stat_get_numscans(C.oid) AS seq_scan,
             pg_stat_get_lastscan(C.oid) AS last_seq_scan,
             pg_stat_get_tuples_returned(C.oid) AS seq_tup_read,
-            sum(pg_stat_get_numscans(I.indexrelid))::bigint AS idx_scan,
-            max(pg_stat_get_lastscan(I.indexrelid)) AS last_idx_scan,
-            sum(pg_stat_get_tuples_fetched(I.indexrelid))::bigint +
+            sum(pg_stat_get_idx_numscans(I.indexrelid))::bigint AS idx_scan,
+            max(pg_stat_get_idx_lastscan(I.indexrelid)) AS last_idx_scan,
+            sum(pg_stat_get_idx_tuples_fetched(I.indexrelid))::bigint +
             pg_stat_get_tuples_fetched(C.oid) AS idx_tup_fetch,
             pg_stat_get_tuples_inserted(C.oid) AS n_tup_ins,
             pg_stat_get_tuples_updated(C.oid) AS n_tup_upd,
@@ -761,8 +761,8 @@ CREATE VIEW pg_stat_xact_all_tables AS
             C.relname AS relname,
             pg_stat_get_xact_numscans(C.oid) AS seq_scan,
             pg_stat_get_xact_tuples_returned(C.oid) AS seq_tup_read,
-            sum(pg_stat_get_xact_numscans(I.indexrelid))::bigint AS idx_scan,
-            sum(pg_stat_get_xact_tuples_fetched(I.indexrelid))::bigint +
+            sum(pg_stat_get_xact_idx_numscans(I.indexrelid))::bigint AS idx_scan,
+            sum(pg_stat_get_xact_idx_tuples_fetched(I.indexrelid))::bigint +
             pg_stat_get_xact_tuples_fetched(C.oid) AS idx_tup_fetch,
             pg_stat_get_xact_tuples_inserted(C.oid) AS n_tup_ins,
             pg_stat_get_xact_tuples_updated(C.oid) AS n_tup_upd,
@@ -833,17 +833,17 @@ CREATE VIEW pg_statio_all_tables AS
             pg_class T ON C.reltoastrelid = T.oid
             LEFT JOIN pg_namespace N ON (N.oid = C.relnamespace)
             LEFT JOIN LATERAL (
-              SELECT sum(pg_stat_get_blocks_fetched(indexrelid) -
-                         pg_stat_get_blocks_hit(indexrelid))::bigint
+              SELECT sum(pg_stat_get_idx_blocks_fetched(indexrelid) -
+                         pg_stat_get_idx_blocks_hit(indexrelid))::bigint
                      AS idx_blks_read,
-                     sum(pg_stat_get_blocks_hit(indexrelid))::bigint
+                     sum(pg_stat_get_idx_blocks_hit(indexrelid))::bigint
                      AS idx_blks_hit
               FROM pg_index WHERE indrelid = C.oid ) I ON true
             LEFT JOIN LATERAL (
-              SELECT sum(pg_stat_get_blocks_fetched(indexrelid) -
-                         pg_stat_get_blocks_hit(indexrelid))::bigint
+              SELECT sum(pg_stat_get_idx_blocks_fetched(indexrelid) -
+                         pg_stat_get_idx_blocks_hit(indexrelid))::bigint
                      AS idx_blks_read,
-                     sum(pg_stat_get_blocks_hit(indexrelid))::bigint
+                     sum(pg_stat_get_idx_blocks_hit(indexrelid))::bigint
                      AS idx_blks_hit
               FROM pg_index WHERE indrelid = T.oid ) X ON true
     WHERE C.relkind IN ('r', 't', 'm');
@@ -865,11 +865,11 @@ CREATE VIEW pg_stat_all_indexes AS
             N.nspname AS schemaname,
             C.relname AS relname,
             I.relname AS indexrelname,
-            pg_stat_get_numscans(I.oid) AS idx_scan,
-            pg_stat_get_lastscan(I.oid) AS last_idx_scan,
-            pg_stat_get_tuples_returned(I.oid) AS idx_tup_read,
-            pg_stat_get_tuples_fetched(I.oid) AS idx_tup_fetch,
-            pg_stat_get_stat_reset_time(I.oid) AS stats_reset
+            pg_stat_get_idx_numscans(I.oid) AS idx_scan,
+            pg_stat_get_idx_lastscan(I.oid) AS last_idx_scan,
+            pg_stat_get_idx_tuples_returned(I.oid) AS idx_tup_read,
+            pg_stat_get_idx_tuples_fetched(I.oid) AS idx_tup_fetch,
+            pg_stat_get_idx_stat_reset_time(I.oid) AS stats_reset
     FROM pg_class C JOIN
             pg_index X ON C.oid = X.indrelid JOIN
             pg_class I ON I.oid = X.indexrelid
@@ -893,10 +893,10 @@ CREATE VIEW pg_statio_all_indexes AS
             N.nspname AS schemaname,
             C.relname AS relname,
             I.relname AS indexrelname,
-            pg_stat_get_blocks_fetched(I.oid) -
-                    pg_stat_get_blocks_hit(I.oid) AS idx_blks_read,
-            pg_stat_get_blocks_hit(I.oid) AS idx_blks_hit,
-            pg_stat_get_stat_reset_time(I.oid) AS stats_reset
+            pg_stat_get_idx_blocks_fetched(I.oid) -
+                    pg_stat_get_idx_blocks_hit(I.oid) AS idx_blks_read,
+            pg_stat_get_idx_blocks_hit(I.oid) AS idx_blks_hit,
+            pg_stat_get_idx_stat_reset_time(I.oid) AS stats_reset
     FROM pg_class C JOIN
             pg_index X ON C.oid = X.indrelid JOIN
             pg_class I ON I.oid = X.indexrelid

src/backend/utils/activity/Makefile

@@ -25,6 +25,7 @@ OBJS = \
 	pgstat_checkpointer.o \
 	pgstat_database.o \
 	pgstat_function.o \
+	pgstat_index.o \
 	pgstat_io.o \
 	pgstat_kind.o \
 	pgstat_lock.o \

src/backend/utils/activity/meson.build

@@ -10,6 +10,7 @@ backend_sources += files(
   'pgstat_checkpointer.c',
   'pgstat_database.c',
   'pgstat_function.c',
+  'pgstat_index.c',
   'pgstat_io.c',
   'pgstat_kind.c',
   'pgstat_lock.c',

src/backend/utils/activity/pgstat.c

@@ -317,6 +317,22 @@ static const PgStat_KindInfo pgstat_kind_builtin_infos[PGSTAT_KIND_BUILTIN_SIZE]
 		.reset_timestamp_cb = pgstat_relation_reset_timestamp_cb,
 	},
 
+	[PGSTAT_KIND_INDEX] = {
+		.name = "index",
+
+		.fixed_amount = false,
+		.write_to_file = true,
+
+		.shared_size = sizeof(PgStatShared_Index),
+		.shared_data_off = offsetof(PgStatShared_Index, stats),
+		.shared_data_len = sizeof(((PgStatShared_Index *) 0)->stats),
+		.pending_size = sizeof(PgStat_TableStatus),
+
+		.flush_pending_cb = pgstat_index_flush_cb,
+		.delete_pending_cb = pgstat_index_delete_pending_cb,
+		.reset_timestamp_cb = pgstat_index_reset_timestamp_cb,
+	},
+
 	[PGSTAT_KIND_FUNCTION] = {
 		.name = "function",
 

src/backend/utils/activity/pgstat_index.c

@@ -0,0 +1,131 @@
+/* -------------------------------------------------------------------------
+ *
+ * pgstat_index.c
+ *	  Implementation of index statistics.
+ *
+ * This file contains the implementation of index statistics.
+ *
+ * Copyright (c) 2001-2026, PostgreSQL Global Development Group
+ *
+ * IDENTIFICATION
+ *	  src/backend/utils/activity/pgstat_index.c
+ * -------------------------------------------------------------------------
+ */
+
+#include "postgres.h"
+
+#include "access/xact.h"
+#include "catalog/catalog.h"
+#include "utils/memutils.h"
+#include "utils/pgstat_internal.h"
+#include "utils/rel.h"
+#include "utils/timestamp.h"
+
+
+/*
+ * Flush out pending stats for an index entry.
+ *
+ * If nowait is true and the lock could not be immediately acquired, returns
+ * false without flushing the entry.  Otherwise returns true.
+ *
+ * Some of the stats are copied to the corresponding pending database stats
+ * entry when successfully flushing.
+ */
+bool
+pgstat_index_flush_cb(PgStat_EntryRef *entry_ref, bool nowait)
+{
+	Oid			dboid;
+	PgStat_TableStatus *lstats; /* pending stats entry */
+	PgStatShared_Index *shidxstats;
+	PgStat_StatIdxEntry *idxentry;	/* index entry of shared stats */
+	PgStat_StatDBEntry *dbentry;	/* pending database entry */
+
+	dboid = entry_ref->shared_entry->key.dboid;
+	lstats = (PgStat_TableStatus *) entry_ref->pending;
+	shidxstats = (PgStatShared_Index *) entry_ref->shared_stats;
+
+	/*
+	 * Ignore entries that didn't accumulate any actual counts, such as
+	 * indexes that were opened by the planner but not used.
+	 */
+	if (pg_memory_is_all_zeros(&lstats->counts,
+							   sizeof(struct PgStat_TableCounts)))
+		return true;
+
+	if (!pgstat_lock_entry(entry_ref, nowait))
+		return false;
+
+	/* Add the values to the shared entry. */
+	idxentry = &shidxstats->stats;
+
+	idxentry->numscans += lstats->counts.numscans;
+	if (lstats->counts.numscans)
+	{
+		TimestampTz t = GetCurrentTransactionStopTimestamp();
+
+		if (t > idxentry->lastscan)
+			idxentry->lastscan = t;
+	}
+	idxentry->tuples_returned += lstats->counts.tuples_returned;
+	idxentry->tuples_fetched += lstats->counts.tuples_fetched;
+	idxentry->blocks_fetched += lstats->counts.blocks_fetched;
+	idxentry->blocks_hit += lstats->counts.blocks_hit;
+
+	pgstat_unlock_entry(entry_ref);
+
+	/* The entry was successfully flushed, add the same to database stats */
+	dbentry = pgstat_prep_database_pending(dboid);
+	dbentry->tuples_returned += lstats->counts.tuples_returned;
+	dbentry->tuples_fetched += lstats->counts.tuples_fetched;
+	dbentry->blocks_fetched += lstats->counts.blocks_fetched;
+	dbentry->blocks_hit += lstats->counts.blocks_hit;
+
+	return true;
+}
+
+/*
+ * Callback to delete pending index stats.
+ */
+void
+pgstat_index_delete_pending_cb(PgStat_EntryRef *entry_ref)
+{
+	PgStat_TableStatus *pending = (PgStat_TableStatus *) entry_ref->pending;
+
+	if (pending->relation)
+		pgstat_unlink_relation(pending->relation);
+}
+
+/*
+ * Callback to reset the timestamp on an index stats entry.
+ */
+void
+pgstat_index_reset_timestamp_cb(PgStatShared_Common *header, TimestampTz ts)
+{
+	((PgStatShared_Index *) header)->stats.stat_reset_time = ts;
+}
+
+/*
+ * Support function for the SQL-callable pgstat* functions. Returns
+ * the collected statistics for one index or NULL. NULL doesn't mean
+ * that the index doesn't exist, just that there are no statistics, so the
+ * caller is better off to report ZERO instead.
+ */
+PgStat_StatIdxEntry *
+pgstat_fetch_stat_idxentry(Oid relid)
+{
+	return pgstat_fetch_stat_idxentry_ext(IsSharedRelation(relid), relid, NULL);
+}
+
+/*
+ * More efficient version of pgstat_fetch_stat_idxentry(), allowing to specify
+ * whether the to-be-accessed index is a shared relation or not.  This version
+ * also returns whether the caller can pfree() the result if desired.
+ */
+PgStat_StatIdxEntry *
+pgstat_fetch_stat_idxentry_ext(bool shared, Oid reloid, bool *may_free)
+{
+	Oid			dboid = (shared ? InvalidOid : MyDatabaseId);
+
+	return (PgStat_StatIdxEntry *)
+		pgstat_fetch_entry(PGSTAT_KIND_INDEX, dboid, reloid, may_free);
+}