57.2. 擴展性 · PostgreSQL 中文文檔 9.3

# 57.2\. 擴展性 GIN接口有一個高層次的抽象，僅要求實現被訪問數據類型的語義即可。 GIN層自身可以處理并發操作、記錄日志、搜索樹結構。定義一個GIN訪問方法所要做的所有事情就是實現四個(或五個)用戶定義的方法，這些方法定義了鍵在樹中的行為、鍵與鍵之間的關系、被索引的項目、能夠使用索引的查詢。簡而言之，GIN將擴展性與普遍性、代碼重用、清晰的接口結合在了一起。一個GIN索引操作符類必須實現的四個方法如下： `int compare(Datum a, Datum b)` 比較兩個鍵(不是被索引的項目!)然后返回一個小于、等于或大于零的值，分別表示第一個鍵小于、等于或大于第二個鍵。 NULL的鍵永遠不會被傳入這個函數。 `Datum *extractValue(Datum itemValue, int32 *nkeys, bool **nullFlags)` 給定一個被索引的項目，返回一個對應的由palloc分配的鍵的數組。返回的鍵的數目必須存儲在`*nkeys`中。如果任何鍵可能為NULL，還要palloc一個包含`*nkeys`個`bool`元素的數組，將地址存儲到`*nullFlags`，并且根據需要設置NULL值。如果所有鍵都是非NULL的，可以讓`*nullFlags`保持為`NULL`（它的初始值）。如果輸入的項目不包含任何鍵，返回值可以為`NULL`。 `Datum *extractQuery(Datum query, int32 *nkeys, StrategyNumber n, bool **pmatch, Pointer **extra_data, bool **nullFlags, int32 *searchMode)` 給定一個被查詢的值，返回一個對應的palloc分配的鍵數組。也就是說，`query`是可索引操作符右側的值，而該操作符左側是被索引的字段。 `n`是操作符類中的操作符策略號(參見[Section 35.14.2](#calibre_link-940))。通常，`extractQuery`需要考量`n`來決定`query`的數據類型以及提取鍵值的方法。返回的數組的元素個數必須存放在`*nkeys`中。如果任何鍵可能為NULL，還要palloc一個包含`*nkeys`個`bool`元素的數組，將地址存儲到`*nullFlags`，并且根據需要設置NULL值。如果所有鍵都是非NULL的，可以讓`*nullFlags`保持為`NULL`（它的初始值）。如果`query`不包含任何鍵，返回值可以為`NULL`。 `searchMode`是一個輸出參數，它允許`extractQuery`指定一些關于如何執行搜索的細節。如果`*searchMode`被設置成`GIN_SEARCH_MODE_DEFAULT`(這也是調用函數前它被初始化的值)，只有匹配至少一個返回的鍵才能被認為是候選的匹配。如果`*searchMode`被設置成`GIN_SEARCH_MODE_INCLUDE_EMPTY`，除了包含至少一個匹配的鍵的項目，根本不包含任何鍵的項目也被視為候選的匹配。（這個模式對于實現像“是否是子集”這樣的操作是有用的）如果`*searchMode`被設置成`GIN_SEARCH_MODE_ALL`，索引中所有非NULL的項目都被認為是候選的匹配，不管它們是否匹配返回的鍵中的任何一個。（這個模式比起其它兩個要慢很多，因為它必須要掃描整個索引，但這對正確的實現邊界條件可能是必要的。一個需要這種模式的操作符在大多數時候很可能不是一個好的GIN操作符類的候選。）用于設置這個模式的符號定義在`access/gin.h`中。 `pmatch`是在部分匹配時需要用到的一個輸出參數。如果使用它，`extractQuery`必須分配一個有`*nkeys`個布爾值的數組，并把數組地址保存到`*pmatch`。數組的每個元素應該被設置為：TRUE，如果相應的鍵需要部分匹配；或者FALSE，如果不是。如果`*pmatch`被設置為`NULL`，GIN假設不需要部分匹配。在函數調用前這個值被初始化成了`NULL`，因此，對于不支持部分匹配的操作符類，可以簡單的忽略這個參數。 `extra_data`是一個允許`extractQuery`傳遞額外數據給`consistent` 和`comparePartial`的輸出參數。如果使用它，`extractQuery`必須分配一個包含`*nkeys`個Pointer元素的數組，并把數組地址保存到`*extra_data`，然后把它想附加的東西存儲到各個獨立的指針中。在函數調用前這個值被初始化成了`NULL`，因此，對于不需要附加數據的操作符類，可以簡單的忽略這個參數。如果`*extra_data`被設置了，那么整個數組會被傳給`consistent`方法，適當的元素會被傳給`comparePartial`方法。 `bool consistent(bool check[], StrategyNumber n, Datum query, int32 nkeys, Pointer extra_data[], bool *recheck, Datum queryKeys[], bool nullFlags[])` 如果被索引項目滿足策略號為`n`的查詢操作符（或可能滿足，如果recheck指示符被返回了的話）返回TRUE。這個函數并不直接訪問被索引項目的值，因為GIN并沒有精確的把項目保存下來，但是需要知道哪些從查詢中提取的鍵值出現在給定的索引項目中。 `check`數組的長度是`nkeys`，這與先前針對這個`query`調用的`extractQuery`函數返回的鍵值的數目相同。如果被索引項目包含了相應的查詢鍵，`check`數組中對應的元素值就是TRUE。比如，如果(check[i] == TRUE)，那么意味著`extractQuery`的結果數組的第i個鍵出現在了索引項目中。考慮到`consistent`可能會用到，原始的`query`也被作為參數傳入進來。與此相同的還有`extractQuery`函數返回的`queryKeys[]`和`nullFlags[]`。 `extra_data`是`extractQuery`函數返回的額外數據數組，如果沒有的話就是`NULL`。當`extractQuery`在`queryKeys[]`中返回一個NULL的鍵值，如果被索引項目包含NULL鍵值，相應的`check[]`中的元素是TRUE。也就是說，`check[]`的語義很像`IS NOT DISTINCT FROM`。如果需要知道是通常值匹配還是NULL匹配，`consistent`函數可以檢查相應的`nullFlags[]`元素。成功執行后，如果對這個元組需要執行查詢操作符是否匹配的再檢查，`*recheck`需要被設置為TRUE，如果索引測試已經是精確的了，則設為FALSE。也就是說，FALSE的返回值確保堆元組不匹配這個查詢；伴隨`*recheck`為FASLE的TRUE的返回值確保堆元組匹配這個查詢；伴隨`*recheck`為TRUE的TRUE的返回值意味著堆元組可能匹配這個查詢，因此需要取得這個堆元組，并通過直接針對原始的被索引項目評估查詢操作符的方式進行再檢查。 GIN操作符類可以可選地提供第五個函數。 `int comparePartial(Datum partial_key, Datum key, StrategyNumber n, Pointer extra_data)` 比較一個部分匹配查詢鍵和一個索引鍵。返回一個整形值，它個符號代表了不同的含義：小于0意味著索引鍵不匹配查詢，但是索引掃描應該繼續； 0意味著索引鍵匹配查詢；大于0指示應該終止索引掃描，因為不可能再有更多的匹配。這里提供了生成部分一致查詢的操作符的策略號`n`，以防需要用它的語義去決定何時終止掃描。同樣的，`extra_data`是`extractQuery`生成的額外數據數組中的相應元素，或者為NULL，如果沒有的話。 NULL的鍵永遠不會被傳入這個函數。為了支持"部分匹配"查詢，一個操作符類必須提供`comparePartial`方法，并且當遇到部分匹配查詢時，它的`extractQuery`方法必須設置`pmatch`參數。詳細請參考[Section 57.3.2](#calibre_link-1557)。上面的各種`Datum`值的實際數據類型根據操作符類的不同而不同。傳入到`extractValue`中的項目值總是操作符類的輸入類型，所有的鍵值類型必須這個類的`STORAGE`類型。傳入到`extractQuery`和`consistent`的`query`參數的類型是由策略號識別的類成員操作符的右操作數的輸入類型。它不需要和項目類型相同，只要可以從中抽取出正確類型的鍵值。