public inbox for [email protected]help / color / mirror / Atom feed
[PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE 8+ messages / 3 participants [nested] [flat]
* [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE @ 2026-03-13 08:38 Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-13 14:38 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: Ryo Matsumura (Fujitsu) @ 2026-03-13 08:38 UTC (permalink / raw) To: pgsql-hackers Hi Hackers, It looks like the EXPLAIN documentation is missing an explanation of the default values for the BUFFERS and SERIALIZE options. I've attached a patch that adds this information. While the documentation currently notes that these options are implicitly enabled when ANALYZE is specified, the default values of the parameters themselves do not appear to be documented. Best Regards Ryo Matsumura Attachments: [application/octet-stream] v1-0001-Docs-clarify-default-values-in-EXPLAIN-documentat.patch (1.2K, 3-v1-0001-Docs-clarify-default-values-in-EXPLAIN-documentat.patch) download | inline diff: From 8f98d5cb1c195b3ff3fced763a547486c4b73cb0 Mon Sep 17 00:00:00 2001 From: Ryo Matsumura <[email protected]> Date: Fri, 13 Mar 2026 10:59:25 +0900 Subject: [PATCH v1] Docs: clarify default values in EXPLAIN documentation. --- doc/src/sgml/ref/explain.sgml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index 7dee77fd366..0073a68b6e6 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -203,6 +203,7 @@ ROLLBACK; 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. + It defaults to <literal>FALSE</literal>. </para> </listitem> </varlistentry> @@ -231,6 +232,7 @@ ROLLBACK; Serialization may only be enabled when <literal>ANALYZE</literal> is also enabled. If <literal>SERIALIZE</literal> is written without an argument, <literal>TEXT</literal> is assumed. + It defaults to <literal>FALSE</literal>. </para> </listitem> </varlistentry> -- 2.47.3 ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE 2026-03-13 08:38 [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> @ 2026-03-13 14:38 ` Fujii Masao <[email protected]> 2026-03-16 09:36 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: Fujii Masao @ 2026-03-13 14:38 UTC (permalink / raw) To: Ryo Matsumura (Fujitsu) <[email protected]>; +Cc: pgsql-hackers On Fri, Mar 13, 2026 at 5:38 PM Ryo Matsumura (Fujitsu) <[email protected]> wrote: > > Hi Hackers, > > It looks like the EXPLAIN documentation is missing an explanation of the default values for the BUFFERS and SERIALIZE options. > I've attached a patch that adds this information. > While the documentation currently notes that these options are implicitly enabled when ANALYZE is specified, the default values of the parameters themselves do not appear to be documented. +1 to adding a description of the default value. format, only non-zero values are printed. Buffers information is automatically included when <literal>ANALYZE</literal> is used. + It defaults to <literal>FALSE</literal>. How about clarifying the default depending on whether ANALYZE is used? For example: When ANALYZE is used, this parameter defaults to TRUE and buffer usage information is included. Otherwise, it defaults to FALSE. argument, <literal>TEXT</literal> is assumed. + It defaults to <literal>FALSE</literal>. Does SERIALIZE actually accept FALSE? Regards, -- Fujii Masao ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE 2026-03-13 08:38 [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-13 14:38 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> @ 2026-03-16 09:36 ` Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-16 10:30 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: Ryo Matsumura (Fujitsu) @ 2026-03-16 09:36 UTC (permalink / raw) To: Fujii Masao <[email protected]>; +Cc: pgsql-hackers 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 ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE 2026-03-13 08:38 [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-13 14:38 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 2026-03-16 09:36 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> @ 2026-03-16 10:30 ` Fujii Masao <[email protected]> 2026-03-17 10:26 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE =?iso-2022-jp?B?TWF0c3VtdXJhLCBSeW8vGyRCPj5CPBsoQiAbJEJOTBsoQg==?= <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: Fujii Masao @ 2026-03-16 10:30 UTC (permalink / raw) To: Ryo Matsumura (Fujitsu) <[email protected]>; +Cc: pgsql-hackers On Mon, Mar 16, 2026 at 6:37 PM Ryo Matsumura (Fujitsu) <[email protected]> wrote: > > 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: Isn't the existing description "In text format, only non-zero values are printed." sufficient? Regards, -- Fujii Masao ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE 2026-03-13 08:38 [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-13 14:38 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 2026-03-16 09:36 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-16 10:30 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> @ 2026-03-17 10:26 ` =?iso-2022-jp?B?TWF0c3VtdXJhLCBSeW8vGyRCPj5CPBsoQiAbJEJOTBsoQg==?= <[email protected]> 2026-03-17 15:34 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: =?iso-2022-jp?B?TWF0c3VtdXJhLCBSeW8vGyRCPj5CPBsoQiAbJEJOTBsoQg==?= @ 2026-03-17 10:26 UTC (permalink / raw) To: Fujii Masao <[email protected]>; +Cc: pgsql-hackers On Mon, Mar 16, 2026 at 10:30:00 +0000, Fujii Masao <[email protected]> wrote: > Isn't the existing description "In text format, only non-zero values > are printed." sufficient? This description is sufficient. It was a careless mistake on my part. Sorry about that. I’ve attached a revised patch. Best Regards Ryo Matsumura Attachments: [application/octet-stream] v3-0001-Docs-clarify-default-values-in-EXPLAIN-documentat.patch (1.1K, 3-v3-0001-Docs-clarify-default-values-in-EXPLAIN-documentat.patch) download | inline diff: From db26274d6ee4b8bb123f1a874ec1a495dd1dee7e Mon Sep 17 00:00:00 2001 From: Ryo Matsumura <[email protected]> Date: Tue, 17 Mar 2026 19:16:09 +0900 Subject: [PATCH v3] Docs: clarify default values in EXPLAIN documentation. --- doc/src/sgml/ref/explain.sgml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index 7dee77fd366..5055dde67c7 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -201,8 +201,10 @@ 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>. </para> </listitem> </varlistentry> -- 2.47.3 ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE 2026-03-13 08:38 [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-13 14:38 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 2026-03-16 09:36 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-16 10:30 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 2026-03-17 10:26 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE =?iso-2022-jp?B?TWF0c3VtdXJhLCBSeW8vGyRCPj5CPBsoQiAbJEJOTBsoQg==?= <[email protected]> @ 2026-03-17 15:34 ` Fujii Masao <[email protected]> 2026-03-18 10:08 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: Fujii Masao @ 2026-03-17 15:34 UTC (permalink / raw) To: Matsumura, Ryo/松村 量 <[email protected]>; +Cc: pgsql-hackers On Tue, Mar 17, 2026 at 7:26 PM Matsumura, Ryo/松村 量 <[email protected]> wrote: > > On Mon, Mar 16, 2026 at 10:30:00 +0000, Fujii Masao <[email protected]> wrote: > > Isn't the existing description "In text format, only non-zero values > > are printed." sufficient? > > This description is sufficient. It was a careless mistake on my part. Sorry about that. > > I’ve attached a revised patch. Thanks for updating the patch! Since the docs already state that buffer usage is automatically included when ANALYZE is used, the focus here seems to be clarifying the behavior of BUFFERS without ANALYZE. From that perspective, it might be better to explicitly describe what happens when BUFFERS is TRUE without ANALYZE. I've updated the patch accordingly. Patch attached. Thought? Regards, -- Fujii Masao Attachments: [application/octet-stream] v4-0001-doc-Clarify-BUFFERS-behavior-without-ANALYZE-in-E.patch (1.5K, 2-v4-0001-doc-Clarify-BUFFERS-behavior-without-ANALYZE-in-E.patch) download | inline diff: From 77f16a7f5f6348e80411b2b7a4421b094be95434 Mon Sep 17 00:00:00 2001 From: Fujii Masao <[email protected]> Date: Tue, 17 Mar 2026 23:17:49 +0900 Subject: [PATCH v4] doc: Clarify BUFFERS behavior without ANALYZE in EXPLAIN This commit clarifies the documentation for the BUFFERS option of EXPLAIN by explicitly describing its behavior when ANALYZE is not specified. Author: Ryo Matsumura <[email protected]> Reviewed-by: Fujii Masao <[email protected]> Discussion: https://postgr.es/m/TYRPR01MB13457D31085CB5B246DBBA1AFE845A@TYRPR01MB13457.jpnprd01.prod.outlook.com --- doc/src/sgml/ref/explain.sgml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index 7dee77fd366..5b8b521802e 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -202,7 +202,10 @@ ROLLBACK; 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. + included by default when <literal>ANALYZE</literal> is used but + otherwise is not included by default. When this parameter is + <literal>TRUE</literal> without <literal>ANALYZE</literal>, + only buffer usage during the query planning phase is reported. </para> </listitem> </varlistentry> -- 2.51.2 ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE 2026-03-13 08:38 [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-13 14:38 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 2026-03-16 09:36 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-16 10:30 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 2026-03-17 10:26 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE =?iso-2022-jp?B?TWF0c3VtdXJhLCBSeW8vGyRCPj5CPBsoQiAbJEJOTBsoQg==?= <[email protected]> 2026-03-17 15:34 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> @ 2026-03-18 10:08 ` Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-18 23:32 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: Ryo Matsumura (Fujitsu) @ 2026-03-18 10:08 UTC (permalink / raw) To: Fujii Masao <[email protected]>; +Cc: pgsql-hackers On Tue, Mar 17, 2026 at 15:34:00 +0000, Fujii Masao <[email protected]> wrote: > Since the docs already state that buffer usage is automatically included > when ANALYZE is used, the focus here seems to be clarifying the behavior > of BUFFERS without ANALYZE. From that perspective, it might be better to > explicitly describe what happens when BUFFERS is TRUE without ANALYZE. > I've updated the patch accordingly. Patch attached. Thought? I have no objections. Sorry for my shallow understanding. Best Regards Ryo Matsumura ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE 2026-03-13 08:38 [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-13 14:38 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 2026-03-16 09:36 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-16 10:30 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 2026-03-17 10:26 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE =?iso-2022-jp?B?TWF0c3VtdXJhLCBSeW8vGyRCPj5CPBsoQiAbJEJOTBsoQg==?= <[email protected]> 2026-03-17 15:34 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Fujii Masao <[email protected]> 2026-03-18 10:08 ` Re: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> @ 2026-03-18 23:32 ` Fujii Masao <[email protected]> 0 siblings, 0 replies; 8+ messages in thread From: Fujii Masao @ 2026-03-18 23:32 UTC (permalink / raw) To: Ryo Matsumura (Fujitsu) <[email protected]>; +Cc: pgsql-hackers On Wed, Mar 18, 2026 at 7:09 PM Ryo Matsumura (Fujitsu) <[email protected]> wrote: > > On Tue, Mar 17, 2026 at 15:34:00 +0000, Fujii Masao <[email protected]> wrote: > > Since the docs already state that buffer usage is automatically included > > when ANALYZE is used, the focus here seems to be clarifying the behavior > > of BUFFERS without ANALYZE. From that perspective, it might be better to > > explicitly describe what happens when BUFFERS is TRUE without ANALYZE. > > I've updated the patch accordingly. Patch attached. Thought? > > I have no objections. I've pushed the patch. Thanks! Regards, -- Fujii Masao ^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2026-03-18 23:32 UTC | newest] Thread overview: 8+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-03-13 08:38 [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-13 14:38 ` Fujii Masao <[email protected]> 2026-03-16 09:36 ` Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-16 10:30 ` Fujii Masao <[email protected]> 2026-03-17 10:26 ` =?iso-2022-jp?B?TWF0c3VtdXJhLCBSeW8vGyRCPj5CPBsoQiAbJEJOTBsoQg==?= <[email protected]> 2026-03-17 15:34 ` Fujii Masao <[email protected]> 2026-03-18 10:08 ` Ryo Matsumura (Fujitsu) <[email protected]> 2026-03-18 23:32 ` Fujii Masao <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox