From: Daniel Gustafsson <daniel@yesql.se>
To: alaa.attya91@gmail.com
To: pgsql-docs@lists.postgresql.org
Subject: Re: add new acronym "AM"
Date: Mon, 13 Nov 2023 12:00:20 +0100
Message-ID: <6C63CE33-0F77-4E12-AC8D-3CB6E5C4FD40@yesql.se> (raw)
In-Reply-To: <169974408805.398198.6927340566912872957@wrigleys.postgresql.org>
References: <169974408805.398198.6927340566912872957@wrigleys.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.sgmlindex 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.sgmlindex 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.sgmlindex 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.sgmlindex 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.sgmlindex 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,
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: pgsql-docs@postgresql.org
Cc: daniel@yesql.se, alaa.attya91@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: add new acronym "AM"
In-Reply-To: <6C63CE33-0F77-4E12-AC8D-3CB6E5C4FD40@yesql.se>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
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