From 9bd7ed828ebdc2a8e04acae3b9eaa66d255ebd97 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 21 Oct 2005 01:41:28 +0000 Subject: [PATCH] Clean up some obsolete statements about GiST indexes, and add a section documenting GiST crash recovery procedures, as requested some time ago by Teodor. (The GiST chapter doesn't seem quite the right place for the latter, but I'm not sure what else to do with it.) --- doc/src/sgml/gist.sgml | 60 +++++++++++++++++++++++++++++++++++++---------- doc/src/sgml/indices.sgml | 53 +++++++++++++++++++++++++---------------- doc/src/sgml/mvcc.sgml | 39 +++++++++++++++--------------- 3 files changed, 99 insertions(+), 53 deletions(-) diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml index ce6124579d..17b70fd564 100644 --- a/doc/src/sgml/gist.sgml +++ b/doc/src/sgml/gist.sgml @@ -1,11 +1,11 @@ GiST Indexes - + Introduction @@ -44,7 +44,7 @@ $PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.21 2005/07/02 20:08:27 momjian Exp - + Extensibility @@ -92,7 +92,7 @@ $PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.21 2005/07/02 20:08:27 momjian Exp - + Implementation @@ -180,19 +180,24 @@ $PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.21 2005/07/02 20:08:27 momjian Exp - + Examples - To see example implementations of index methods implemented using - GiST, examine the following contrib modules: + The PostgreSQL source distribution includes + several examples of index methods implemented using + GiST. The core system currently provides R-Tree + equivalent functionality for some of the built-in geometric datatypes + (see src/backend/access/gist/gistproc.c). The following + contrib modules also contain GiST + operator classes: btree_gist - B-Tree + B-Tree equivalent functionality for several datatypes @@ -213,26 +218,26 @@ $PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.21 2005/07/02 20:08:27 momjian Exp ltree - Indexing for tree-like stuctures + Indexing for tree-like structures - rtree_gist + pg_trgm - R-Tree + Text similarity using trigram matching seg - Storage and indexed access for float ranges + Indexing for float ranges - tsearch and tsearch2 + tsearch2 Full text indexing @@ -241,4 +246,33 @@ $PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.21 2005/07/02 20:08:27 momjian Exp + + Crash Recovery + + + Usually, replay of the WAL log is sufficient to restore the integrity + of a GiST index following a database crash. However, there are some + corner cases in which the index state is not fully rebuilt. The index + will still be functionally correct, but there may be some performance + degradation. When this occurs, the index can be repaired by + VACUUMing its table, or by rebuilding the index using + REINDEX. In some cases a plain VACUUM is + not sufficient, and either VACUUM FULL or REINDEX + is needed. The need for one of these procedures is indicated by occurrence + of this log message during crash recovery: + +LOG: index NNN/NNN/NNN needs VACUUM or REINDEX to finish crash recovery + + or this log message during routine index insertions: + +LOG: index "FOO" needs VACUUM or REINDEX to finish crash recovery + + If a plain VACUUM finds itself unable to complete recovery + fully, it will return a notice: + +NOTICE: index "FOO" needs VACUUM FULL or REINDEX to finish crash recovery + + + + diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index a1c1c9735b..fc268389e8 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -1,4 +1,4 @@ - + Indexes @@ -206,14 +206,6 @@ CREATE INDEX name ON table CREATE INDEX name ON table USING hash (column); - - - Testing has shown PostgreSQL's hash - indexes to perform no better than B-tree indexes, and the - index size and build time for hash indexes is much worse. For - these reasons, hash index use is presently discouraged. - - @@ -226,15 +218,33 @@ CREATE INDEX name ON table equivalent to the R-tree operator classes, and many other GiST operator classes are available in the contrib collection or as separate projects. For more information see . - - - It is likely that the R-tree index type will be retired in a future - release, as GiST indexes appear to do everything R-trees can do with - similar or better performance. Users are encouraged to migrate - applications that use R-tree indexes to GiST indexes. - - + + + + Testing has shown PostgreSQL's hash + indexes to perform no better than B-tree indexes, and the + index size and build time for hash indexes is much worse. + Furthermore, hash index operations are not presently WAL-logged, + so hash indexes may need to be rebuilt with REINDEX + after a database crash. + For these reasons, hash index use is presently discouraged. + + + + Similarly, R-tree indexes do not seem to have any performance + advantages compared to the equivalent operations of GiST indexes. + Like hash indexes, they are not WAL-logged and may need + REINDEXing after a database crash. + + + + While the problems with hash indexes may be fixed eventually, + it is likely that the R-tree index type will be retired in a future + release. Users are encouraged to migrate applications that use R-tree + indexes to GiST indexes. + + @@ -300,9 +310,12 @@ CREATE INDEX test2_mm_idx ON test2 (major, minor); A multicolumn GiST index can only be used when there is a query condition - on its leading column. As with B-trees, conditions on additional columns - restrict the entries returned by the index, but do not in themselves aid - the index search. + on its leading column. Conditions on additional columns restrict the + entries returned by the index, but the condition on the first column is the + most important one for determining how much of the index needs to be + scanned. A GiST index will be relatively ineffective if its first column + has only a few distinct values, even if there are many distinct values in + additional columns. diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml index 97e351b323..ea01104d93 100644 --- a/doc/src/sgml/mvcc.sgml +++ b/doc/src/sgml/mvcc.sgml @@ -1,5 +1,5 @@ @@ -965,41 +965,41 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222; - B-tree indexes + B-tree and GiST indexes - Short-term share/exclusive page-level locks are used for - read/write access. Locks are released immediately after each - index row is fetched or inserted. B-tree indexes provide - the highest concurrency without deadlock conditions. + Short-term share/exclusive page-level locks are used for + read/write access. Locks are released immediately after each + index row is fetched or inserted. These index types provide + the highest concurrency without deadlock conditions. - GiST and R-tree indexes + Hash indexes - Share/exclusive index-level locks are used for read/write access. - Locks are released after the command is done. + Share/exclusive hash-bucket-level locks are used for read/write + access. Locks are released after the whole bucket is processed. + Bucket-level locks provide better concurrency than index-level + ones, but deadlock is possible since the locks are held longer + than one index operation. - Hash indexes + R-tree indexes - Share/exclusive hash-bucket-level locks are used for read/write - access. Locks are released after the whole bucket is processed. - Bucket-level locks provide better concurrency than index-level - ones, but deadlock is possible since the locks are held longer - than one index operation. + Share/exclusive index-level locks are used for read/write access. + Locks are released after the entire command is done. @@ -1007,14 +1007,13 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222; - In short, B-tree indexes offer the best performance for concurrent + Currently, B-tree indexes offer the best performance for concurrent applications; since they also have more features than hash indexes, they are the recommended index type for concurrent applications that need to index scalar data. When dealing with - non-scalar data, B-trees obviously cannot be used; in that - situation, application developers should be aware of the - relatively poor concurrent performance of GiST and R-tree - indexes. + non-scalar data, B-trees are not useful, and GiST indexes should + be used instead. R-tree indexes are deprecated and are likely + to disappear entirely in a future release. -- 2.11.0