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,26 +965,14 @@ 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. - - - - - - - GiST and R-tree indexes - - - - Share/exclusive index-level locks are used for read/write access. - Locks are released after the command is done. + 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. @@ -995,11 +983,23 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222; - 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 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. + + + + + + + R-tree indexes + + + + 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.