On Tue, 2024-02-27 at 09:48 -0500, Stephen Frost wrote:
> Attached is an updated patch which drops the 'such as' and adds a
> sentence mentioning that BRIN is the only in-core summarizing index.
The original patch reads more clearly to me. In v4, summarizing (the
exception) feels like it's dominating the description.
Also, is it standard practice to backport this kind of doc update? I
ordinarily wouldn't be inclined to do so, but v4 seems targeted at 16
as well.
Attached my own suggested wording that hopefully addresses Stephen and
Alvaro's concerns. I agree that it's tricky to write so I took a more
minimalist approach:
* I got rid of the "In summary" sentence because (a) it's confusing
now that we're talking about summarizing indexes; and (b) it's not
summarizing anything, it's just redundant.
* I removed the mention partial or expression indexes. It's a bit
redundant and doesn't seem especially helpful in this context.
If this is agreeable I can commit it.
Regards,
Jeff Davis
From d17ecaf1af52ba5b055c19b465d77cc53f825747 Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfr...@snowman.net>
Date: Mon, 26 Feb 2024 17:17:54 -0500
Subject: [PATCH v5] docs: Update HOT update docs for 19d8e2308b
Commit 19d8e2308b changed when the HOT update optimization is possible
but neglected to update the Heap-Only Tuples (HOT) documentation. This
patch updates that documentation accordingly.
Author: Elizabeth Christensen
Reviewed-By: Stephen Frost, Alvaro Herrera
Discussion: https://postgr.es/m/CABoUFXRjisr58Ct_3VsFEdQx+fJeQTWTdJnM7XAp=8mubto...@mail.gmail.com
---
doc/src/sgml/storage.sgml | 21 +++++++++++----------
1 file changed, 11 insertions(+), 10 deletions(-)
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 652946db7d..2e1914b95b 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -1097,8 +1097,10 @@ data. Empty in ordinary tables.</entry>
<itemizedlist>
<listitem>
<para>
- The update does not modify any columns referenced by the table's
- indexes, including expression and partial indexes.
+ The update does not modify any columns referenced by the table's indexes,
+ not including summarizing indexes. The only summarizing index method in
+ the core <productname>PostgreSQL</productname> distribution is <link
+ linkend="brin">BRIN</link>.
</para>
</listitem>
<listitem>
@@ -1114,7 +1116,8 @@ data. Empty in ordinary tables.</entry>
<itemizedlist>
<listitem>
<para>
- New index entries are not needed to represent updated rows.
+ New index entries are not needed to represent updated rows, however,
+ summary indexes may still need to be updated.
</para>
</listitem>
<listitem>
@@ -1130,14 +1133,12 @@ data. Empty in ordinary tables.</entry>
</para>
<para>
- In summary, heap-only tuple updates can only be created
- if columns used by indexes are not updated. You can
- increase the likelihood of sufficient page space for
+ You can increase the likelihood of sufficient page space for
<acronym>HOT</acronym> updates by decreasing a table's <link
- linkend="reloption-fillfactor"><literal>fillfactor</literal></link>.
- If you don't, <acronym>HOT</acronym> updates will still happen because
- new rows will naturally migrate to new pages and existing pages with
- sufficient free space for new row versions. The system view <link
+ linkend="reloption-fillfactor"><literal>fillfactor</literal></link>. If you
+ don't, <acronym>HOT</acronym> updates will still happen because new rows
+ will naturally migrate to new pages and existing pages with sufficient free
+ space for new row versions. The system view <link
linkend="monitoring-pg-stat-all-tables-view">pg_stat_all_tables</link>
allows monitoring of the occurrence of HOT and non-HOT updates.
</para>
--
2.34.1
