public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feeddoc: Clarify ANALYZE VERBOSE output
13+ messages / 7 participants
[nested] [flat]
* doc: Clarify ANALYZE VERBOSE output
@ 2025-10-31 07:13 Shinya Kato <shinya11.kato@gmail.com>
2026-04-05 18:08 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-05-05 23:26 ` Re: doc: Clarify ANALYZE VERBOSE output surya poondla <suryapoondla4@gmail.com>
0 siblings, 2 replies; 13+ messages in thread
From: Shinya Kato @ 2025-10-31 07:13 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Hi,
ANALYZE VERBOSE emits a detailed per-table INFO level report, like
VACUUM VERBOSE. Update the parameter description to use the same
wording.
--
Best regards,
Shinya Kato
NTT OSS Center
Attachments:
[application/octet-stream] v1-0001-doc-Clarify-ANALYZE-VERBOSE-output.patch (1.1K, 2-v1-0001-doc-Clarify-ANALYZE-VERBOSE-output.patch)
download | inline diff:
From e8c1ef8e28e393619e4af6b95564fa02a4cfcee4 Mon Sep 17 00:00:00 2001
From: Shinya Kato <shinya11.kato@gmail.com>
Date: Fri, 31 Oct 2025 16:06:42 +0900
Subject: [PATCH v1] doc: Clarify ANALYZE VERBOSE output
ANALYZE VERBOSE emits a detailed per-table INFO level report, like
VACUUM VERBOSE. Update the parameter description to use the same
wording.
Author: Shinya Kato <shinya11.kato@gmail.com>
Discussion: https://postgr.es/m/
---
doc/src/sgml/ref/analyze.sgml | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index ec81f00fecf..e0b4a2f68da 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -65,7 +65,8 @@ ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
- Enables display of progress messages at <literal>INFO</literal> level.
+ Prints a detailed analyze activity report for each table at
+ <literal>INFO</literal> level.
</para>
</listitem>
</varlistentry>
--
2.47.3
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
@ 2026-04-05 18:08 ` Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-06 04:51 ` Re: doc: Clarify ANALYZE VERBOSE output Fujii Masao <masao.fujii@gmail.com>
1 sibling, 1 reply; 13+ messages in thread
From: Maciek Sakrejda @ 2026-04-05 18:08 UTC (permalink / raw)
To: Shinya Kato <shinya11.kato@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
It makes sense to align these, but I think the existing VACUUM wording
is not great. What do you think about something like the attached?
Basically, I changed both option descriptions to just be
Prints detailed progress for each table at <literal>INFO</literal> level.
I think the idea of _progress_ is important to communicate here. The
word "report" suggests more detailed information, that comes in a
batch after the action is completed.
Thanks,
Maciek
PS: I changed the patch name because I felt the original name is
misleading with my proposed change, and I left it at v1 because
starting a different name with v2 didn't make sense, but I'm not
trying to take authorship credit: most of the work here was finding
the discrepancy.
Attachments:
[text/x-patch] v1-0001-doc-Clarify-VACUUM-VERBOSE-and-ANALYZE-VERBOSE-outpu.patch (1.7K, 2-v1-0001-doc-Clarify-VACUUM-VERBOSE-and-ANALYZE-VERBOSE-outpu.patch)
download | inline diff:
From 7753fb86bba9baee8e599b4e4a6b2e728ebd5279 Mon Sep 17 00:00:00 2001
From: Shinya Kato <shinya11.kato@gmail.com>
Date: Fri, 31 Oct 2025 16:06:42 +0900
Subject: [PATCH] doc: Clarify VACUUM VERBOSE and ANALYZE VERBOSE output
VACUUM VERBOSE and ANALYZE VERBOSE both emit detailed per-table INFO
level progress. The documentation currently calls these "reports", but
communicating progress is an important function of this feature and
the documentation should reflect that.
---
doc/src/sgml/ref/analyze.sgml | 2 +-
doc/src/sgml/ref/vacuum.sgml | 3 +--
2 files changed, 2 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index ec81f00fecf..d99b4f2eb6d 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -65,7 +65,7 @@ ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
- Enables display of progress messages at <literal>INFO</literal> level.
+ Prints detailed progress for each table at <literal>INFO</literal> level.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index ac5d083d468..994da777d9a 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -115,8 +115,7 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
- Prints a detailed vacuum activity report for each table
- at <literal>INFO</literal> level.
+ Prints detailed progress for each table at <literal>INFO</literal> level.
</para>
</listitem>
</varlistentry>
--
2.43.0
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-05 18:08 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
@ 2026-04-06 04:51 ` Fujii Masao <masao.fujii@gmail.com>
2026-04-06 05:17 ` Re: doc: Clarify ANALYZE VERBOSE output David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 13+ messages in thread
From: Fujii Masao @ 2026-04-06 04:51 UTC (permalink / raw)
To: maciek@sakrejda.org; +Cc: Shinya Kato <shinya11.kato@gmail.com>; pgsql-docs@lists.postgresql.org
On Mon, Apr 6, 2026 at 3:10 AM Maciek Sakrejda <m.sakrejda@gmail.com> wrote:
>
> It makes sense to align these, but I think the existing VACUUM wording
> is not great. What do you think about something like the attached?
> Basically, I changed both option descriptions to just be
>
> Prints detailed progress for each table at <literal>INFO</literal> level.
>
> I think the idea of _progress_ is important to communicate here. The
> word "report" suggests more detailed information, that comes in a
> batch after the action is completed.
Referring to it only as "progress" seems like a step backward, doesn't it?
The VERBOSE option reports per-table activity details (e.g., pages to scan,
buffer usage), not just progress.
Since these details are shown for each table, they can also serve as progress
indicators, but they're more than that.
If that understanding is correct, the existing term "vacuum activity report"
seems more appropriate to me. Thought?
Regards,
--
Fujii Masao
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-05 18:08 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-06 04:51 ` Re: doc: Clarify ANALYZE VERBOSE output Fujii Masao <masao.fujii@gmail.com>
@ 2026-04-06 05:17 ` David G. Johnston <david.g.johnston@gmail.com>
2026-04-08 01:49 ` Re: doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
0 siblings, 1 reply; 13+ messages in thread
From: David G. Johnston @ 2026-04-06 05:17 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@gmail.com>; +Cc: maciek@sakrejda.org <maciek@sakrejda.org>; Shinya Kato <shinya11.kato@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Sunday, April 5, 2026, Fujii Masao <masao.fujii@gmail.com> wrote:
> On Mon, Apr 6, 2026 at 3:10 AM Maciek Sakrejda <m.sakrejda@gmail.com>
> wrote:
> >
> > It makes sense to align these, but I think the existing VACUUM wording
> > is not great. What do you think about something like the attached?
> > Basically, I changed both option descriptions to just be
> >
> > Prints detailed progress for each table at <literal>INFO</literal>
> level.
> >
> > I think the idea of _progress_ is important to communicate here. The
> > word "report" suggests more detailed information, that comes in a
> > batch after the action is completed.
>
> Referring to it only as "progress" seems like a step backward, doesn't it?
> The VERBOSE option reports per-table activity details (e.g., pages to scan,
> buffer usage), not just progress.
>
> Since these details are shown for each table, they can also serve as
> progress
> indicators, but they're more than that.
>
> If that understanding is correct, the existing term "vacuum activity
> report"
> seems more appropriate to me. Thought?
>
How about something like:
“Enables sending an INFO message to the client (and server log) as each
table is processed. This message contains: etc…”
And then let’s tell the user what info they are getting and what it means
(where necessary).
I concur being specific about when these messages arrive, and IMO where,
should be specified. But losing the detail of “report” is not good; but
not sure why we are being vague so suggest we just go all-in on specificity.
David J.
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-05 18:08 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-06 04:51 ` Re: doc: Clarify ANALYZE VERBOSE output Fujii Masao <masao.fujii@gmail.com>
2026-04-06 05:17 ` Re: doc: Clarify ANALYZE VERBOSE output David G. Johnston <david.g.johnston@gmail.com>
@ 2026-04-08 01:49 ` Shinya Kato <shinya11.kato@gmail.com>
2026-04-13 21:26 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
0 siblings, 1 reply; 13+ messages in thread
From: Shinya Kato @ 2026-04-08 01:49 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Fujii Masao <masao.fujii@gmail.com>; maciek@sakrejda.org; pgsql-docs@lists.postgresql.org
On Mon, Apr 6, 2026, 14:17 David G. Johnston <david.g.johnston@gmail.com>
wrote:
>
> How about something like:
> “Enables sending an INFO message to the client (and server log) as each
> table is processed. This message contains: etc…”
>
> And then let’s tell the user what info they are getting and what it means
> (where necessary).
>
> I concur being specific about when these messages arrive, and IMO where,
> should be specified. But losing the detail of “report” is not good; but
> not sure why we are being vague so suggest we just go all-in on specificity.
>
Thank you for the suggestion. I'd prefer to keep this patch focused; since
the verbose output of both commands is subject to change, listing every
individual field in the documentation would require frequent updates.
I believe the current "Outputs" section is intentionally kept simple to
minimize maintenance overhead. While expanding it might be a worthwhile
follow-up, it probably deserves its own dedicated discussion.
--
Shinya Kato
>
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-05 18:08 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-06 04:51 ` Re: doc: Clarify ANALYZE VERBOSE output Fujii Masao <masao.fujii@gmail.com>
2026-04-06 05:17 ` Re: doc: Clarify ANALYZE VERBOSE output David G. Johnston <david.g.johnston@gmail.com>
2026-04-08 01:49 ` Re: doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
@ 2026-04-13 21:26 ` Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-13 22:28 ` Re: doc: Clarify ANALYZE VERBOSE output David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 13+ messages in thread
From: Maciek Sakrejda @ 2026-04-13 21:26 UTC (permalink / raw)
To: Shinya Kato <shinya11.kato@gmail.com>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; Fujii Masao <masao.fujii@gmail.com>; maciek@sakrejda.org; pgsql-docs@lists.postgresql.org
On Tue, Apr 7, 2026 at 6:57 PM Shinya Kato <shinya11.kato@gmail.com> wrote:
> On Mon, Apr 6, 2026, 14:17 David G. Johnston <david.g.johnston@gmail.com> wrote:
>>
>> How about something like:
>> “Enables sending an INFO message to the client (and server log) as each table is processed. This message contains: etc…”
>>
>> And then let’s tell the user what info they are getting and what it means (where necessary).
>>
>> I concur being specific about when these messages arrive, and IMO where, should be specified. But losing the detail of “report” is not good; but not sure why we are being vague so suggest we just go all-in on specificity.
>
> Thank you for the suggestion. I'd prefer to keep this patch focused; since the verbose output of both commands is subject to change, listing every individual field in the documentation would require frequent updates.
>
> I believe the current "Outputs" section is intentionally kept simple to minimize maintenance overhead. While expanding it might be a worthwhile follow-up, it probably deserves its own dedicated discussion.
+1, listing output details is signing up for busywork. But I do like
the “as each table is processed" wording: it's clear on when you'll
see output. Given the feedback above (that just using the word
"progress" obscures that you'll see actual stats), maybe something
along these lines:
"Prints detailed stats at <literal>INFO</literal> level for each table
as it is processed."
? I still think "report" is the wrong term for something that happens
incrementally.
I don't feel strongly about this, though: if everyone is okay with
consolidating on the existing VACUUM wording, that's still better than
inconsistency.
Thanks,
Maciek
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-05 18:08 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-06 04:51 ` Re: doc: Clarify ANALYZE VERBOSE output Fujii Masao <masao.fujii@gmail.com>
2026-04-06 05:17 ` Re: doc: Clarify ANALYZE VERBOSE output David G. Johnston <david.g.johnston@gmail.com>
2026-04-08 01:49 ` Re: doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-13 21:26 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
@ 2026-04-13 22:28 ` David G. Johnston <david.g.johnston@gmail.com>
2026-04-15 09:45 ` Re: doc: Clarify ANALYZE VERBOSE output Yushu Chen <gentcys@gmail.com>
2026-04-15 16:38 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <maciek@pganalyze.com>
0 siblings, 2 replies; 13+ messages in thread
From: David G. Johnston @ 2026-04-13 22:28 UTC (permalink / raw)
To: maciek@sakrejda.org; +Cc: Shinya Kato <shinya11.kato@gmail.com>; Fujii Masao <masao.fujii@gmail.com>; pgsql-docs@lists.postgresql.org
On Mon, Apr 13, 2026 at 2:28 PM Maciek Sakrejda <m.sakrejda@gmail.com>
wrote:
> On Tue, Apr 7, 2026 at 6:57 PM Shinya Kato <shinya11.kato@gmail.com>
> wrote:
> > On Mon, Apr 6, 2026, 14:17 David G. Johnston <david.g.johnston@gmail.com>
> wrote:
> >>
> >> How about something like:
> >> “Enables sending an INFO message to the client (and server log) as each
> table is processed. This message contains: etc…”
> >>
> >> And then let’s tell the user what info they are getting and what it
> means (where necessary).
> >>
> >> I concur being specific about when these messages arrive, and IMO
> where, should be specified. But losing the detail of “report” is not good;
> but not sure why we are being vague so suggest we just go all-in on
> specificity.
> >
> > Thank you for the suggestion. I'd prefer to keep this patch focused;
> since the verbose output of both commands is subject to change, listing
> every individual field in the documentation would require frequent updates.
> >
> > I believe the current "Outputs" section is intentionally kept simple to
> minimize maintenance overhead. While expanding it might be a worthwhile
> follow-up, it probably deserves its own dedicated discussion.
>
> +1, listing output details is signing up for busywork.
Given how expansive and thorough our documentation is, and the fact this is
user-facing output, I'm not seeing why this gets a pass on the
documentation requirement. That said, I concur this patch needn't be
responsible for dealing with that - I'm not even sure whether trying to do
that on the vacuum/analyze pages is even the correct choice since at least
some of what is output is object-specific and not generic to vacuum
itself. Though stuff like timings are. Even if we want to leave ourselves
the "it's undocumented so it can be changed at will" clause we can simply
write that in.
maybe something
> along these lines:
>
> "Prints detailed stats at <literal>INFO</literal> level for each table
> as it is processed."
>
>
I really don't like the word "Print" here. What the client decides to do
with the INFO message is up to them - the interface to document for the
server is simply sending the message and its details.
I was apparently mistaken about this info showing in the server log file
though.
So that leaves me with suggesting:
"Enables the sending of a detailed INFO message to the client after each
table is processed."
David J.
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-05 18:08 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-06 04:51 ` Re: doc: Clarify ANALYZE VERBOSE output Fujii Masao <masao.fujii@gmail.com>
2026-04-06 05:17 ` Re: doc: Clarify ANALYZE VERBOSE output David G. Johnston <david.g.johnston@gmail.com>
2026-04-08 01:49 ` Re: doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-13 21:26 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-13 22:28 ` Re: doc: Clarify ANALYZE VERBOSE output David G. Johnston <david.g.johnston@gmail.com>
@ 2026-04-15 09:45 ` Yushu Chen <gentcys@gmail.com>
1 sibling, 0 replies; 13+ messages in thread
From: Yushu Chen @ 2026-04-15 09:45 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: maciek@sakrejda.org; Shinya Kato <shinya11.kato@gmail.com>; Fujii Masao <masao.fujii@gmail.com>; pgsql-docs@lists.postgresql.org
Hi,
The discussion makes sense to me.
Just to add one variant for consideration:
"Emits detailed information about vacuum activity for each table in the
form of INFO and DETAIL messages."
Thanks.
On Tue, Apr 14, 2026 at 6:29 AM David G. Johnston <
david.g.johnston@gmail.com> wrote:
> On Mon, Apr 13, 2026 at 2:28 PM Maciek Sakrejda <m.sakrejda@gmail.com>
> wrote:
>
>> On Tue, Apr 7, 2026 at 6:57 PM Shinya Kato <shinya11.kato@gmail.com>
>> wrote:
>> > On Mon, Apr 6, 2026, 14:17 David G. Johnston <
>> david.g.johnston@gmail.com> wrote:
>> >>
>> >> How about something like:
>> >> “Enables sending an INFO message to the client (and server log) as
>> each table is processed. This message contains: etc…”
>> >>
>> >> And then let’s tell the user what info they are getting and what it
>> means (where necessary).
>> >>
>> >> I concur being specific about when these messages arrive, and IMO
>> where, should be specified. But losing the detail of “report” is not good;
>> but not sure why we are being vague so suggest we just go all-in on
>> specificity.
>> >
>> > Thank you for the suggestion. I'd prefer to keep this patch focused;
>> since the verbose output of both commands is subject to change, listing
>> every individual field in the documentation would require frequent updates.
>> >
>> > I believe the current "Outputs" section is intentionally kept simple to
>> minimize maintenance overhead. While expanding it might be a worthwhile
>> follow-up, it probably deserves its own dedicated discussion.
>>
>> +1, listing output details is signing up for busywork.
>
>
> Given how expansive and thorough our documentation is, and the fact this
> is user-facing output, I'm not seeing why this gets a pass on the
> documentation requirement. That said, I concur this patch needn't be
> responsible for dealing with that - I'm not even sure whether trying to do
> that on the vacuum/analyze pages is even the correct choice since at least
> some of what is output is object-specific and not generic to vacuum
> itself. Though stuff like timings are. Even if we want to leave ourselves
> the "it's undocumented so it can be changed at will" clause we can simply
> write that in.
>
> maybe something
>> along these lines:
>>
>> "Prints detailed stats at <literal>INFO</literal> level for each table
>> as it is processed."
>>
>>
> I really don't like the word "Print" here. What the client decides to do
> with the INFO message is up to them - the interface to document for the
> server is simply sending the message and its details.
>
> I was apparently mistaken about this info showing in the server log file
> though.
>
> So that leaves me with suggesting:
>
> "Enables the sending of a detailed INFO message to the client after each
> table is processed."
>
> David J.
>
>
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-05 18:08 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-06 04:51 ` Re: doc: Clarify ANALYZE VERBOSE output Fujii Masao <masao.fujii@gmail.com>
2026-04-06 05:17 ` Re: doc: Clarify ANALYZE VERBOSE output David G. Johnston <david.g.johnston@gmail.com>
2026-04-08 01:49 ` Re: doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-13 21:26 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-13 22:28 ` Re: doc: Clarify ANALYZE VERBOSE output David G. Johnston <david.g.johnston@gmail.com>
@ 2026-04-15 16:38 ` Maciek Sakrejda <maciek@pganalyze.com>
1 sibling, 0 replies; 13+ messages in thread
From: Maciek Sakrejda @ 2026-04-15 16:38 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: maciek@sakrejda.org; Shinya Kato <shinya11.kato@gmail.com>; Fujii Masao <masao.fujii@gmail.com>; pgsql-docs@lists.postgresql.org
On Mon, Apr 13, 2026 at 3:29 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>> On Tue, Apr 7, 2026 at 6:57 PM Shinya Kato <shinya11.kato@gmail.com> wrote:
>> > I believe the current "Outputs" section is intentionally kept simple to minimize maintenance overhead. While expanding it might be a worthwhile follow-up, it probably deserves its own dedicated discussion.
>>
>> +1, listing output details is signing up for busywork.
>
>
> Given how expansive and thorough our documentation is, and the fact this is user-facing output, I'm not seeing why this gets a pass on the documentation requirement. That said, I concur this patch needn't be responsible for dealing with that - I'm not even sure whether trying to do that on the vacuum/analyze pages is even the correct choice since at least some of what is output is object-specific and not generic to vacuum itself. Though stuff like timings are. Even if we want to leave ourselves the "it's undocumented so it can be changed at will" clause we can simply write that in.
It's not getting "a pass". Ultimately it's a judgment call:
maintenance cost versus existing conventions (how we document command
output in other places), utility to the user of having detailed docs
on this, and how easy it is to check the actual output by just running
the command. I think on balance it's not worth doing here, and "it's
undocumented so it can be changed at will" is equivalent to saying
nothing (so we might as well say nothing).
>> maybe something
>> along these lines:
>>
>> "Prints detailed stats at <literal>INFO</literal> level for each table
>> as it is processed."
>>
>
> I really don't like the word "Print" here. What the client decides to do with the INFO message is up to them - the interface to document for the server is simply sending the message and its details.
Fair enough, though we do use "print" as a synonym for "log" all over
the place. "Emit" was suggested down-thread; I think that's also a
good choice. Your "Sends" below also works.
> I was apparently mistaken about this info showing in the server log file though.
>
> So that leaves me with suggesting:
>
> "Enables the sending of a detailed INFO message to the client after each table is processed."
I'd simplify it to just
"Sends a detailed INFO message to the client after each table is processed."
Technically the option itself is not doing the sending, but the
relationship of the option to the behavior is obvious, and I don't
think complicating the language to reflect the actual mechanism adds
anything.
Thanks,
Maciek
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
@ 2026-05-05 23:26 ` surya poondla <suryapoondla4@gmail.com>
2026-05-11 20:12 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
1 sibling, 1 reply; 13+ messages in thread
From: surya poondla @ 2026-05-05 23:26 UTC (permalink / raw)
To: Shinya Kato <shinya11.kato@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
Hi All,
Thanks everyone this is a very interesting discussion.
I agree with Shinya that keeping this patch focused is the right call,
documenting every verbose output field is a separate project.
On the wording debate: I think David and Maciek are both pointing at
the same real issue, the description should convey (a) "what kind of
information" users will see, and (b) "when" they'll see it.
Given that, I'd suggest leaning toward something like:
"Sends a detailed INFO message to the client for each table as it is
processed."
I feel with the above message we balance, the server's perspective ("sends"
rather than "prints"), and conveys timing ("after each table is
processed").
This same phrasing could work for both VACUUM and ANALYZE VERBOSE, keeping
them consistent.
Regards,
Surya Poondla
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-05-05 23:26 ` Re: doc: Clarify ANALYZE VERBOSE output surya poondla <suryapoondla4@gmail.com>
@ 2026-05-11 20:12 ` Maciek Sakrejda <m.sakrejda@gmail.com>
2026-05-14 12:14 ` Re: doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
0 siblings, 1 reply; 13+ messages in thread
From: Maciek Sakrejda @ 2026-05-11 20:12 UTC (permalink / raw)
To: surya poondla <suryapoondla4@gmail.com>; +Cc: Shinya Kato <shinya11.kato@gmail.com>; pgsql-docs@lists.postgresql.org
On Tue, May 5, 2026 at 4:26 PM surya poondla <suryapoondla4@gmail.com> wrote:
> On the wording debate: I think David and Maciek are both pointing at
> the same real issue, the description should convey (a) "what kind of
> information" users will see, and (b) "when" they'll see it.
>
> Given that, I'd suggest leaning toward something like:
> "Sends a detailed INFO message to the client for each table as it is processed."
>
> I feel with the above message we balance, the server's perspective ("sends" rather than "prints"), and conveys timing ("after each table is processed").
I agree with the analysis, and I think the proposed wording works well.
> This same phrasing could work for both VACUUM and ANALYZE VERBOSE, keeping them consistent.
+1 for consistency.
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-05-05 23:26 ` Re: doc: Clarify ANALYZE VERBOSE output surya poondla <suryapoondla4@gmail.com>
2026-05-11 20:12 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
@ 2026-05-14 12:14 ` Shinya Kato <shinya11.kato@gmail.com>
2026-05-18 16:35 ` Re: doc: Clarify ANALYZE VERBOSE output surya poondla <suryapoondla4@gmail.com>
0 siblings, 1 reply; 13+ messages in thread
From: Shinya Kato @ 2026-05-14 12:14 UTC (permalink / raw)
To: maciek@sakrejda.org; +Cc: surya poondla <suryapoondla4@gmail.com>; pgsql-docs@lists.postgresql.org
On Tue, May 12, 2026 at 5:15 AM Maciek Sakrejda <m.sakrejda@gmail.com> wrote:
>
> On Tue, May 5, 2026 at 4:26 PM surya poondla <suryapoondla4@gmail.com> wrote:
> > On the wording debate: I think David and Maciek are both pointing at
> > the same real issue, the description should convey (a) "what kind of
> > information" users will see, and (b) "when" they'll see it.
> >
> > Given that, I'd suggest leaning toward something like:
> > "Sends a detailed INFO message to the client for each table as it is processed."
> >
> > I feel with the above message we balance, the server's perspective ("sends" rather than "prints"), and conveys timing ("after each table is processed").
>
> I agree with the analysis, and I think the proposed wording works well.
>
> > This same phrasing could work for both VACUUM and ANALYZE VERBOSE, keeping them consistent.
>
> +1 for consistency.
Sorry for the delayed response, and thank you for the feedback. I
agree with the points raised, so I have updated the patch accordingly.
--
Best regards,
Shinya Kato
NTT OSS Center
Attachments:
[application/octet-stream] v2-0001-doc-Clarify-VERBOSE-output-for-ANALYZE-and-VACUUM.patch (2.2K, 2-v2-0001-doc-Clarify-VERBOSE-output-for-ANALYZE-and-VACUUM.patch)
download | inline diff:
From 71b4878918abf8915c7cbfea24b90668a793c61e Mon Sep 17 00:00:00 2001
From: Shinya Kato <shinya11.kato@gmail.com>
Date: Thu, 14 May 2026 21:12:04 +0900
Subject: [PATCH v2] doc: Clarify VERBOSE output for ANALYZE and VACUUM
ANALYZE VERBOSE emits a detailed per-table INFO level report, like
VACUUM VERBOSE. Reword both option descriptions to convey the
server's perspective ("sends" rather than "prints") and to clarify
the timing of the output. Use identical wording for the two commands
for consistency.
Author: Shinya Kato <shinya11.kato@gmail.com>
Reviewed-by: Maciek Sakrejda <m.sakrejda@gmail.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Surya Poondla <suryapoondla4@gmail.com>
Reviewed-by: Yushu Chen <gentcys@gmail.com>
Discussion: https://postgr.es/m/CAOzEurTpMTUEW8kHu-zKB0EBtuPfpvyoJ--8pxKe87p24BGrpg@mail.gmail.com
---
doc/src/sgml/ref/analyze.sgml | 3 ++-
doc/src/sgml/ref/vacuum.sgml | 4 ++--
2 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index ec81f00fecf..aee7a4f560d 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -65,7 +65,8 @@ ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
- Enables display of progress messages at <literal>INFO</literal> level.
+ Sends a detailed <literal>INFO</literal> message to the client
+ for each table as it is processed.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index bd5dcaf86a5..06f64f3827f 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -129,8 +129,8 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
- Prints a detailed vacuum activity report for each table
- at <literal>INFO</literal> level.
+ Sends a detailed <literal>INFO</literal> message to the client
+ for each table as it is processed.
</para>
</listitem>
</varlistentry>
--
2.47.3
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: doc: Clarify ANALYZE VERBOSE output
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-05-05 23:26 ` Re: doc: Clarify ANALYZE VERBOSE output surya poondla <suryapoondla4@gmail.com>
2026-05-11 20:12 ` Re: doc: Clarify ANALYZE VERBOSE output Maciek Sakrejda <m.sakrejda@gmail.com>
2026-05-14 12:14 ` Re: doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
@ 2026-05-18 16:35 ` surya poondla <suryapoondla4@gmail.com>
0 siblings, 0 replies; 13+ messages in thread
From: surya poondla @ 2026-05-18 16:35 UTC (permalink / raw)
To: Shinya Kato <shinya11.kato@gmail.com>; +Cc: maciek@sakrejda.org; pgsql-docs@lists.postgresql.org
Hi Shinya,
The updated patch looks good to me.
Regards,
Surya Poondla
^ permalink raw reply [nested|flat] 13+ messages in thread
end of thread, other threads:[~2026-05-18 16:35 UTC | newest]
Thread overview: 13+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2025-10-31 07:13 doc: Clarify ANALYZE VERBOSE output Shinya Kato <shinya11.kato@gmail.com>
2026-04-05 18:08 ` Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-06 04:51 ` Fujii Masao <masao.fujii@gmail.com>
2026-04-06 05:17 ` David G. Johnston <david.g.johnston@gmail.com>
2026-04-08 01:49 ` Shinya Kato <shinya11.kato@gmail.com>
2026-04-13 21:26 ` Maciek Sakrejda <m.sakrejda@gmail.com>
2026-04-13 22:28 ` David G. Johnston <david.g.johnston@gmail.com>
2026-04-15 09:45 ` Yushu Chen <gentcys@gmail.com>
2026-04-15 16:38 ` Maciek Sakrejda <maciek@pganalyze.com>
2026-05-05 23:26 ` surya poondla <suryapoondla4@gmail.com>
2026-05-11 20:12 ` Maciek Sakrejda <m.sakrejda@gmail.com>
2026-05-14 12:14 ` Shinya Kato <shinya11.kato@gmail.com>
2026-05-18 16:35 ` surya poondla <suryapoondla4@gmail.com>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox