# 54.2\. 索引訪問方法函數 索引訪問方法必須提供的索引構造和維護函數有： ``` IndexBuildResult * ambuild (Relation heapRelation, Relation indexRelation, IndexInfo *indexInfo); ``` 創建一個新索引。索引關系已經物理上創建好了，但是是空的。 必須用索引訪問方法要求的固定數據和代表所有已經在表里的行的數據項填充它。 通常，`ambuild`函數會調用`IndexBuildHeapScan()`掃描該表以獲取現有行并計算需要插入索引的鍵字。 ``` void ambuildempty (Relation indexRelation); ``` 創建一個空的索引，并寫到給定關系的初始fork(INIT_FORKNUM)中。 這個方法只會為unlogged表調用;在服務器重啟動時寫入到初始fork的空索引會被復制到主關系。 ``` bool aminsert (Relation indexRelation, Datum *values, bool *isnull, ItemPointer heap_tid, Relation heapRelation, IndexUniqueCheck checkUnique); ``` 向現有索引插入一個新行。 `values`和`isnull`數組給出需要制作索引的鍵字值，而`heap_tid`是要被索引的 TID 。 如果該訪問方法支持唯一索引(它的`pg_am`.`amcanunique`標志是真)， 那么`checkUnique`指示需要執行這種唯一性檢查。 具體情況依賴于該唯一制約是否是可延期的（deferrable）而不同; 詳細請參閱 [Section 54.5](#calibre_link-1170)。 通常訪問方法只有在執行唯一性檢查時才需要`heapRelation`參數(它將深入到heap中確認行是否是活的)。 只有當`checkUnique`是`UNIQUE_CHECK_PARTIAL`時，該函數的返回值才有意義。 TRUE的返回值意味著新的索引項是唯一的，FALSE意味著不唯一（并且延期的唯一性檢查必須被調度）。 其它情況下推薦返回常量FALSE。 一些索引可能并不索引所有的行。如果行不被索引，`aminsert`應該不做任何事情就直接返回。 ``` IndexBulkDeleteResult * ambulkdelete (IndexVacuumInfo *info, IndexBulkDeleteResult *stats, IndexBulkDeleteCallback callback, void *callback_state); ``` 從索引中刪除行。 這是一個"批量刪除"的操作，通常都是通過掃描整個索引，檢查每條記錄，看看它是否需要被刪除來實現的。 可以調用傳遞進來的`callback`函數，調用風格是： `callback(``_TID_`, callback_state) returns bool， 其作用是判斷某個用其引用的 TID 標識的索引項是否需要刪除。 必須返回 NULL 或者是一個 palloc 出來的，包含刪除操作執行影響的統計信息的結構。 如果不需要向`amvacuumcleanup`傳遞信息，返回 NULL 也是 OK 的。 由于`maintenance_work_mem`的限制，在刪除多行的時候 `ambulkdelete`可能需要被調用多次，`stats` 參數是先前在這個索引上的調用結果(在一個`VACUUM`操作內部第一次調用的話則是 NULL)。 這將允許 AM 在整個操作過程中積累統計信息。 典型的，如果傳遞的`stats`不是 null 的話，`ambulkdelete`將會修改并返回相同的結構。 ``` IndexBulkDeleteResult * amvacuumcleanup (IndexVacuumInfo *info, IndexBulkDeleteResult *stats); ``` 在一個`VACUUM`操作(一個或多個`ambulkdelete`調用)之后清理。 雖然不必做任何返回索引狀態之外的任何其他事情，但是它通常用于批量清理，比如說回收空的索引頁面。 `stats`是最后的`ambulkdelete`調用返回的東西或者 NULL(如果因為沒有行需要刪除而未調用`ambulkdelete`的話)。 如果結果不是 NULL ，那么它必須是一個 palloc 出來的結構。 它包含的統計信息將用于更新`pg_class`并且由`VACUUM`報告(如果給出了`VERBOSE`)。 如果索引在`VACUUM`操作的過程中根本沒有改變，那么返回 NULL 也是 OK 的，否則必須返回當前狀態。 在PostgreSQL8.4中，`amvacuumcleanup`也會在`ANALYZE`完成時被調用。 這時，`stats`總是為NULL，并且返回值會被忽略。 通過檢查`info->analyze_only`可以區分出這種情況。 建議訪問方法在這樣的調用里除了插入后的清理不要做其他事情，并且這只在autovacuum工作進程中。 ``` bool amcanreturn (Relation indexRelation); ``` 檢查索引是否支持_index-only掃描_，通過為一個索引項以IndexTuple的形式返回被索引的列值。 如果支持返回TRUE，否則返回FALSE。 如果索引AM永遠不支持index-only掃描（比如hash，它只存儲哈希值而不是原始數據）， 可以有充分的理由把`pg_am`中的`amcanreturn`字段設置為零。 ``` void amcostestimate (PlannerInfo *root, IndexPath *path, double loop_count, Cost *indexStartupCost, Cost *indexTotalCost, Selectivity *indexSelectivity, double *indexCorrelation); ``` 估算一個索引掃描的開銷。該函數在下面的[Section 54.6](#calibre_link-1171)中有詳細的討論。 ``` bytea * amoptions (ArrayType *reloptions, bool validate); ``` 為一個索引分析和驗證 reloptions 數組，僅當一個索引存在非空 reloptions 數組時才會被調用。 `reloptions`是一個`text`數組，包含`_name_``=``_value_`格式的項。 該函數應當創建一個`bytea`值，該值將被拷貝進索引的 relcache 項的`rd_options`字段。 `bytea`值的數據內容可以由訪問方法定義，不過目前所有的標準訪問方法都使用`StdRdOptions`結構。 當`validate`為真時，如果任何一個選項不可識別或者含有非法值，該函數都應當報告一個適當的錯誤信息；當`validate`為假時，非法項應該被悄悄的忽略。 （當載入已經存儲在`pg_catalog`中的選項時，`validate`為假，僅在訪問方法已經改變了選項規則的時候才可能找到非法項，在此情況下可以忽略廢棄的項。） 如果默認行為正是想要的，那么返回 NULL 也 OK 。 索引的目的當然是支持那些包含一個可以索引的`WHERE`條件的行的掃描，這個條件通常叫_修飾詞_或_掃描鍵字_。 索引掃描的語義在下面的[Section 54.3](#calibre_link-1142)里面有更完整的描述。 一個索引訪問方法可以支持"plain"索引掃描，"bitmap"索引掃描，或者兩者都支持。 必須或可以提供的與掃描有關的函數有： ``` IndexScanDesc ambeginscan (Relation indexRelation, int nkeys, int norderbys); ``` 準備一個索引掃描。 `nkeys`和`norderbys`參素指示掃描中使用的修飾詞和排序操作符的個數；它們可能對空間分配有用。 注意實際的掃描鍵還沒有提供。 結果必須是一個 palloc 出來的結構。 由于實現的原因，索引訪問方法_必須_通過調用`RelationGetIndexScan()`來創建這個結構。 在大多數情況下，`ambeginscan`本身除了調用上面這個函數和可能獲取一些鎖之外幾乎不干別的事情；索引掃描啟動時的有趣部分在`amrescan`里。 ``` void amrescan (IndexScanDesc scan, ScanKey keys, int nkeys, ScanKey orderbys, int norderbys); ``` 啟動或重新啟動一個索引掃描，可能會使用新的掃描鍵字。 （要使用先前提供的鍵重啟動，給`keys` 和/或者`orderbys`傳入NULL） 記住掃描鍵字或排序操作符的個數不予許大于傳給 `ambeginscan`的數值。 實際上，重新啟動特性用于這樣的場景：當一個新的外元組被嵌套循環(nested-loop)連接選中時，需要一個新的鍵比較值，但是掃描鍵結構仍然是相同的。 ``` boolean amgettuple (IndexScanDesc scan, ScanDirection direction); ``` 在給出的掃描里抓取下一個行，向給出的方向移動(在索引里向前或者向后)。 如果抓取到了行，則返回 TRUE ，如果沒有抓到匹配的行，返回 FALSE 。 在為 TRUE 的時候，該行的 TID 存儲在`scan`結構里。 請注意"成功"只是意味著索引包含一個匹配掃描鍵字的條目，并不是說該行仍然在堆中存在，或者是能夠通過調用者的快照檢查(譯注：MVCC 快照，用于判斷事務邊界內的行可視性)。 如果成功，`amgettuple`必須設置`scan->xs_recheck`為TRUE或FALSE。 FALSE意味著已經可以確定索引項匹配掃描鍵字。 TRUE意味著尚不確定，在取到堆元組后必須對堆元組再次檢查代表這個掃描鍵值的條件。 如果索引支持index-only掃描（比如，`amcanreturn`為它返回TRUE）， 那么成功執行后，這個AM也必須檢查`scan->xs_want_itup`，如果為TRUE, 它必須通過存儲在`scan->xs_itup`中的`IndexTuple`指針以及元組描述符`scan->xs_itupdesc`為這個索引項返回原始的被索引數據。 （訪問方法需要負責維護被這個指針引用的數據。至少在該掃描下一次調用`amgettuple`，`amrescan`或`amendscan`前，這個數據必須保持完好） 如果訪問方法支持"plain"索引掃描，只需要提供`amgettuple`函數。 如果不是，在它的`pg_am`行中的`amgettuple`字段必須被設置成零。 ``` int64 amgetbitmap (IndexScanDesc scan, TIDBitmap *tbm); ``` 在指定的掃描中抓取所有元組并把它們加入到調用者提供的`TIDBitmap`中（換句話說，元組的ID集合加入到某個已存在的bitmap）。 函數返回抓取到的元組數（這可能只是一個近似計數，某些AM實例并不檢測重復）。 當插入元組的TID到bitmap,`amgetbitmap`可以指示對特定的元組TID需要對掃描條件做再檢查。 這和`amgettuple`函數的輸出參數`xs_recheck`類似。 注意：在當前實現中，支持這個特性涉及到支持bitmap自身的有損存儲，因此調用者為可再檢查的元組再次檢查掃描條件和部分索引謂詞（如果有的話）。 然而，這可能不會總是正確的。 `amgetbitmap`和`amgettuple`不能在同一個索引掃描中使用；在使用 `amgetbitmap`的時候還有其它限制，在[Section 54.3](#calibre_link-1142)里給出解釋。 只有訪問方法支持"bitmap"索引掃描時才需要提供`amgetbitmap`函數。 如果訪問方法不支持的話，必須在它的`pg_am`行里設置`amgetbitmap`字段為零。 ``` void amendscan (IndexScanDesc scan); ``` 結束掃描并釋放資源。不應該釋放`scan`本身，但訪問方法內部使用的任何鎖或者銷(pin)都應該釋放。 ``` void ammarkpos (IndexScanDesc scan); ``` 標記當前掃描位置。訪問方法只需要支持每次掃描里面有一個被記住的掃描位置。 ``` void amrestrpos (IndexScanDesc scan); ``` 把掃描恢復到最近標記的位置。 通常，任何索引訪問方法函數的`pg_proc`記錄都應該顯示正確數目的參數， 只是把類型都聲明為類型`internal`(因為大多數參數的類型都是 SQL 不識別的類型，并且不希望用戶直接調用該函數)。 返回類型根據具體情況聲明為`void`, `internal`, or `boolean`。 唯一的例外是 `amoptions`，它應當被聲明為接受`text[]`和`bool`并返回`bytea`。 這樣就允許客戶端代碼執行`amoptions`以確認選項設置的有效性。