MIME-Version: 1.0
In-Reply-To: <175771747377.860.519892204627285536@wrigleys.postgresql.org>
References: <175771747377.860.519892204627285536@wrigleys.postgresql.org>
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Sat, 13 Sep 2025 15:59:32 -0700
Message-ID: 
 <CAKFQuwZwbuSoQGaTDRSg6e9YysaJWi29a5imSeUQA76n9ehTKQ@mail.gmail.com>
Subject: Re: ANALYZE being a read v write operation clarification
To: "abby.e.flint@gmail.com" <abby.e.flint@gmail.com>,
	"pgsql-docs@lists.postgresql.org" <pgsql-docs@lists.postgresql.org>
Content-Type: multipart/alternative; boundary="0000000000003a4982063eb6b91c"
Archived-At: 
 <https://www.postgresql.org/message-id/CAKFQuwZwbuSoQGaTDRSg6e9YysaJWi29a5imSeUQA76n9ehTKQ%40mail.gmail.com>
Precedence: bulk

--0000000000003a4982063eb6b91c
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Friday, September 12, 2025, PG Doc comments form <noreply@postgresql.org=
>
wrote:

> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/17/sql-analyze.html
> Description:
>
> In the ANALYZE docs it states,
> - "ANALYZE collects statistics about the contents of tables in the
> database,
> and stores the results in the pg_statistic system catalog"
> - "ANALYZE requires only a read lock on the target table".
>
> When trying to determien if this command could be run with
> `default_transaction_read_only` set to `on,` I was left stumped on whethe=
r
> this is a read only or read-write operation. It is unclear to me, what
> "stores" in the context of the "pg_statistic system catalog" means, and
> whether that requires a write operation. I'm potentially missing
> understanding on the workings of the `pg_statistic` system catalog, but
> figured this could be a small improvement made to clarify the docs about
> this operation.
>

Yes, it is a write operation - otherwise it would be pretty useless since
it has no output to the client.

It reads the contents of the named table, computes statistics, and then
saves/stores/writes them for future reference - the location being saved to
is a system catalog (a special kind of table).

If you want to propose a complete suggestion here it would be entertained,
but none of the terms seem problematic on their own. Though maybe some
requiring looking up if one is unfamiliar.  =E2=80=9Cstores the results in =
the
system catalog=E2=80=9D vs. =E2=80=9Cwrites the results to the system catal=
og=E2=80=9D seems like a
pure style choice.  They mean the same thing.  Though I=E2=80=99m probably =
biased
as a native English speaker.  But I=E2=80=99d want some other opinions in f=
avor of
changing it before I=E2=80=99d try to go improve it.

David J.

--0000000000003a4982063eb6b91c
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Friday, September 12, 2025, PG Doc comments form &lt;<a href=3D"mailto:n=
oreply@postgresql.org">noreply@postgresql.org</a>&gt; wrote:<br><blockquote=
 class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc soli=
d;padding-left:1ex">The following documentation comment has been logged on =
the website:<br>
<br>
Page: <a href=3D"https://www.postgresql.org/docs/17/sql-analyze.html" targe=
t=3D"_blank">https://www.postgresql.org/<wbr>docs/17/sql-analyze.html</a><b=
r>
Description:<br>
<br>
In the ANALYZE docs it states,<br>
- &quot;ANALYZE collects statistics about the contents of tables in the dat=
abase,<br>
and stores the results in the pg_statistic system catalog&quot;<br>
- &quot;ANALYZE requires only a read lock on the target table&quot;.<br>
<br>
When trying to determien if this command could be run with<br>
`default_transaction_read_<wbr>only` set to `on,` I was left stumped on whe=
ther<br>
this is a read only or read-write operation. It is unclear to me, what<br>
&quot;stores&quot; in the context of the &quot;pg_statistic system catalog&=
quot; means, and<br>
whether that requires a write operation. I&#39;m potentially missing<br>
understanding on the workings of the `pg_statistic` system catalog, but<br>
figured this could be a small improvement made to clarify the docs about<br=
>
this operation.<br>
</blockquote><div><br></div><div>Yes, it is a write operation - otherwise i=
t would be pretty useless since it has no output to the client.</div><div><=
br></div><div>It reads the contents of the named table, computes statistics=
, and then saves/stores/writes them for future reference - the location bei=
ng saved to is a system catalog (a special kind of table).</div><div><br></=
div><div>If you want to propose a complete suggestion here it would be ente=
rtained, but none of the terms seem problematic on their own. Though maybe =
some requiring looking up if one is unfamiliar. =C2=A0=E2=80=9Cstores the r=
esults in the system catalog=E2=80=9D vs. =E2=80=9Cwrites the results to th=
e system catalog=E2=80=9D seems like a pure style choice.=C2=A0 They mean t=
he same thing.=C2=A0 Though I=E2=80=99m probably biased as a native English=
 speaker.=C2=A0 But I=E2=80=99d want some other opinions in favor of changi=
ng it before I=E2=80=99d try to go improve it.</div><div><br></div><div>Dav=
id J.</div><div><br></div>

--0000000000003a4982063eb6b91c--