pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedadd new acronym "AM"
4+ messages / 3 participants
[nested] [flat]
* add new acronym "AM"
@ 2023-11-11 23:08 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 4+ messages in thread
From: PG Doc comments form @ 2023-11-11 23:08 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: alaa.attya91@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/16/acronyms.html
Description:
while reading the progres codebase, i could find you're using the acronym
"AM" which denotes "Access Method". it's be nice to add it to the list of
acronyms
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: add new acronym "AM"
@ 2023-11-13 11:00 Daniel Gustafsson <daniel@yesql.se>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 4+ messages in thread
From: Daniel Gustafsson @ 2023-11-13 11:00 UTC (permalink / raw)
To: alaa.attya91@gmail.com; pgsql-docs@lists.postgresql.org
> On 12 Nov 2023, at 00:08, PG Doc comments form <noreply@postgresql.org> wrote:
>
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/16/acronyms.html
> Description:
>
> while reading the progres codebase, i could find you're using the acronym
> "AM" which denotes "Access Method". it's be nice to add it to the list of
> acronyms
That's a fair point. It's sort of hard to refer back from the acronym list
though since we don't have a single Access Method section but instead one for
Indexes and one for Relations. In the attached diff I propose that we add a
glossary entry for Access Method (suggested better wording much appreciated)
which the acronym can refer to. Being such a core concept it doesn't seem like
a bad idea to explain it.
--
Daniel Gustafsson
Attachments:
[application/octet-stream] am_acronym.diff (6.2K, ../../6C63CE33-0F77-4E12-AC8D-3CB6E5C4FD40@yesql.se/2-am_acronym.diff)
download | inline diff:
diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index 22e0dc5c70..817d062c7e 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -9,6 +9,15 @@
<variablelist>
+ <varlistentry>
+ <term><acronym>AM</acronym></term>
+ <listitem>
+ <para>
+ <link linkend="glossary-am">Access Method</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><acronym>ANSI</acronym></term>
<listitem>
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index 6f608a14bf..be8210286b 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -27,7 +27,7 @@
and understanding of sorting semantics. Therefore, they've acquired
some features that go beyond what would be needed just to support btree
indexes, and parts of the system that are quite distant from the
- btree AM make use of them.
+ btree <acronym>AM</acronym> make use of them.
</para>
</sect1>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index fe8def41d0..de415445d4 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -39,6 +39,19 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-am">
+ <glossterm>Access Method</glossterm>
+ <glossdef>
+ <para>
+ Access methods are the interfaces which
+ <productname>PostgreSQL</productname> use in order to access relations
+ and indexes. This abstraction allows for adding support for new
+ types of tuple storage. For more information, see <xref linkend="indexam" />
+ and <xref linkend="tableam" />.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry>
<glossterm>Analytic function</glossterm>
<glosssee otherterm="glossary-window-function" />
diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 30eda37afa..133d4180ea 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -212,7 +212,7 @@ typedef struct IndexAmRoutine
the first; however they are permitted to require some restriction to
appear for the first index column, and this is signaled by setting
<structfield>amoptionalkey</structfield> false.
- One reason that an index AM might set
+ One reason that an index <acronym>AM</acronym> might set
<structfield>amoptionalkey</structfield> false is if it doesn't index
null values. Since most indexable operators are
strict and hence cannot return true for null inputs,
@@ -330,7 +330,7 @@ aminsert (Relation indexRelation,
new tuple is a logically unchanged successor MVCC tuple version. This
happens when an <command>UPDATE</command> takes place that does not
modify any columns covered by the index, but nevertheless requires a
- new version in the index. The index AM may use this hint to decide
+ new version in the index. The index <acronym>AM</acronym> may use this hint to decide
to apply bottom-up index deletion in parts of the index where many
versions of the same logical row accumulate. Note that updating a non-key
column or a column that only appears in a partial index predicate does not
@@ -355,7 +355,7 @@ aminsert (Relation indexRelation,
</para>
<para>
- If the index AM wishes to cache data across successive index insertions
+ If the index <acronym>AM</acronym> wishes to cache data across successive index insertions
within an SQL statement, it can allocate space
in <literal>indexInfo->ii_Context</literal> and store a pointer to the
data in <literal>indexInfo->ii_AmCache</literal> (which will be NULL
@@ -387,7 +387,7 @@ ambulkdelete (IndexVacuumInfo *info,
<function>ambulkdelete</function> might need to be called more than once when many
tuples are to be deleted. The <literal>stats</literal> argument is the result
of the previous call for this index (it is NULL for the first call within a
- <command>VACUUM</command> operation). This allows the AM to accumulate statistics
+ <command>VACUUM</command> operation). This allows the <acronym>AM</acronym> to accumulate statistics
across the whole operation. Typically, <function>ambulkdelete</function> will
modify and return the same struct if the passed <literal>stats</literal> is not
null.
@@ -672,7 +672,7 @@ amgettuple (IndexScanDesc scan,
If the index supports <link linkend="indexes-index-only-scans">index-only
scans</link> (i.e., <function>amcanreturn</function> returns true for any
of its columns),
- then on success the AM must also check <literal>scan->xs_want_itup</literal>,
+ then on success the <acronym>AM</acronym> must also check <literal>scan->xs_want_itup</literal>,
and if that is true it must return the originally indexed data for the
index entry. Columns for which <function>amcanreturn</function> returns
false can be returned as nulls.
diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml
index 6a6eb2b766..954663d29b 100644
--- a/doc/src/sgml/tableam.sgml
+++ b/doc/src/sgml/tableam.sgml
@@ -64,7 +64,7 @@
</para>
<para>
- Currently, the way an AM actually stores data is fairly unconstrained. For
+ Currently, the way an <acronym>AM</acronym> actually stores data is fairly unconstrained. For
example, it's possible, but not required, to use postgres' shared buffer
cache. In case it is used, it likely makes sense to use
<productname>PostgreSQL</productname>'s standard page layout as described in
@@ -73,7 +73,7 @@
<para>
One fairly large constraint of the table access method API is that,
- currently, if the AM wants to support modifications and/or indexes, it is
+ currently, if the <acronym>AM</acronym> wants to support modifications and/or indexes, it is
necessary for each tuple to have a tuple identifier (<acronym>TID</acronym>)
consisting of a block number and an item number (see also <xref
linkend="storage-page-layout"/>). It is not strictly necessary that the
@@ -83,7 +83,7 @@
</para>
<para>
- For crash safety, an AM can use postgres' <link
+ For crash safety, an <acronym>AM</acronym> can use postgres' <link
linkend="wal"><acronym>WAL</acronym></link>, or a custom implementation.
If <acronym>WAL</acronym> is chosen, either <link
linkend="generic-wal">Generic WAL Records</link> can be used,
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: add new acronym "AM"
@ 2023-11-13 11:20 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 4+ messages in thread
From: Alvaro Herrera @ 2023-11-13 11:20 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: alaa.attya91@gmail.com; pgsql-docs@lists.postgresql.org
On 2023-Nov-13, Daniel Gustafsson wrote:
> That's a fair point. It's sort of hard to refer back from the acronym list
> though since we don't have a single Access Method section but instead one for
> Indexes and one for Relations. In the attached diff I propose that we add a
> glossary entry for Access Method (suggested better wording much appreciated)
> which the acronym can refer to. Being such a core concept it doesn't seem like
> a bad idea to explain it.
+1 for a glossary entry.
+ Access methods are the interfaces which
+ <productname>PostgreSQL</productname> use in order to access relations
+ and indexes. This abstraction allows for adding support for new
+ types of tuple storage. For more information, see <xref linkend="indexam" />
+ and <xref linkend="tableam" />.
We don't start the glossary definition with the term we're defining.
For example, we say
Atomicity
The property of a transaction that ...
we don't say
Atomicity
Atomicity is the property of ...
So you would want your definition to be something like
"Interfaces which PostgreSQL use to ..."
I'd say "data in tables and indexes" rather than "relations and
indexes", and "data storage" instead of "tuple storage".
"For more information" should be its own <para>.
--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
Si no sabes adonde vas, es muy probable que acabes en otra parte.
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: add new acronym "AM"
@ 2023-11-13 12:38 Daniel Gustafsson <daniel@yesql.se>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 0 replies; 4+ messages in thread
From: Daniel Gustafsson @ 2023-11-13 12:38 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: alaa.attya91@gmail.com; pgsql-docs@lists.postgresql.org
> On 13 Nov 2023, at 12:20, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
>
> On 2023-Nov-13, Daniel Gustafsson wrote:
>
>> That's a fair point. It's sort of hard to refer back from the acronym list
>> though since we don't have a single Access Method section but instead one for
>> Indexes and one for Relations. In the attached diff I propose that we add a
>> glossary entry for Access Method (suggested better wording much appreciated)
>> which the acronym can refer to. Being such a core concept it doesn't seem like
>> a bad idea to explain it.
>
> +1 for a glossary entry.
>
> + Access methods are the interfaces which
> + <productname>PostgreSQL</productname> use in order to access relations
> + and indexes. This abstraction allows for adding support for new
> + types of tuple storage. For more information, see <xref linkend="indexam" />
> + and <xref linkend="tableam" />.
>
> We don't start the glossary definition with the term we're defining.
> For example, we say
> Atomicity
> The property of a transaction that ...
> we don't say
> Atomicity
> Atomicity is the property of ...
>
> So you would want your definition to be something like
> "Interfaces which PostgreSQL use to ..."
>
> I'd say "data in tables and indexes" rather than "relations and
> indexes", and "data storage" instead of "tuple storage".
>
> "For more information" should be its own <para>.
Thanks, that makes it a lot better. v2 with the above changes attached.
--
Daniel Gustafsson
Attachments:
[application/octet-stream] v2-0001-doc-Add-acronym-and-glossary-term-for-Access-Meth.patch (7.1K, ../../4F49DE18-AF28-489E-B2CB-654EC6FC9C95@yesql.se/2-v2-0001-doc-Add-acronym-and-glossary-term-for-Access-Meth.patch)
download | inline diff:
From a81e66cad5afdd250f2b904212dd78b51a65d164 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <dgustafsson@postgresql.org>
Date: Mon, 13 Nov 2023 13:19:48 +0100
Subject: [PATCH v2] doc: Add acronym and glossary term for Access Method
AM was used throughout the documentation to denote Access Method, but
the acronym was not described. This adds an acronym entry as well as
a glossary term which the acronym links to.
Reported-by: alaa.attya91@gmail.com
Reviewed-by: Alvaro Herrera <alvherre@alvh.no-ip.org>
Discussion: https://postgr.es/m/169974408805.398198.6927340566912872957@wrigleys.postgresql.org
---
doc/src/sgml/acronyms.sgml | 9 +++++++++
doc/src/sgml/btree.sgml | 2 +-
doc/src/sgml/glossary.sgml | 15 +++++++++++++++
doc/src/sgml/indexam.sgml | 10 +++++-----
doc/src/sgml/tableam.sgml | 6 +++---
5 files changed, 33 insertions(+), 9 deletions(-)
diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index 22e0dc5c70..817d062c7e 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -9,6 +9,15 @@
<variablelist>
+ <varlistentry>
+ <term><acronym>AM</acronym></term>
+ <listitem>
+ <para>
+ <link linkend="glossary-am">Access Method</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><acronym>ANSI</acronym></term>
<listitem>
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index 6f608a14bf..be8210286b 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -27,7 +27,7 @@
and understanding of sorting semantics. Therefore, they've acquired
some features that go beyond what would be needed just to support btree
indexes, and parts of the system that are quite distant from the
- btree AM make use of them.
+ btree <acronym>AM</acronym> make use of them.
</para>
</sect1>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index fe8def41d0..26b739b7ca 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -39,6 +39,21 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-am">
+ <glossterm>Access Method</glossterm>
+ <glossdef>
+ <para>
+ Interfaces which <productname>PostgreSQL</productname> use in order to
+ access data in tables and indexes. This abstraction allows for adding
+ support for new types of data storage.
+ </para>
+ <para>
+ For more information, see <xref linkend="indexam" /> and
+ <xref linkend="tableam" />.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry>
<glossterm>Analytic function</glossterm>
<glosssee otherterm="glossary-window-function" />
diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 30eda37afa..133d4180ea 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -212,7 +212,7 @@ typedef struct IndexAmRoutine
the first; however they are permitted to require some restriction to
appear for the first index column, and this is signaled by setting
<structfield>amoptionalkey</structfield> false.
- One reason that an index AM might set
+ One reason that an index <acronym>AM</acronym> might set
<structfield>amoptionalkey</structfield> false is if it doesn't index
null values. Since most indexable operators are
strict and hence cannot return true for null inputs,
@@ -330,7 +330,7 @@ aminsert (Relation indexRelation,
new tuple is a logically unchanged successor MVCC tuple version. This
happens when an <command>UPDATE</command> takes place that does not
modify any columns covered by the index, but nevertheless requires a
- new version in the index. The index AM may use this hint to decide
+ new version in the index. The index <acronym>AM</acronym> may use this hint to decide
to apply bottom-up index deletion in parts of the index where many
versions of the same logical row accumulate. Note that updating a non-key
column or a column that only appears in a partial index predicate does not
@@ -355,7 +355,7 @@ aminsert (Relation indexRelation,
</para>
<para>
- If the index AM wishes to cache data across successive index insertions
+ If the index <acronym>AM</acronym> wishes to cache data across successive index insertions
within an SQL statement, it can allocate space
in <literal>indexInfo->ii_Context</literal> and store a pointer to the
data in <literal>indexInfo->ii_AmCache</literal> (which will be NULL
@@ -387,7 +387,7 @@ ambulkdelete (IndexVacuumInfo *info,
<function>ambulkdelete</function> might need to be called more than once when many
tuples are to be deleted. The <literal>stats</literal> argument is the result
of the previous call for this index (it is NULL for the first call within a
- <command>VACUUM</command> operation). This allows the AM to accumulate statistics
+ <command>VACUUM</command> operation). This allows the <acronym>AM</acronym> to accumulate statistics
across the whole operation. Typically, <function>ambulkdelete</function> will
modify and return the same struct if the passed <literal>stats</literal> is not
null.
@@ -672,7 +672,7 @@ amgettuple (IndexScanDesc scan,
If the index supports <link linkend="indexes-index-only-scans">index-only
scans</link> (i.e., <function>amcanreturn</function> returns true for any
of its columns),
- then on success the AM must also check <literal>scan->xs_want_itup</literal>,
+ then on success the <acronym>AM</acronym> must also check <literal>scan->xs_want_itup</literal>,
and if that is true it must return the originally indexed data for the
index entry. Columns for which <function>amcanreturn</function> returns
false can be returned as nulls.
diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml
index 6a6eb2b766..954663d29b 100644
--- a/doc/src/sgml/tableam.sgml
+++ b/doc/src/sgml/tableam.sgml
@@ -64,7 +64,7 @@
</para>
<para>
- Currently, the way an AM actually stores data is fairly unconstrained. For
+ Currently, the way an <acronym>AM</acronym> actually stores data is fairly unconstrained. For
example, it's possible, but not required, to use postgres' shared buffer
cache. In case it is used, it likely makes sense to use
<productname>PostgreSQL</productname>'s standard page layout as described in
@@ -73,7 +73,7 @@
<para>
One fairly large constraint of the table access method API is that,
- currently, if the AM wants to support modifications and/or indexes, it is
+ currently, if the <acronym>AM</acronym> wants to support modifications and/or indexes, it is
necessary for each tuple to have a tuple identifier (<acronym>TID</acronym>)
consisting of a block number and an item number (see also <xref
linkend="storage-page-layout"/>). It is not strictly necessary that the
@@ -83,7 +83,7 @@
</para>
<para>
- For crash safety, an AM can use postgres' <link
+ For crash safety, an <acronym>AM</acronym> can use postgres' <link
linkend="wal"><acronym>WAL</acronym></link>, or a custom implementation.
If <acronym>WAL</acronym> is chosen, either <link
linkend="generic-wal">Generic WAL Records</link> can be used,
--
2.32.1 (Apple Git-133)
=
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2023-11-13 12:38 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-11-11 23:08 add new acronym "AM" PG Doc comments form <noreply@postgresql.org>
2023-11-13 11:00 ` Daniel Gustafsson <daniel@yesql.se>
2023-11-13 11:20 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-13 12:38 ` Daniel Gustafsson <daniel@yesql.se>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox