public inbox for [email protected]  

help / color / mirror / Atom feed

From: Ryo Matsumura (Fujitsu) <[email protected]>
To: Fujii Masao <[email protected]>
Cc: PostgreSQL-development <[email protected]>
Subject: Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE
Date: Mon, 16 Mar 2026 09:36:56 +0000
Message-ID: <TYRPR01MB134578C74066239A8281B9308E840A@TYRPR01MB13457.jpnprd01.prod.outlook.com> (raw)
In-Reply-To: <CAHGQGwFpmEg2WgjgLLNbDBimmZ23krS2Q4FHR=0NJU2CZxvF_Q@mail.gmail.com>
References: <TYRPR01MB13457D31085CB5B246DBBA1AFE845A@TYRPR01MB13457.jpnprd01.prod.outlook.com>
	<CAHGQGwFpmEg2WgjgLLNbDBimmZ23krS2Q4FHR=0NJU2CZxvF_Q@mail.gmail.com>

On Fri, Mar 13, 2026 at 14:38 UTC, Fujii Masao <[email protected]> wrote:
>        When ANALYZE is used, this parameter defaults to TRUE and buffer usage
>        information is included. Otherwise, it defaults to FALSE.

Thanks for the comment. I hadn’t understood the implementation correctly.
It might also be worth clarifying that even when the BUFFERS(and WAL) is set to TRUE,
values are shown only when there is something to report as follows:

BUFFERS
       The number of blocks shown for an
       upper-level node includes those used by all its child nodes.  In text
-      format, only non-zero values are printed.  Buffers information is
-      automatically included when <literal>ANALYZE</literal> is used.
+      format, only non-zero values are printed.
+      When ANALYZE is used, this parameter defaults to <literal>TRUE</literal>
+      and buffer usage information is included.
+      Otherwise, it defaults to <literal>FALSE</literal>.
+      When the <literal>FORMAT</literal> is <literal>TEXT</literal>,
+      no output is produced unless there is something to report, even if it
+      is set to <literal>TRUE</literal>.

WAL
       In text format, only non-zero values are printed.
       This parameter may only be used when <literal>ANALYZE</literal> is also
       enabled.  It defaults to <literal>FALSE</literal>.
+      When the <literal>FORMAT</literal> is <literal>TEXT</literal>,
+      no output is produced unless there is something to report, even if it
+      is set to <literal>TRUE</literal>.


> Does SERIALIZE actually accept FALSE?

This was entirely my mistake. And the default value was already documented.


Best Regards
Ryo Matsumura



Attachments:

  [application/octet-stream] v2-0001-Docs-clarify-default-values-in-EXPLAIN-documentat.patch (1.8K, 3-v2-0001-Docs-clarify-default-values-in-EXPLAIN-documentat.patch)
  download | inline diff:
From 3cdb6bf2070e9ec12c89b1c966a9225c73185e70 Mon Sep 17 00:00:00 2001
From: Ryo Matsumura <[email protected]>
Date: Mon, 16 Mar 2026 18:34:44 +0900
Subject: [PATCH v2] Docs: clarify default values in EXPLAIN documentation.

---
 doc/src/sgml/ref/explain.sgml | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index 7dee77fd366..cfc412e9d34 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -201,8 +201,13 @@ ROLLBACK;
       query processing.
       The number of blocks shown for an
       upper-level node includes those used by all its child nodes.  In text
-      format, only non-zero values are printed.  Buffers information is
-      automatically included when <literal>ANALYZE</literal> is used.
+      format, only non-zero values are printed.
+      When ANALYZE is used, this parameter defaults to <literal>TRUE</literal>
+      and buffer usage information is included.
+      Otherwise, it defaults to <literal>FALSE</literal>.
+      When the <literal>FORMAT</literal> is <literal>TEXT</literal>,
+      no output is produced unless there is something to report, even if it
+      is set to <literal>TRUE</literal>.
      </para>
     </listitem>
    </varlistentry>
@@ -246,6 +251,9 @@ ROLLBACK;
       In text format, only non-zero values are printed.
       This parameter may only be used when <literal>ANALYZE</literal> is also
       enabled.  It defaults to <literal>FALSE</literal>.
+      When the <literal>FORMAT</literal> is <literal>TEXT</literal>,
+      no output is produced unless there is something to report, even if it
+      is set to <literal>TRUE</literal>.
      </para>
     </listitem>
    </varlistentry>
-- 
2.47.3

view thread (8+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected]
  Subject: Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE
  In-Reply-To: <TYRPR01MB134578C74066239A8281B9308E840A@TYRPR01MB13457.jpnprd01.prod.outlook.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox