mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: minor improvements for section 11.2 "Index Types".

Browse Source 
Break the per-index-type discussions into <sect2>'s so as to make
them more visually separate and easier to find.  Improve the markup,
and make a couple of small wording adjustments.

This also fixes one stray reference to the now-deprecated point
operators <^ and >^.

Dagfinn Ilmari Mannsåker, reviewed by David Johnston and Jürgen Purtz

Discussion: https://postgr.es/m/877dukhvzg.fsf@wibble.ilmari.org
This commit is contained in:
Tom Lane 2020-11-25 14:04:28 -05:00
parent 2432b1a040
commit 85b4ba7342
1 changed files with 74 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
doc/src/sgml/indices.sgml
View File

@ -118,32 +118,39 @@ CREATE INDEX test1_id_index ON test1 (id);
B-tree, Hash, GiST, SP-GiST, GIN and BRIN. B-tree, Hash, GiST, SP-GiST, GIN and BRIN.
Each index type uses a different Each index type uses a different
algorithm that is best suited to different types of queries. algorithm that is best suited to different types of queries.
By default, the <command>CREATE INDEX</command> command creates By default, the <link linkend="sql-createindex"><command>CREATE
INDEX</command></link> command creates
B-tree indexes, which fit the most common situations. B-tree indexes, which fit the most common situations.
The other index types are selected by writing the keyword
<literal>USING</literal> followed by the index type name.
For example, to create a Hash index:
<programlisting>
CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable> USING HASH (<replaceable>column</replaceable>);
</programlisting>
</para> </para>
<para> <sect2 id="indexes-types-btree">
<title>B-Tree</title>
<indexterm> <indexterm>
<primary>index</primary> <primary>index</primary>
<secondary>B-tree</secondary> <secondary>B-Tree</secondary>
</indexterm> </indexterm>
<indexterm> <indexterm>
<primary>B-tree</primary> <primary>B-Tree</primary>
<see>index</see> <see>index</see>
</indexterm> </indexterm>
<para>
B-trees can handle equality and range queries on data that can be sorted B-trees can handle equality and range queries on data that can be sorted
into some ordering. into some ordering.
In particular, the <productname>PostgreSQL</productname> query planner In particular, the <productname>PostgreSQL</productname> query planner
will consider using a B-tree index whenever an indexed column is will consider using a B-tree index whenever an indexed column is
involved in a comparison using one of these operators: involved in a comparison using one of these operators:
<simplelist> <synopsis>
<member><literal>&lt;</literal></member> &lt; &nbsp; &lt;= &nbsp; = &nbsp; &gt;= &nbsp; &gt;
<member><literal>&lt;=</literal></member> </synopsis>
<member><literal>=</literal></member>
<member><literal>&gt;=</literal></member>
<member><literal>&gt;</literal></member>
</simplelist>
Constructs equivalent to combinations of these operators, such as Constructs equivalent to combinations of these operators, such as
<literal>BETWEEN</literal> and <literal>IN</literal>, can also be implemented with <literal>BETWEEN</literal> and <literal>IN</literal>, can also be implemented with
@ -172,8 +179,11 @@ CREATE INDEX test1_id_index ON test1 (id);
This is not always faster than a simple scan and sort, but it is This is not always faster than a simple scan and sort, but it is
often helpful. often helpful.
</para> </para>
</sect2>
<sect2 id="indexes-types-hash">
<title>Hash</title>
<para>
<indexterm> <indexterm>
<primary>index</primary> <primary>index</primary>
<secondary>hash</secondary> <secondary>hash</secondary>
@ -182,17 +192,24 @@ CREATE INDEX test1_id_index ON test1 (id);
<primary>hash</primary> <primary>hash</primary>
<see>index</see> <see>index</see>
</indexterm> </indexterm>
Hash indexes can only handle simple equality comparisons.
The query planner will consider using a hash index whenever an
indexed column is involved in a comparison using the
<literal>=</literal> operator.
The following command is used to create a hash index:
<synopsis>
CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable> USING HASH (<replaceable>column</replaceable>);
</synopsis>
</para>
<para> <para>
Hash indexes store a 32-bit hash code derived from the
value of the indexed column. Hence,
such indexes can only handle simple equality comparisons.
The query planner will consider using a hash index whenever an
indexed column is involved in a comparison using the
equal operator:
<synopsis>
=
</synopsis>
</para>
</sect2>
<sect2 id="indexes-type-gist">
<title>GiST</title>
<indexterm> <indexterm>
<primary>index</primary> <primary>index</primary>
<secondary>GiST</secondary> <secondary>GiST</secondary>
@ -201,6 +218,8 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
<primary>GiST</primary> <primary>GiST</primary>
<see>index</see> <see>index</see>
</indexterm> </indexterm>
<para>
GiST indexes are not a single kind of index, but rather an infrastructure GiST indexes are not a single kind of index, but rather an infrastructure
within which many different indexing strategies can be implemented. within which many different indexing strategies can be implemented.
Accordingly, the particular operators with which a GiST index can be Accordingly, the particular operators with which a GiST index can be
@ -210,20 +229,9 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
for several two-dimensional geometric data types, which support indexed for several two-dimensional geometric data types, which support indexed
queries using these operators: queries using these operators:
<simplelist> <synopsis>
<member><literal>&lt;&lt;</literal></member> &lt;&lt; &nbsp; &amp;&lt; &nbsp; &amp;&gt; &nbsp; &gt;&gt; &nbsp; &lt;&lt;| &nbsp; &amp;&lt;| &nbsp; |&amp;&gt; &nbsp; |&gt;&gt; &nbsp; @&gt; &nbsp; &lt;@ &nbsp; ~= &nbsp; &amp;&amp;
<member><literal>&amp;&lt;</literal></member> </synopsis>
<member><literal>&amp;&gt;</literal></member>
<member><literal>&gt;&gt;</literal></member>
<member><literal>&lt;&lt;|</literal></member>
<member><literal>&amp;&lt;|</literal></member>
<member><literal>|&amp;&gt;</literal></member>
<member><literal>|&gt;&gt;</literal></member>
<member><literal>@&gt;</literal></member>
<member><literal>&lt;@</literal></member>
<member><literal>~=</literal></member>
<member><literal>&amp;&amp;</literal></member>
</simplelist>
(See <xref linkend="functions-geometry"/> for the meaning of (See <xref linkend="functions-geometry"/> for the meaning of
these operators.) these operators.)
@ -246,8 +254,11 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be
used in this way are listed in the column <quote>Ordering Operators</quote>. used in this way are listed in the column <quote>Ordering Operators</quote>.
</para> </para>
</sect2>
<sect2 id="indexes-type-spgist">
<title>SP-GiST</title>
<para>
<indexterm> <indexterm>
<primary>index</primary> <primary>index</primary>
<secondary>SP-GiST</secondary> <secondary>SP-GiST</secondary>
@ -256,6 +267,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
<primary>SP-GiST</primary> <primary>SP-GiST</primary>
<see>index</see> <see>index</see>
</indexterm> </indexterm>
<para>
SP-GiST indexes, like GiST indexes, offer an infrastructure that supports SP-GiST indexes, like GiST indexes, offer an infrastructure that supports
various kinds of searches. SP-GiST permits implementation of a wide range various kinds of searches. SP-GiST permits implementation of a wide range
of different non-balanced disk-based data structures, such as quadtrees, of different non-balanced disk-based data structures, such as quadtrees,
@ -264,14 +277,9 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
for two-dimensional points, which support indexed for two-dimensional points, which support indexed
queries using these operators: queries using these operators:
<simplelist> <synopsis>
<member><literal>&lt;&lt;</literal></member> &lt;&lt; &nbsp; &gt;&gt; &nbsp; ~= &nbsp; &lt;@ &nbsp; &lt;&lt;| &nbsp; |&gt;&gt;
<member><literal>&gt;&gt;</literal></member> </synopsis>
<member><literal>~=</literal></member>
<member><literal>&lt;@</literal></member>
<member><literal>&lt;^</literal></member>
<member><literal>&gt;^</literal></member>
</simplelist>
(See <xref linkend="functions-geometry"/> for the meaning of (See <xref linkend="functions-geometry"/> for the meaning of
these operators.) these operators.)
@ -283,11 +291,14 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
<para> <para>
Like GiST, SP-GiST supports <quote>nearest-neighbor</quote> searches. Like GiST, SP-GiST supports <quote>nearest-neighbor</quote> searches.
For SP-GiST operator classes that support distance ordering, the For SP-GiST operator classes that support distance ordering, the
corresponding operator is specified in the <quote>Ordering Operators</quote> corresponding operator is listed in the <quote>Ordering Operators</quote>
column in <xref linkend="spgist-builtin-opclasses-table"/>. column in <xref linkend="spgist-builtin-opclasses-table"/>.
</para> </para>
</sect2>
<sect2 id="indexes-types-gin">
<title>GIN</title>
<para>
<indexterm> <indexterm>
<primary>index</primary> <primary>index</primary>
<secondary>GIN</secondary> <secondary>GIN</secondary>
@ -296,6 +307,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
<primary>GIN</primary> <primary>GIN</primary>
<see>index</see> <see>index</see>
</indexterm> </indexterm>
<para>
GIN indexes are <quote>inverted indexes</quote> which are appropriate for GIN indexes are <quote>inverted indexes</quote> which are appropriate for
data values that contain multiple component values, such as arrays. An data values that contain multiple component values, such as arrays. An
inverted index contains a separate entry for each component value, and inverted index contains a separate entry for each component value, and
@ -312,12 +325,9 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
<productname>PostgreSQL</productname> includes a GIN operator class <productname>PostgreSQL</productname> includes a GIN operator class
for arrays, which supports indexed queries using these operators: for arrays, which supports indexed queries using these operators:
<simplelist> <synopsis>
<member><literal>&lt;@</literal></member> &lt;@ &nbsp; @&gt; &nbsp; = &nbsp; &amp;&amp;
<member><literal>@&gt;</literal></member> </synopsis>
<member><literal>=</literal></member>
<member><literal>&amp;&amp;</literal></member>
</simplelist>
(See <xref linkend="functions-array"/> for the meaning of (See <xref linkend="functions-array"/> for the meaning of
these operators.) these operators.)
@ -327,8 +337,11 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
classes are available in the <literal>contrib</literal> collection or as separate classes are available in the <literal>contrib</literal> collection or as separate
projects. For more information see <xref linkend="gin"/>. projects. For more information see <xref linkend="gin"/>.
</para> </para>
</sect2>
<sect2 id="indexes-types-brin">
<title>BRIN</title>
<para>
<indexterm> <indexterm>
<primary>index</primary> <primary>index</primary>
<secondary>BRIN</secondary> <secondary>BRIN</secondary>
@ -337,8 +350,12 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
<primary>BRIN</primary> <primary>BRIN</primary>
<see>index</see> <see>index</see>
</indexterm> </indexterm>
<para>
BRIN indexes (a shorthand for Block Range INdexes) store summaries about BRIN indexes (a shorthand for Block Range INdexes) store summaries about
the values stored in consecutive physical block ranges of a table. the values stored in consecutive physical block ranges of a table.
Thus, they are most effective for columns whose values are well-correlated
with the physical order of the table rows.
Like GiST, SP-GiST and GIN, Like GiST, SP-GiST and GIN,
BRIN can support many different indexing strategies, BRIN can support many different indexing strategies,
and the particular operators with which a BRIN index can be used and the particular operators with which a BRIN index can be used
@ -348,18 +365,15 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
values in the column for each block range. This supports indexed queries values in the column for each block range. This supports indexed queries
using these operators: using these operators:
<simplelist> <synopsis>
<member><literal>&lt;</literal></member> &lt; &nbsp; &lt;= &nbsp; = &nbsp; &gt;= &nbsp; &gt;
<member><literal>&lt;=</literal></member> </synopsis>
<member><literal>=</literal></member>
<member><literal>&gt;=</literal></member>
<member><literal>&gt;</literal></member>
</simplelist>
The BRIN operator classes included in the standard distribution are The BRIN operator classes included in the standard distribution are
documented in <xref linkend="brin-builtin-opclasses-table"/>. documented in <xref linkend="brin-builtin-opclasses-table"/>.
For more information see <xref linkend="brin"/>. For more information see <xref linkend="brin"/>.
</para> </para>
</sect2>
</sect1> </sect1>