From 85b4ba73423b480902206ca04330c1cbea371c3c Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 25 Nov 2020 14:04:28 -0500 Subject: [PATCH] Doc: minor improvements for section 11.2 "Index Types". MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Break the per-index-type discussions into '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 --- doc/src/sgml/indices.sgml | 134 +++++++++++++++++++++----------------- 1 file changed, 74 insertions(+), 60 deletions(-) diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index 671299ff05..623962d1d8 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -118,32 +118,39 @@ CREATE INDEX test1_id_index ON test1 (id); B-tree, Hash, GiST, SP-GiST, GIN and BRIN. Each index type uses a different algorithm that is best suited to different types of queries. - By default, the CREATE INDEX command creates + By default, the CREATE + INDEX command creates B-tree indexes, which fit the most common situations. + The other index types are selected by writing the keyword + USING followed by the index type name. + For example, to create a Hash index: + +CREATE INDEX name ON table USING HASH (column); + - + + B-Tree + index - B-tree + B-Tree - B-tree + B-Tree index + + B-trees can handle equality and range queries on data that can be sorted into some ordering. In particular, the PostgreSQL query planner will consider using a B-tree index whenever an indexed column is involved in a comparison using one of these operators: - - < - <= - = - >= - > - + +<   <=   =   >=   > + Constructs equivalent to combinations of these operators, such as BETWEEN and IN, 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 often helpful. + + + + Hash - index hash @@ -182,17 +192,24 @@ CREATE INDEX test1_id_index ON test1 (id); hash index - 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 - = operator. - The following command is used to create a hash index: - -CREATE INDEX name ON table USING HASH (column); - - + 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: + + += + + + + + + GiST + index GiST @@ -201,6 +218,8 @@ CREATE INDEX name ON table GiST index + + GiST indexes are not a single kind of index, but rather an infrastructure within which many different indexing strategies can be implemented. Accordingly, the particular operators with which a GiST index can be @@ -210,20 +229,9 @@ CREATE INDEX name ON table for several two-dimensional geometric data types, which support indexed queries using these operators: - - << - &< - &> - >> - <<| - &<| - |&> - |>> - @> - <@ - ~= - && - + +<<   &<   &>   >>   <<|   &<|   |&>   |>>   @>   <@   ~=   && + (See for the meaning of these operators.) @@ -246,8 +254,11 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; In , operators that can be used in this way are listed in the column Ordering Operators. + + + + SP-GiST - index SP-GiST @@ -256,6 +267,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; SP-GiST index + + SP-GiST indexes, like GiST indexes, offer an infrastructure that supports various kinds of searches. SP-GiST permits implementation of a wide range 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 queries using these operators: - - << - >> - ~= - <@ - <^ - >^ - + +<<   >>   ~=   <@   <<|   |>> + (See for the meaning of these operators.) @@ -283,11 +291,14 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; Like GiST, SP-GiST supports nearest-neighbor searches. For SP-GiST operator classes that support distance ordering, the - corresponding operator is specified in the Ordering Operators + corresponding operator is listed in the Ordering Operators column in . + + + + GIN - index GIN @@ -296,6 +307,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; GIN index + + GIN indexes are inverted indexes which are appropriate for data values that contain multiple component values, such as arrays. An 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; PostgreSQL includes a GIN operator class for arrays, which supports indexed queries using these operators: - - <@ - @> - = - && - + +<@   @>   =   && + (See for the meaning of these operators.) @@ -327,8 +337,11 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; classes are available in the contrib collection or as separate projects. For more information see . + + + + BRIN - index BRIN @@ -337,8 +350,12 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; BRIN index + + BRIN indexes (a shorthand for Block Range INdexes) store summaries about 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, BRIN can support many different indexing strategies, 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 using these operators: - - < - <= - = - >= - > - + +<   <=   =   >=   > + The BRIN operator classes included in the standard distribution are documented in . For more information see . +