Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1r2Ugh-00H3K3-W2 for pgsql-docs@arkaria.postgresql.org; Mon, 13 Nov 2023 11:01:04 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.94.2) (envelope-from ) id 1r2Ugg-00Epy3-MV for pgsql-docs@arkaria.postgresql.org; Mon, 13 Nov 2023 11:01:02 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1r2Ugg-00Epxv-DV for pgsql-docs@lists.postgresql.org; Mon, 13 Nov 2023 11:01:02 +0000 Received: from smtp.outgoing.loopia.se ([93.188.3.37]) by magus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1r2Ugd-006Cgo-NM for pgsql-docs@lists.postgresql.org; Mon, 13 Nov 2023 11:01:01 +0000 Received: from s807.loopia.se (localhost [127.0.0.1]) by s807.loopia.se (Postfix) with ESMTP id 7EC532FC84BF for ; Mon, 13 Nov 2023 12:00:58 +0100 (CET) Received: from s981.loopia.se (unknown [172.22.191.5]) by s807.loopia.se (Postfix) with ESMTP id 6F38A2E27557; Mon, 13 Nov 2023 12:00:58 +0100 (CET) Received: from s474.loopia.se (unknown [172.22.191.5]) by s981.loopia.se (Postfix) with ESMTP id 6B2BB22B17DA; Mon, 13 Nov 2023 12:00:58 +0100 (CET) X-Virus-Scanned: amavisd-new at amavis.loopia.se X-Spam-Flag: NO X-Spam-Score: -1.01 X-Spam-Level: X-Spam-Status: No, score=-1.01 tagged_above=-999 required=6.2 tests=[ALL_TRUSTED=-1, T_SCC_BODY_TEXT_LINE=-0.01] autolearn=disabled Received: from s899.loopia.se ([172.22.191.5]) by s474.loopia.se (s474.loopia.se [172.22.190.14]) (amavisd-new, port 10024) with UTF8LMTP id GM0RlQFL-WnQ; Mon, 13 Nov 2023 12:00:57 +0100 (CET) X-Loopia-Auth: user X-Loopia-User: daniel@yesql.se X-Loopia-Originating-IP: 89.255.232.193 Received: from smtpclient.apple (customer-89-255-232-193.stosn.net [89.255.232.193]) (Authenticated sender: daniel@yesql.se) by s899.loopia.se (Postfix) with ESMTPSA id 4C81C2C8BAD6; Mon, 13 Nov 2023 12:00:47 +0100 (CET) From: Daniel Gustafsson Content-Type: multipart/mixed; boundary="Apple-Mail=_0DBF5305-610F-45D1-88FF-821A047DC290" Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3696.120.41.1.3\)) Subject: Re: add new acronym "AM" Date: Mon, 13 Nov 2023 12:00:20 +0100 References: <169974408805.398198.6927340566912872957@wrigleys.postgresql.org> To: alaa.attya91@gmail.com, pgsql-docs@lists.postgresql.org In-Reply-To: <169974408805.398198.6927340566912872957@wrigleys.postgresql.org> Message-Id: <6C63CE33-0F77-4E12-AC8D-3CB6E5C4FD40@yesql.se> X-Mailer: Apple Mail (2.3696.120.41.1.3) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --Apple-Mail=_0DBF5305-610F-45D1-88FF-821A047DC290 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii > On 12 Nov 2023, at 00:08, PG Doc comments form = wrote: >=20 > The following documentation comment has been logged on the website: >=20 > Page: https://www.postgresql.org/docs/16/acronyms.html > Description: >=20 > 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 --Apple-Mail=_0DBF5305-610F-45D1-88FF-821A047DC290 Content-Disposition: attachment; filename=am_acronym.diff Content-Type: application/octet-stream; x-unix-mode=0644; name="am_acronym.diff" Content-Transfer-Encoding: 7bit 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 @@ + + AM + + + Access Method + + + + ANSI 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 AM make use of them. 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 @@ + + Access Method + + + Access methods are the interfaces which + PostgreSQL use in order to access relations + and indexes. This abstraction allows for adding support for new + types of tuple storage. For more information, see + and . + + + + Analytic 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 amoptionalkey false. - One reason that an index AM might set + One reason that an index AM might set amoptionalkey 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 UPDATE 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 AM 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, - If the index AM wishes to cache data across successive index insertions + If the index AM wishes to cache data across successive index insertions within an SQL statement, it can allocate space in indexInfo->ii_Context and store a pointer to the data in indexInfo->ii_AmCache (which will be NULL @@ -387,7 +387,7 @@ ambulkdelete (IndexVacuumInfo *info, ambulkdelete might need to be called more than once when many tuples are to be deleted. The stats argument is the result of the previous call for this index (it is NULL for the first call within a - VACUUM operation). This allows the AM to accumulate statistics + VACUUM operation). This allows the AM to accumulate statistics across the whole operation. Typically, ambulkdelete will modify and return the same struct if the passed stats is not null. @@ -672,7 +672,7 @@ amgettuple (IndexScanDesc scan, If the index supports index-only scans (i.e., amcanreturn returns true for any of its columns), - then on success the AM must also check scan->xs_want_itup, + then on success the AM must also check scan->xs_want_itup, and if that is true it must return the originally indexed data for the index entry. Columns for which amcanreturn 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 @@ - Currently, the way an AM actually stores data is fairly unconstrained. For + Currently, the way an AM 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 PostgreSQL's standard page layout as described in @@ -73,7 +73,7 @@ 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 AM wants to support modifications and/or indexes, it is necessary for each tuple to have a tuple identifier (TID) consisting of a block number and an item number (see also ). It is not strictly necessary that the @@ -83,7 +83,7 @@ - For crash safety, an AM can use postgres' AM can use postgres' WAL, or a custom implementation. If WAL is chosen, either Generic WAL Records can be used, --Apple-Mail=_0DBF5305-610F-45D1-88FF-821A047DC290--