From 9c9492bb495d05ac4cb9d86b08b2644cc9f02832 Mon Sep 17 00:00:00 2001
From: Melanie Plageman <melanieplageman@gmail.com>
Date: Tue, 5 Dec 2023 07:04:57 -0500
Subject: [PATCH v3 12/12] Add pg_visibility_map_summary_extended()

Add a new pg_visibility function, pg_visibility_map_summary_extended(),
which returns the total number of blocks in the relation in addition to
the number of all frozen and all visible pages returned by
pg_visibility_map_summary(). It is easy and cheap to get the number of
blocks at the same time as the number of all visible and all frozen
pages and doing so is useful for calculating percent visible/frozen. The
old pg_visibility_map_summary() function API is left as is but is
implemented by selecting a subset of the columns returned by
pg_visibility_map_summary_extended().
---
 contrib/pg_visibility/expected/pg_visibility.out |  5 +++++
 contrib/pg_visibility/pg_visibility--1.1.sql     | 11 +++++++++--
 contrib/pg_visibility/pg_visibility.c            | 13 +++++++------
 doc/src/sgml/pgvisibility.sgml                   | 12 ++++++++++++
 4 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/contrib/pg_visibility/expected/pg_visibility.out b/contrib/pg_visibility/expected/pg_visibility.out
index 9de54db2a29..db52d407393 100644
--- a/contrib/pg_visibility/expected/pg_visibility.out
+++ b/contrib/pg_visibility/expected/pg_visibility.out
@@ -49,6 +49,7 @@ DETAIL:  This operation is not supported for partitioned tables.
 select pg_visibility_map_summary('test_partitioned');
 ERROR:  relation "test_partitioned" is of wrong relation kind
 DETAIL:  This operation is not supported for partitioned tables.
+CONTEXT:  SQL function "pg_visibility_map_summary" statement 1
 select pg_check_frozen('test_partitioned');
 ERROR:  relation "test_partitioned" is of wrong relation kind
 DETAIL:  This operation is not supported for partitioned tables.
@@ -67,6 +68,7 @@ DETAIL:  This operation is not supported for indexes.
 select pg_visibility_map_summary('test_index');
 ERROR:  relation "test_index" is of wrong relation kind
 DETAIL:  This operation is not supported for indexes.
+CONTEXT:  SQL function "pg_visibility_map_summary" statement 1
 select pg_check_frozen('test_index');
 ERROR:  relation "test_index" is of wrong relation kind
 DETAIL:  This operation is not supported for indexes.
@@ -84,6 +86,7 @@ DETAIL:  This operation is not supported for views.
 select pg_visibility_map_summary('test_view');
 ERROR:  relation "test_view" is of wrong relation kind
 DETAIL:  This operation is not supported for views.
+CONTEXT:  SQL function "pg_visibility_map_summary" statement 1
 select pg_check_frozen('test_view');
 ERROR:  relation "test_view" is of wrong relation kind
 DETAIL:  This operation is not supported for views.
@@ -101,6 +104,7 @@ DETAIL:  This operation is not supported for sequences.
 select pg_visibility_map_summary('test_sequence');
 ERROR:  relation "test_sequence" is of wrong relation kind
 DETAIL:  This operation is not supported for sequences.
+CONTEXT:  SQL function "pg_visibility_map_summary" statement 1
 select pg_check_frozen('test_sequence');
 ERROR:  relation "test_sequence" is of wrong relation kind
 DETAIL:  This operation is not supported for sequences.
@@ -120,6 +124,7 @@ DETAIL:  This operation is not supported for foreign tables.
 select pg_visibility_map_summary('test_foreign_table');
 ERROR:  relation "test_foreign_table" is of wrong relation kind
 DETAIL:  This operation is not supported for foreign tables.
+CONTEXT:  SQL function "pg_visibility_map_summary" statement 1
 select pg_check_frozen('test_foreign_table');
 ERROR:  relation "test_foreign_table" is of wrong relation kind
 DETAIL:  This operation is not supported for foreign tables.
diff --git a/contrib/pg_visibility/pg_visibility--1.1.sql b/contrib/pg_visibility/pg_visibility--1.1.sql
index 0a29967ee6d..c2f81377363 100644
--- a/contrib/pg_visibility/pg_visibility--1.1.sql
+++ b/contrib/pg_visibility/pg_visibility--1.1.sql
@@ -37,12 +37,19 @@ RETURNS SETOF record
 AS 'MODULE_PATHNAME', 'pg_visibility_rel'
 LANGUAGE C STRICT;
 
