From 1fd3dd2048991a164c287dc29fdb78b1f7e6e14e Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 2 Jan 2023 13:02:29 -0500
Subject: Add bt_multi_page_stats() function to contrib/pageinspect.

This is like the existing bt_page_stats() function, but it can
report on a range of pages rather than just one at a time.

I don't have a huge amount of faith in the portability of the
new test cases, but they do pass in a 32-bit FreeBSD VM here.
Further adjustment may be needed depending on buildfarm results.

Hamid Akhtar, reviewed by Naeem Akhter, Bertrand Drouvot,
Bharath Rupireddy, and myself

Discussion: https://postgr.es/m/CANugjht-=oGMRmNJKMqnBC69y7vr+wHDmm0ZK6-1pJsxoBKBbA@mail.gmail.com
---
 doc/src/sgml/pageinspect.sgml | 50 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml
index d4ee34ee0fd..04aca998e7f 100644
--- a/doc/src/sgml/pageinspect.sgml
+++ b/doc/src/sgml/pageinspect.sgml
@@ -326,7 +326,7 @@ allequalimage             | f
     <listitem>
      <para>
       <function>bt_page_stats</function> returns summary information about
-      single pages of B-tree indexes.  For example:
+      a data page of a B-tree index.  For example:
 <screen>
 test=# SELECT * FROM bt_page_stats('pg_cast_oid_index', 1);
 -[ RECORD 1 ]-+-----
@@ -346,6 +346,54 @@ btpo_flags    | 3
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term>
+     <function>bt_multi_page_stats(relname text, blkno bigint, blk_count bigint) returns setof record</function>
+     <indexterm>
+      <primary>bt_multi_page_stats</primary>
+     </indexterm>
+    </term>
+
+    <listitem>
+     <para>
+      <function>bt_multi_page_stats</function> returns the same information
+      as <function>bt_page_stats</function>, but does so for each page of the
+      range of pages beginning at <parameter>blkno</parameter> and extending
+      for <parameter>blk_count</parameter> pages.
+      If <parameter>blk_count</parameter> is negative, all pages
+      from <parameter>blkno</parameter> to the end of the index are reported
+      on.  For example:
+<screen>
+test=# SELECT * FROM bt_multi_page_stats('pg_proc_oid_index', 5, 2);
+-[ RECORD 1 ]-+-----
+blkno         | 5
+type          | l
+live_items    | 367
+dead_items    | 0
+avg_item_size | 16
+page_size     | 8192
+free_size     | 808
+btpo_prev     | 4
+btpo_next     | 6
+btpo_level    | 0
+btpo_flags    | 1
+-[ RECORD 2 ]-+-----
+blkno         | 6
+type          | l
+live_items    | 367
+dead_items    | 0
+avg_item_size | 16
+page_size     | 8192
+free_size     | 808
+btpo_prev     | 5
+btpo_next     | 7
+btpo_level    | 0
+btpo_flags    | 1
+</screen>
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term>
      <function>bt_page_items(relname text, blkno bigint) returns setof record</function>
-- 
cgit v1.2.3