diff --git a/doc/src/sgml/0001-Add-section-headers-to-index-types-doc_1.patch b/doc/src/sgml/0001-Add-section-headers-to-index-types-doc_1.patch new file mode 100644 index 0000000000..1919080bfc --- /dev/null +++ b/doc/src/sgml/0001-Add-section-headers-to-index-types-doc_1.patch @@ -0,0 +1,183 @@ +>From 84522dc77afd1b8ce0bf111279302888d9d3edcb Mon Sep 17 00:00:00 2001 +From: =?utf-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= +Date: Fri, 31 Jul 2020 10:20:48 +0100 +Subject: [PATCH] Add section headers to index types doc + +This makes it easier to compare the properties of different index +types at a glance. + +In passing, make the index operator lists a single line each. +--- + doc/src/sgml/indices.sgml | 81 +++++++++++++++++++-------------------- + 1 file changed, 39 insertions(+), 42 deletions(-) + +diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml +index 671299ff05..f22253f4c3 100644 +--- a/doc/src/sgml/indices.sgml ++++ b/doc/src/sgml/indices.sgml +@@ -122,6 +122,9 @@ + B-tree indexes, which fit the most common situations. + + ++ ++ B-tree ++ + + + index +@@ -137,13 +140,9 @@ + 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,6 +171,10 @@ + This is not always faster than a simple scan and sort, but it is + often helpful. + ++ ++ ++ ++ Hash + + + +@@ -191,6 +194,10 @@ + CREATE INDEX name ON table USING HASH (column); + + ++ ++ ++ ++ GiST + + + +@@ -210,20 +217,9 @@ + for several two-dimensional geometric data types, which support indexed + queries using these operators: + +- +- << +- &< +- &> +- >> +- <<| +- &<| +- |&> +- |>> +- @> +- <@ +- ~= +- && +- ++ ++<<   &<   &>   >>   <<|   &<|   |&>   |>>   @>   <@   ~=   && ++ + + (See for the meaning of + these operators.) +@@ -246,6 +242,10 @@ + In , operators that can be + used in this way are listed in the column Ordering Operators. + ++ ++ ++ ++ SP-GiST + + + +@@ -264,14 +264,9 @@ + for two-dimensional points, which support indexed + queries using these operators: + +- +- << +- >> +- ~= +- <@ +- <^ +- >^ +- ++ ++<<   >>   ~=   <@   <^   >^ ++ + + (See for the meaning of + these operators.) +@@ -286,6 +281,10 @@ + corresponding operator is specified in the Ordering Operators + column in . + ++ ++ ++ ++ GIN + + + +@@ -312,12 +311,9 @@ + PostgreSQL includes a GIN operator class + for arrays, which supports indexed queries using these operators: + +- +- <@ +- @> +- = +- && +- ++ ++<@   @>   =   && ++ + + (See for the meaning of + these operators.) +@@ -327,6 +323,10 @@ + classes are available in the contrib collection or as separate + projects. For more information see . + ++ ++ ++ ++ BRIN + + + +@@ -348,18 +348,15 @@ + 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 . + ++ + + + +-- +2.27.0 + diff --git a/doc/src/sgml/0002-Reindent-index-types-docs-after-previous-commit.patch b/doc/src/sgml/0002-Reindent-index-types-docs-after-previous-commit.patch new file mode 100644 index 0000000000..74d05fb5a5 --- /dev/null +++ b/doc/src/sgml/0002-Reindent-index-types-docs-after-previous-commit.patch @@ -0,0 +1,427 @@ +From 2a75f535e60e89ed7e2276f4775395162f364e8c Mon Sep 17 00:00:00 2001 +From: =?utf-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= +Date: Tue, 1 Sep 2020 11:48:59 +0100 +Subject: [PATCH 2/2] Reindent index types docs after previous commit + +The previous commit wrapped each index type descripiton in a `` +tag, but avoided reidenting for ease of review. This commit reindents +everything, except the `` and `` tags, which +appear to need to be in column zero. +--- + doc/src/sgml/indices.sgml | 338 +++++++++++++++++++------------------- + 1 file changed, 169 insertions(+), 169 deletions(-) + +diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml +index f22253f4c3..3e11d3917f 100644 +--- a/doc/src/sgml/indices.sgml ++++ b/doc/src/sgml/indices.sgml +@@ -125,237 +125,237 @@ + + B-tree + +- +- +- index +- 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: ++ ++ ++ index ++ 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 +- a B-tree index search. Also, an IS NULL or IS NOT +- NULL condition on an index column can be used with a B-tree index. +- ++ Constructs equivalent to combinations of these operators, such as ++ BETWEEN and IN, can also be implemented with ++ a B-tree index search. Also, an IS NULL or IS NOT ++ NULL condition on an index column can be used with a B-tree index. ++ + +- +- The optimizer can also use a B-tree index for queries involving the +- pattern matching operators LIKE and ~ +- if the pattern is a constant and is anchored to +- the beginning of the string — for example, col LIKE +- 'foo%' or col ~ '^foo', but not +- col LIKE '%bar'. However, if your database does not +- use the C locale you will need to create the index with a special +- operator class to support indexing of pattern-matching queries; see +- below. It is also possible to use +- B-tree indexes for ILIKE and +- ~*, but only if the pattern starts with +- non-alphabetic characters, i.e., characters that are not affected by +- upper/lower case conversion. +- ++ ++ The optimizer can also use a B-tree index for queries involving the ++ pattern matching operators LIKE and ~ ++ if the pattern is a constant and is anchored to ++ the beginning of the string — for example, col LIKE ++ 'foo%' or col ~ '^foo', but not ++ col LIKE '%bar'. However, if your database does not ++ use the C locale you will need to create the index with a special ++ operator class to support indexing of pattern-matching queries; see ++ below. It is also possible to use ++ B-tree indexes for ILIKE and ++ ~*, but only if the pattern starts with ++ non-alphabetic characters, i.e., characters that are not affected by ++ upper/lower case conversion. ++ + +- +- B-tree indexes can also be used to retrieve data in sorted order. +- This is not always faster than a simple scan and sort, but it is +- often helpful. +- ++ ++ B-tree indexes can also be used to retrieve data in sorted order. ++ This is not always faster than a simple scan and sort, but it is ++ often helpful. ++ + + + + Hash + +- +- +- index +- hash +- +- +- 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: ++ ++ ++ index ++ hash ++ ++ ++ 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); + +- ++ + + + + GiST + +- +- +- index +- GiST +- +- +- 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 +- used vary depending on the indexing strategy (the operator +- class). As an example, the standard distribution of +- PostgreSQL includes GiST operator classes +- for several two-dimensional geometric data types, which support indexed +- queries using these operators: ++ ++ ++ index ++ GiST ++ ++ ++ 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 ++ used vary depending on the indexing strategy (the operator ++ class). As an example, the standard distribution of ++ PostgreSQL includes GiST operator classes ++ for several two-dimensional geometric data types, which support indexed ++ queries using these operators: + + + <<   &<   &>   >>   <<|   &<|   |&>   |>>   @>   <@   ~=   && + + +- (See for the meaning of +- these operators.) +- The GiST operator classes included in the standard distribution are +- documented in . +- Many other GiST operator +- classes are available in the contrib collection or as separate +- projects. For more information see . +- ++ (See for the meaning of ++ these operators.) ++ The GiST operator classes included in the standard distribution are ++ documented in . ++ Many other GiST operator ++ classes are available in the contrib collection or as separate ++ projects. For more information see . ++ + +- +- GiST indexes are also capable of optimizing nearest-neighbor +- searches, such as ++ ++ GiST indexes are also capable of optimizing nearest-neighbor ++ searches, such as + point '(101,456)' LIMIT 10; + ]]> + +- which finds the ten places closest to a given target point. The ability +- to do this is again dependent on the particular operator class being used. +- In , operators that can be +- used in this way are listed in the column Ordering Operators. +- ++ which finds the ten places closest to a given target point. The ability ++ to do this is again dependent on the particular operator class being used. ++ In , operators that can be ++ used in this way are listed in the column Ordering Operators. ++ + + + + SP-GiST + +- +- +- index +- SP-GiST +- +- +- 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, +- k-d trees, and radix trees (tries). As an example, the standard distribution of +- PostgreSQL includes SP-GiST operator classes +- for two-dimensional points, which support indexed +- queries using these operators: ++ ++ ++ index ++ SP-GiST ++ ++ ++ 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, ++ k-d trees, and radix trees (tries). As an example, the standard distribution of ++ PostgreSQL includes SP-GiST operator classes ++ for two-dimensional points, which support indexed ++ queries using these operators: + + + <<   >>   ~=   <@   <^   >^ + + +- (See for the meaning of +- these operators.) +- The SP-GiST operator classes included in the standard distribution are +- documented in . +- For more information see . +- ++ (See for the meaning of ++ these operators.) ++ The SP-GiST operator classes included in the standard distribution are ++ documented in . ++ For more information see . ++ + +- +- 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 +- column in . +- ++ ++ 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 ++ column in . ++ + + + + GIN + +- +- +- index +- GIN +- +- +- 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 +- can efficiently handle queries that test for the presence of specific +- component values. +- ++ ++ ++ index ++ GIN ++ ++ ++ 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 ++ can efficiently handle queries that test for the presence of specific ++ component values. ++ + +- +- Like GiST and SP-GiST, GIN can support +- many different user-defined indexing strategies, and the particular +- operators with which a GIN index can be used vary depending on the +- indexing strategy. +- As an example, the standard distribution of +- PostgreSQL includes a GIN operator class +- for arrays, which supports indexed queries using these operators: ++ ++ Like GiST and SP-GiST, GIN can support ++ many different user-defined indexing strategies, and the particular ++ operators with which a GIN index can be used vary depending on the ++ indexing strategy. ++ As an example, the standard distribution of ++ PostgreSQL includes a GIN operator class ++ for arrays, which supports indexed queries using these operators: + + + <@   @>   =   && + + +- (See for the meaning of +- these operators.) +- The GIN operator classes included in the standard distribution are +- documented in . +- Many other GIN operator +- classes are available in the contrib collection or as separate +- projects. For more information see . +- ++ (See for the meaning of ++ these operators.) ++ The GIN operator classes included in the standard distribution are ++ documented in . ++ Many other GIN operator ++ classes are available in the contrib collection or as separate ++ projects. For more information see . ++ + + + + BRIN + +- +- +- index +- BRIN +- +- +- BRIN +- index +- +- BRIN indexes (a shorthand for Block Range INdexes) store summaries about +- the values stored in consecutive physical block ranges of a table. +- 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 +- vary depending on the indexing strategy. +- For data types that have a linear sort order, the indexed data +- corresponds to the minimum and maximum values of the +- values in the column for each block range. This supports indexed queries +- using these operators: ++ ++ ++ index ++ BRIN ++ ++ ++ BRIN ++ index ++ ++ BRIN indexes (a shorthand for Block Range INdexes) store summaries about ++ the values stored in consecutive physical block ranges of a table. ++ 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 ++ vary depending on the indexing strategy. ++ For data types that have a linear sort order, the indexed data ++ corresponds to the minimum and maximum values of the ++ 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 . +- ++ The BRIN operator classes included in the standard distribution are ++ documented in . ++ For more information see . ++ + + + +-- +2.27.0 + diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index 671299ff05..85d740b60a 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -120,246 +120,252 @@ CREATE INDEX test1_id_index ON test1 (id); algorithm that is best suited to different types of queries. By default, the CREATE INDEX command creates B-tree indexes, which fit the most common situations. + The other index types are established by the keyword + USING followed by the type name, e.g., + for a Hash index: + +CREATE INDEX name ON table USING HASH (column); + - - - index - 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: + + B-tree - - < - <= - = - >= - > - + + + index + 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 - a B-tree index search. Also, an IS NULL or IS NOT - NULL condition on an index column can be used with a B-tree index. - + +<   <=   =   >=   > + - - The optimizer can also use a B-tree index for queries involving the - pattern matching operators LIKE and ~ - if the pattern is a constant and is anchored to - the beginning of the string — for example, col LIKE - 'foo%' or col ~ '^foo', but not - col LIKE '%bar'. However, if your database does not - use the C locale you will need to create the index with a special - operator class to support indexing of pattern-matching queries; see - below. It is also possible to use - B-tree indexes for ILIKE and - ~*, but only if the pattern starts with - non-alphabetic characters, i.e., characters that are not affected by - upper/lower case conversion. - + Constructs equivalent to combinations of these operators, such as + BETWEEN and IN, can also be implemented with + a B-tree index search. Also, an IS NULL or IS NOT + NULL condition on an index column can be used with a B-tree index. + - - B-tree indexes can also be used to retrieve data in sorted order. - This is not always faster than a simple scan and sort, but it is - often helpful. - + + The optimizer can also use a B-tree index for queries involving the + pattern matching operators LIKE and ~ + if the pattern is a constant and is anchored to + the beginning of the string — for example, col LIKE + 'foo%' or col ~ '^foo', but not + col LIKE '%bar'. However, if your database does not + use the C locale you will need to create the index with a special + operator class to support indexing of pattern-matching queries; see + below. It is also possible to use + B-tree indexes for ILIKE and + ~*, but only if the pattern starts with + non-alphabetic characters, i.e., characters that are not affected by + upper/lower case conversion. + + + + B-tree indexes can also be used to retrieve data in sorted order. + This is not always faster than a simple scan and sort, but it is + often helpful. + + + + + Hash + + + + index + hash + + + hash + index + + Hash indexes store a 32-bit hash code derived from the + value of the involved 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: - - - index - hash - - - 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); += - - - - index - GiST - - - 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 - used vary depending on the indexing strategy (the operator - class). As an example, the standard distribution of - PostgreSQL includes GiST operator classes - for several two-dimensional geometric data types, which support indexed - queries using these operators: - - - << - &< - &> - >> - <<| - &<| - |&> - |>> - @> - <@ - ~= - && - - - (See for the meaning of - these operators.) - The GiST operator classes included in the standard distribution are - documented in . - Many other GiST operator - classes are available in the contrib collection or as separate - projects. For more information see . - - - - GiST indexes are also capable of optimizing nearest-neighbor - searches, such as + + + + + GiST + + + + index + GiST + + + 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 + used vary depending on the indexing strategy (the operator + class). As an example, the standard distribution of + PostgreSQL includes GiST operator classes + for several two-dimensional geometric data types, which support indexed + queries using these operators: + + +<<   &<   &>   >>   <<|   &<|   |&>   |>>   @>   <@   ~=   && + + + (See for the meaning of + these operators.) + The GiST operator classes included in the standard distribution are + documented in . + Many other GiST operator + classes are available in the contrib collection or as separate + projects. For more information see . + + + + GiST indexes are also capable of optimizing nearest-neighbor + searches, such as point '(101,456)' LIMIT 10; ]]> - which finds the ten places closest to a given target point. The ability - to do this is again dependent on the particular operator class being used. - In , operators that can be - used in this way are listed in the column Ordering Operators. - + which finds the ten places closest to a given target point. The ability + to do this is again dependent on the particular operator class being used. + In , operators that can be + used in this way are listed in the column Ordering Operators. + + - - - index - SP-GiST - - - 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, - k-d trees, and radix trees (tries). As an example, the standard distribution of - PostgreSQL includes SP-GiST operator classes - for two-dimensional points, which support indexed - queries using these operators: + + SP-GiST - - << - >> - ~= - <@ - <^ - >^ - + + + index + SP-GiST + + + 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, + k-d trees, and radix trees (tries). As an example, the standard distribution of + PostgreSQL includes SP-GiST operator classes + for two-dimensional points, which support indexed + queries using these operators: - (See for the meaning of - these operators.) - The SP-GiST operator classes included in the standard distribution are - documented in . - For more information see . - + +<<   >>   ~=   <@   <^   >^ + - - 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 - column in . - + (See for the meaning of + these operators.) + The SP-GiST operator classes included in the standard distribution are + documented in . + For more information see . + - - - index - GIN - - - 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 - can efficiently handle queries that test for the presence of specific - component values. - + + 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 + column in . + + - - Like GiST and SP-GiST, GIN can support - many different user-defined indexing strategies, and the particular - operators with which a GIN index can be used vary depending on the - indexing strategy. - As an example, the standard distribution of - PostgreSQL includes a GIN operator class - for arrays, which supports indexed queries using these operators: + + GIN - - <@ - @> - = - && - + + + index + GIN + + + 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 + can efficiently handle queries that test for the presence of specific + component values. + - (See for the meaning of - these operators.) - The GIN operator classes included in the standard distribution are - documented in . - Many other GIN operator - classes are available in the contrib collection or as separate - projects. For more information see . - + + Like GiST and SP-GiST, GIN can support + many different user-defined indexing strategies, and the particular + operators with which a GIN index can be used vary depending on the + indexing strategy. + As an example, the standard distribution of + PostgreSQL includes a GIN operator class + for arrays, which supports indexed queries using these operators: - - - index - BRIN - - - BRIN - index - - BRIN indexes (a shorthand for Block Range INdexes) store summaries about - the values stored in consecutive physical block ranges of a table. - 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 - vary depending on the indexing strategy. - For data types that have a linear sort order, the indexed data - corresponds to the minimum and maximum values of the - 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 . - + +<@   @>   =   && + + + (See for the meaning of + these operators.) + The GIN operator classes included in the standard distribution are + documented in . + Many other GIN operator + classes are available in the contrib collection or as separate + projects. For more information see . + + + + + BRIN + + + + index + BRIN + + + BRIN + index + + BRIN indexes (a shorthand for Block Range INdexes) store summaries about + the values stored in consecutive physical block ranges of a table. + 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 + vary depending on the indexing strategy. + For data types that have a linear sort order, the indexed data + corresponds to the minimum and maximum values of the + 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 . + +