database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-02 11:44:50 +03:00
Code

docs: Merge separate chapters on built-in index AMs into one.

Browse Source 
The documentation index is getting very long, which makes it hard
to find things. Since these chapters are all very similar in structure
and content, merging them is a natural way of reducing the size of
the toplevel index.

Rather than actually combining all of the SGML into a single file,
keep one file per <sect1>, and add a glue file that includes all
of them.

Discussion: http://postgr.es/m/CA+Tgmob7_uoYuS2=rVwpVXaRwP-UXz+++saYTC-BCZ42QzSNKQ@mail.gmail.com
This commit is contained in:
Robert Haas 2024-03-20 11:51:53 -04:00
parent 10e3226ba1
commit fe8eaa5442
9 changed files with 100 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/src/sgml/brin.sgml
View File

@ -1,6 +1,6 @@
<!-- doc/src/sgml/brin.sgml --> <!-- doc/src/sgml/brin.sgml -->
<chapter id="brin"> <sect1 id="brin">
<title>BRIN Indexes</title> <title>BRIN Indexes</title>
<indexterm> <indexterm>
@ -8,7 +8,7 @@
<secondary>BRIN</secondary> <secondary>BRIN</secondary>
</indexterm> </indexterm>
<sect1 id="brin-intro"> <sect2 id="brin-intro">
<title>Introduction</title> <title>Introduction</title>
<para> <para>
@ -64,7 +64,7 @@
be more precise and more data blocks can be skipped during an index scan. be more precise and more data blocks can be skipped during an index scan.
</para> </para>
<sect2 id="brin-operation"> <sect3 id="brin-operation">
<title>Index Maintenance</title> <title>Index Maintenance</title>
<para> <para>
@ -136,10 +136,10 @@ LOG: request for BRIN range summarization for index "brin_wi_idx" page 128 was
See <xref linkend="functions-admin-index"/> for details. See <xref linkend="functions-admin-index"/> for details.
</para> </para>
</sect2> </sect3>
</sect1> </sect2>
<sect1 id="brin-builtin-opclasses"> <sect2 id="brin-builtin-opclasses">
<title>Built-in Operator Classes</title> <title>Built-in Operator Classes</title>
<para> <para>
@ -743,7 +743,7 @@ LOG: request for BRIN range summarization for index "brin_wi_idx" page 128 was
</tgroup> </tgroup>
</table> </table>
<sect2 id="brin-builtin-opclasses--parameters"> <sect3 id="brin-builtin-opclasses--parameters">
<title>Operator Class Parameters</title> <title>Operator Class Parameters</title>
<para> <para>
@ -808,11 +808,11 @@ LOG: request for BRIN range summarization for index "brin_wi_idx" page 128 was
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</sect2> </sect3>
</sect1> </sect2>
<sect1 id="brin-extensibility"> <sect2 id="brin-extensibility">
<title>Extensibility</title> <title>Extensibility</title>
<para> <para>
@ -1340,5 +1340,5 @@ typedef struct BrinOpcInfo
<literal>float4_minmax_ops</literal> as an example of minmax, and <literal>float4_minmax_ops</literal> as an example of minmax, and
<literal>box_inclusion_ops</literal> as an example of inclusion. <literal>box_inclusion_ops</literal> as an example of inclusion.
</para> </para>
</sect2>
</sect1> </sect1>
</chapter>

32
doc/src/sgml/btree.sgml
View File