+-- Show summary of visibility map bits for a relation and the number of blocks
+CREATE FUNCTION pg_visibility_map_summary_extended(regclass,
+    OUT all_visible bigint, OUT all_frozen bigint, OUT nblocks bigint)
+RETURNS record
+AS 'MODULE_PATHNAME', 'pg_visibility_map_summary_extended'
+LANGUAGE C STRICT;
+
 -- Show summary of visibility map bits for a relation.
 CREATE FUNCTION pg_visibility_map_summary(regclass,
     OUT all_visible bigint, OUT all_frozen bigint)
 RETURNS record
-AS 'MODULE_PATHNAME', 'pg_visibility_map_summary'
-LANGUAGE C STRICT;
+AS $$ SELECT all_visible, all_frozen FROM pg_visibility_map_summary_extended($1) $$
+LANGUAGE SQL;
 
 -- Show tupleids of non-frozen tuples if any in all_frozen pages
 -- for a relation.
diff --git a/contrib/pg_visibility/pg_visibility.c b/contrib/pg_visibility/pg_visibility.c
index 2a4acfd1eee..48c30b222a6 100644
--- a/contrib/pg_visibility/pg_visibility.c
+++ b/contrib/pg_visibility/pg_visibility.c
@@ -44,7 +44,7 @@ PG_FUNCTION_INFO_V1(pg_visibility_map);
 PG_FUNCTION_INFO_V1(pg_visibility_map_rel);
 PG_FUNCTION_INFO_V1(pg_visibility);
 PG_FUNCTION_INFO_V1(pg_visibility_rel);
-PG_FUNCTION_INFO_V1(pg_visibility_map_summary);
+PG_FUNCTION_INFO_V1(pg_visibility_map_summary_extended);
 PG_FUNCTION_INFO_V1(pg_check_frozen);
 PG_FUNCTION_INFO_V1(pg_check_visible);
 PG_FUNCTION_INFO_V1(pg_truncate_visibility_map);
@@ -247,11 +247,11 @@ pg_visibility_rel(PG_FUNCTION_ARGS)
 }
 
 /*
- * Count the number of all-visible and all-frozen pages in the visibility
- * map for a particular relation.
+ * Count the number of all-visible and all-frozen pages in the visibility map
+ * as well as the total number of blocks of a particular relation.
  */
 Datum
-pg_visibility_map_summary(PG_FUNCTION_ARGS)
+pg_visibility_map_summary_extended(PG_FUNCTION_ARGS)
 {
 	Oid			relid = PG_GETARG_OID(0);
 	Relation	rel;
@@ -261,8 +261,8 @@ pg_visibility_map_summary(PG_FUNCTION_ARGS)
 	int64		all_visible = 0;
 	int64		all_frozen = 0;
 	TupleDesc	tupdesc;
-	Datum		values[2];
-	bool		nulls[2] = {0};
+	Datum		values[3];
+	bool		nulls[3] = {0};
 
 	rel = relation_open(relid, AccessShareLock);
 
@@ -296,6 +296,7 @@ pg_visibility_map_summary(PG_FUNCTION_ARGS)
 
 	values[0] = Int64GetDatum(all_visible);
 	values[1] = Int64GetDatum(all_frozen);
+	values[2] = Int64GetDatum(nblocks);
 
 	PG_RETURN_DATUM(HeapTupleGetDatum(heap_form_tuple(tupdesc, values, nulls)));
 }
diff --git a/doc/src/sgml/pgvisibility.sgml b/doc/src/sgml/pgvisibility.sgml
index 097f7e05661..4358e267b18 100644
--- a/doc/src/sgml/pgvisibility.sgml
+++ b/doc/src/sgml/pgvisibility.sgml
@@ -99,6 +99,18 @@
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><function>pg_visibility_map_summary_extended(relation regclass, all_visible OUT bigint, all_frozen OUT bigint, nblocks OUT bigint) returns record</function></term>
+
+    <listitem>
+     <para>
+      Returns the number of all-visible pages, the number of all-frozen pages,
+      and the total number of blocks in the relation according to the
+      visibility map.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><function>pg_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid</function></term>
 
-- 
2.37.2

