From a81e66cad5afdd250f2b904212dd78b51a65d164 Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson 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 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 @@ + + 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..26b739b7ca 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -39,6 +39,21 @@ + + Access Method + + + Interfaces which PostgreSQL use in order to + access data in tables and indexes. This abstraction allows for adding + support for new types of data 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, -- 2.32.1 (Apple Git-133)