@ -1,6 +1,6 @@
<!-- doc/src/sgml/btree.sgml --> <!-- doc/src/sgml/btree.sgml -->
<chapter id="btree"> <sect1 id="btree">
<title>B-Tree Indexes</title> <title>B-Tree Indexes</title>
<indexterm> <indexterm>
@ -8,7 +8,7 @@
<secondary>B-Tree</secondary> <secondary>B-Tree</secondary>
</indexterm> </indexterm>
<sect1 id="btree-intro"> <sect2 id="btree-intro">
<title>Introduction</title> <title>Introduction</title>
<para> <para>
@ -30,9 +30,9 @@
btree <acronym>AM</acronym> make use of them. btree <acronym>AM</acronym> make use of them.
</para> </para>
</sect1> </sect2>
<sect1 id="btree-behavior"> <sect2 id="btree-behavior">
<title>Behavior of B-Tree Operator Classes</title> <title>Behavior of B-Tree Operator Classes</title>
<para> <para>
@ -200,9 +200,9 @@
planner relies on them for optimization purposes. planner relies on them for optimization purposes.
</para> </para>
</sect1> </sect2>
<sect1 id="btree-support-funcs"> <sect2 id="btree-support-funcs">
<title>B-Tree Support Functions</title> <title>B-Tree Support Functions</title>
<para> <para>
@ -585,9 +585,9 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</sect1> </sect2>
<sect1 id="btree-implementation"> <sect2 id="btree-implementation">
<title>Implementation</title> <title>Implementation</title>
<para> <para>
@ -597,7 +597,7 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
distribution for a much more detailed, internals-focused description distribution for a much more detailed, internals-focused description
of the B-Tree implementation. of the B-Tree implementation.
</para> </para>
<sect2 id="btree-structure"> <sect3 id="btree-structure">
<title>B-Tree Structure</title> <title>B-Tree Structure</title>
<para> <para>
<productname>PostgreSQL</productname> B-Tree indexes are <productname>PostgreSQL</productname> B-Tree indexes are
@ -627,9 +627,9 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
the tree structure by creating a new root page that is one level the tree structure by creating a new root page that is one level
above the original root page. above the original root page.
</para> </para>
</sect2> </sect3>
<sect2 id="btree-deletion"> <sect3 id="btree-deletion">
<title>Bottom-up Index Deletion</title> <title>Bottom-up Index Deletion</title>
<para> <para>
B-Tree indexes are not directly aware that under MVCC, there might B-Tree indexes are not directly aware that under MVCC, there might
@ -731,9 +731,9 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
two logical rows whose lifetimes span the same two logical rows whose lifetimes span the same
<command>VACUUM</command> cycle). <command>VACUUM</command> cycle).
</para> </para>
</sect2> </sect3>
<sect2 id="btree-deduplication"> <sect3 id="btree-deduplication">
<title>Deduplication</title> <title>Deduplication</title>
<para> <para>
A duplicate is a leaf page tuple (a tuple that points to a table A duplicate is a leaf page tuple (a tuple that points to a table
@ -908,7 +908,7 @@ options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns
</itemizedlist> </itemizedlist>
</para> </para>
</sect2> </sect3>
</sect1> </sect2>
</chapter> </sect1>

1
doc/src/sgml/filelist.sgml
View File

@ -85,6 +85,7 @@
<!ENTITY catalogs SYSTEM "catalogs.sgml"> <!ENTITY catalogs SYSTEM "catalogs.sgml">
<!ENTITY system-views SYSTEM "system-views.sgml"> <!ENTITY system-views SYSTEM "system-views.sgml">
<!ENTITY geqo SYSTEM "geqo.sgml"> <!ENTITY geqo SYSTEM "geqo.sgml">
<!ENTITY indextypes SYSTEM "indextypes.sgml">
<!ENTITY btree SYSTEM "btree.sgml"> <!ENTITY btree SYSTEM "btree.sgml">
<!ENTITY gist SYSTEM "gist.sgml"> <!ENTITY gist SYSTEM "gist.sgml">
<!ENTITY spgist SYSTEM "spgist.sgml"> <!ENTITY spgist SYSTEM "spgist.sgml">

40
doc/src/sgml/gin.sgml
View File

@ -1,6 +1,6 @@
<!-- doc/src/sgml/gin.sgml --> <!-- doc/src/sgml/gin.sgml -->
<chapter id="gin"> <sect1 id="gin">
<title>GIN Indexes</title> <title>GIN Indexes</title>
<indexterm> <indexterm>
@ -8,7 +8,7 @@
<secondary>GIN</secondary> <secondary>GIN</secondary>
</indexterm> </indexterm>
<sect1 id="gin-intro"> <sect2 id="gin-intro">
<title>Introduction</title> <title>Introduction</title>
<para> <para>
@ -60,9 +60,9 @@
information about <acronym>GIN</acronym> on their information about <acronym>GIN</acronym> on their
<ulink url="http://www.sai.msu.su/~megera/wiki/Gin">website</ulink>. <ulink url="http://www.sai.msu.su/~megera/wiki/Gin">website</ulink>.
</para> </para>
</sect1> </sect2>
<sect1 id="gin-builtin-opclasses"> <sect2 id="gin-builtin-opclasses">
<title>Built-in Operator Classes</title> <title>Built-in Operator Classes</title>
<para> <para>
@ -140,9 +140,9 @@
See <xref linkend="json-indexing"/> for details. See <xref linkend="json-indexing"/> for details.
</para> </para>
</sect1> </sect2>
<sect1 id="gin-extensibility"> <sect2 id="gin-extensibility">
<title>Extensibility</title> <title>Extensibility</title>
<para> <para>
@ -458,9 +458,9 @@
though the actual type might be something else depending on the operator. though the actual type might be something else depending on the operator.
</para> </para>
</sect1> </sect2>
<sect1 id="gin-implementation"> <sect2 id="gin-implementation">
<title>Implementation</title> <title>Implementation</title>
<para> <para>
@ -497,7 +497,7 @@
</mediaobject> </mediaobject>
</figure> </figure>
<sect2 id="gin-fast-update"> <sect3 id="gin-fast-update">
<title>GIN Fast Update Technique</title> <title>GIN Fast Update Technique</title>
<para> <para>
@ -535,9 +535,9 @@
<acronym>GIN</acronym> index. See <xref linkend="sql-createindex"/> <acronym>GIN</acronym> index. See <xref linkend="sql-createindex"/>
for details. for details.
</para> </para>
</sect2> </sect3>
<sect2 id="gin-partial-match"> <sect3 id="gin-partial-match">
<title>Partial Match Algorithm</title> <title>Partial Match Algorithm</title>
<para> <para>
@ -554,11 +554,11 @@
to be searched, or greater than zero if the index key is past the range to be searched, or greater than zero if the index key is past the range
that could match. that could match.
</para> </para>
</sect2> </sect3>
</sect1> </sect2>
<sect1 id="gin-tips"> <sect2 id="gin-tips">
<title>GIN Tips and Tricks</title> <title>GIN Tips and Tricks</title>
<variablelist> <variablelist>
@ -653,9 +653,9 @@
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</sect1> </sect2>
<sect1 id="gin-limit"> <sect2 id="gin-limit">
<title>Limitations</title> <title>Limitations</title>
<para> <para>
@ -667,9 +667,9 @@
however that null key values contained within a non-null composite item however that null key values contained within a non-null composite item
or query value are supported. or query value are supported.
</para> </para>
</sect1> </sect2>
<sect1 id="gin-examples"> <sect2 id="gin-examples">
<title>Examples</title> <title>Examples</title>
<para> <para>
@ -709,6 +709,6 @@
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </para>
</sect1> </sect2>
</chapter> </sect1>

28
doc/src/sgml/gist.sgml
View File

@ -1,6 +1,6 @@
<!-- doc/src/sgml/gist.sgml --> <!-- doc/src/sgml/gist.sgml -->
<chapter id="gist"> <sect1 id="gist">
<title>GiST Indexes</title> <title>GiST Indexes</title>
<indexterm> <indexterm>
@ -8,7 +8,7 @@
<secondary>GiST</secondary> <secondary>GiST</secondary>
</indexterm> </indexterm>
<sect1 id="gist-intro"> <sect2 id="gist-intro">
<title>Introduction</title> <title>Introduction</title>
<para> <para>
@ -38,9 +38,9 @@
<ulink url="http://www.sai.msu.su/~megera/postgres/gist/">web site</ulink>. <ulink url="http://www.sai.msu.su/~megera/postgres/gist/">web site</ulink>.
</para> </para>
</sect1> </sect2>
<sect1 id="gist-builtin-opclasses"> <sect2 id="gist-builtin-opclasses">
<title>Built-in Operator Classes</title> <title>Built-in Operator Classes</title>
<para> <para>
@ -222,9 +222,9 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops);
</programlisting> </programlisting>
</para> </para>
</sect1> </sect2>
<sect1 id="gist-extensibility"> <sect2 id="gist-extensibility">
<title>Extensibility</title> <title>Extensibility</title>
<para> <para>
@ -1260,12 +1260,12 @@ my_stratnum(PG_FUNCTION_ARGS)
will accumulate for the duration of the operation. will accumulate for the duration of the operation.
</para> </para>
</sect1> </sect2>
<sect1 id="gist-implementation"> <sect2 id="gist-implementation">
<title>Implementation</title> <title>Implementation</title>
<sect2 id="gist-buffering-build"> <sect3 id="gist-buffering-build">
<title>GiST Index Build Methods</title> <title>GiST Index Build Methods</title>
<para> <para>
@ -1314,10 +1314,10 @@ my_stratnum(PG_FUNCTION_ARGS)
is ordered. is ordered.
</para> </para>
</sect2> </sect3>
</sect1> </sect2>
<sect1 id="gist-examples"> <sect2 id="gist-examples">
<title>Examples</title> <title>Examples</title>
<para> <para>
@ -1382,6 +1382,6 @@ my_stratnum(PG_FUNCTION_ARGS)
</variablelist> </variablelist>
</para> </para>
</sect1> </sect2>
</chapter> </sect1>

12
doc/src/sgml/hash.sgml
View File

@ -1,6 +1,6 @@
<!-- doc/src/sgml/hash.sgml --> <!-- doc/src/sgml/hash.sgml -->
<chapter id="hash-index"> <sect1 id="hash-index">
<title>Hash Indexes</title> <title>Hash Indexes</title>
<indexterm> <indexterm>
@ -8,7 +8,7 @@
<secondary>Hash</secondary> <secondary>Hash</secondary>
</indexterm> </indexterm>
<sect1 id="hash-intro"> <sect2 id="hash-intro">
<title>Overview</title> <title>Overview</title>
<para> <para>
@ -108,9 +108,9 @@
with rapidly increasing number of rows. with rapidly increasing number of rows.
</para> </para>
</sect1> </sect2>
<sect1 id="hash-implementation"> <sect2 id="hash-implementation">
<title>Implementation</title> <title>Implementation</title>
<para> <para>
@ -157,6 +157,6 @@
successfully. successfully.
</para> </para>
</sect1> </sect2>
</chapter> </sect1>

13
doc/src/sgml/indextypes.sgml Normal file
View File

@ -0,0 +1,13 @@
<!-- doc/src/sgml/indextypes.sgml -->
<chapter id="indextypes">
<title>Built-in Index Access Methods</title>
&btree;
&gist;
&spgist;
&gin;
&brin;
&hash;
</chapter>

7
doc/src/sgml/postgres.sgml
View File

@ -258,12 +258,7 @@ break is not needed in a wider output rendering.
&indexam; &indexam;
&generic-wal; &generic-wal;
&custom-rmgr; &custom-rmgr;
&btree; &indextypes;
&gist;
&spgist;
&gin;
&brin;
&hash;
&storage; &storage;
&transaction; &transaction;
&bki; &bki;

36
doc/src/sgml/spgist.sgml
View File

@ -1,6 +1,6 @@
<!-- doc/src/sgml/spgist.sgml --> <!-- doc/src/sgml/spgist.sgml -->
<chapter id="spgist"> <sect1 id="spgist">
<title>SP-GiST Indexes</title> <title>SP-GiST Indexes</title>
<indexterm> <indexterm>
@ -8,7 +8,7 @@
<secondary>SP-GiST</secondary> <secondary>SP-GiST</secondary>
</indexterm> </indexterm>
<sect1 id="spgist-intro"> <sect2 id="spgist-intro">
<title>Introduction</title> <title>Introduction</title>
<para> <para>
@ -51,9 +51,9 @@
<ulink url="http://www.sai.msu.su/~megera/wiki/spgist_dev">web site</ulink>. <ulink url="http://www.sai.msu.su/~megera/wiki/spgist_dev">web site</ulink>.
</para> </para>
</sect1> </sect2>
<sect1 id="spgist-builtin-opclasses"> <sect2 id="spgist-builtin-opclasses">
<title>Built-in Operator Classes</title> <title>Built-in Operator Classes</title>
<para> <para>
@ -191,9 +191,9 @@
search over indexed point or polygon data sets. search over indexed point or polygon data sets.
</para> </para>
</sect1> </sect2>
<sect1 id="spgist-extensibility"> <sect2 id="spgist-extensibility">
<title>Extensibility</title> <title>Extensibility</title>
<para> <para>
@ -933,9 +933,9 @@ LANGUAGE C STRICT;
<function>PG_GET_COLLATION()</function> mechanism. <function>PG_GET_COLLATION()</function> mechanism.
</para> </para>
</sect1> </sect2>
<sect1 id="spgist-implementation"> <sect2 id="spgist-implementation">
<title>Implementation</title> <title>Implementation</title>
<para> <para>
@ -944,7 +944,7 @@ LANGUAGE C STRICT;
know. know.
</para> </para>
<sect2 id="spgist-limits"> <sect3 id="spgist-limits">
<title>SP-GiST Limits</title> <title>SP-GiST Limits</title>
<para> <para>
@ -991,9 +991,9 @@ LANGUAGE C STRICT;
leaf datum does not become any smaller within ten cycles leaf datum does not become any smaller within ten cycles
of <function>choose</function> method calls. of <function>choose</function> method calls.
</para> </para>
</sect2> </sect3>
<sect2 id="spgist-null-labels"> <sect3 id="spgist-null-labels">
<title>SP-GiST Without Node Labels</title> <title>SP-GiST Without Node Labels</title>
<para> <para>
@ -1018,9 +1018,9 @@ LANGUAGE C STRICT;
for <function>choose</function> to return <literal>spgAddNode</literal>, since the set for <function>choose</function> to return <literal>spgAddNode</literal>, since the set
of nodes is supposed to be fixed in such cases. of nodes is supposed to be fixed in such cases.
</para> </para>
</sect2> </sect3>
<sect2 id="spgist-all-the-same"> <sect3 id="spgist-all-the-same">
<title><quote>All-the-Same</quote> Inner Tuples</title> <title><quote>All-the-Same</quote> Inner Tuples</title>
<para> <para>
@ -1056,11 +1056,11 @@ LANGUAGE C STRICT;
depending on how much the <function>inner_consistent</function> function normally depending on how much the <function>inner_consistent</function> function normally
assumes about the meaning of the nodes. assumes about the meaning of the nodes.
</para> </para>
</sect2> </sect3>
</sect1> </sect2>
<sect1 id="spgist-examples"> <sect2 id="spgist-examples">
<title>Examples</title> <title>Examples</title>
<para> <para>
@ -1071,6 +1071,6 @@ LANGUAGE C STRICT;
and <filename>src/backend/utils/adt/</filename> to see the code. and <filename>src/backend/utils/adt/</filename> to see the code.
</para> </para>
</sect1> </sect2>
</chapter> </sect1>