56.3. Extensibility

Traditionally, implementing a new index access method meant a lot of difficult work. It was necessary to understand the inner workings of the database, such as the lock manager and Write-Ahead Log. TheGiST interface has a high level of abstraction, requiring the access method implementer only to implement the semantics of the data type being accessed. TheGiST layer itself takes care of concurrency, logging and searching the tree structure.

This extensibility should not be confused with the extensibility of the other standard search trees in terms of the data they can handle. For example,PostgreSQL supports extensible B-trees and hash indexes. That means that you can usePostgreSQL to build a B-tree or hash over any data type you want. But B-trees only support range predicates (<,=,>), and hash indexes only support equality queries.

So if you index, say, an image collection with aPostgreSQL B-tree, you can only issue queries such as"is imagex equal to imagey","is imagex less than imagey" and"is imagex greater than imagey". Depending on how you define"equals","less than" and"greater than" in this context, this could be useful. However, by using aGiST based index, you could create ways to ask domain-specific questions, perhaps"find all images of horses" or"find all over-exposed images".

All it takes to get aGiST access method up and running is to implement several user-defined methods, which define the behavior of keys in the tree. Of course these methods have to be pretty fancy to support fancy queries, but for all the standard queries (B-trees, R-trees, etc.) they're relatively straightforward. In short,GiST combines extensibility along with generality, code reuse, and a clean interface.

There are seven methods that an index operator class forGiST must provide, and an eighth that is optional. Correctness of the index is ensured by proper implementation of thesame,consistent andunion methods, while efficiency (size and speed) of the index will depend on thepenalty andpicksplit methods. The remaining two basic methods arecompress anddecompress, which allow an index to have internal tree data of a different type than the data it indexes. The leaves are to be of the indexed data type, while the other tree nodes can be of any C struct (but you still have to followPostgreSQL data type rules here, see aboutvarlena for variable sized data). If the tree's internal data type exists at the SQL level, theSTORAGE option of theCREATE OPERATOR CLASS command can be used. The optional eighth method isdistance, which is needed if the operator class wishes to support ordered scans (nearest-neighbor searches).

All the GiST support methods are normally called in short-lived memory contexts; that is,CurrentMemoryContext will get reset after each tuple is processed. It is therefore not very important to worry about pfree'ing everything you palloc. However, in some cases it's useful for a support method to cache data across repeated calls. To do that, allocate the longer-lived data infcinfo->flinfo->fn_mcxt, and keep a pointer to it infcinfo->flinfo->fn_extra. Such data will survive for the life of the index operation (e.g., a single GiST index scan, index build, or index tuple insertion). Be careful to pfree the previous value when replacing afn_extra value, or the leak will accumulate for the duration of the operation.