55.2. Функции для метода доступа индекса

Метод доступа индекса должен реализовывать следующие функции построения и обслуживания индексов:

IndexBuildResult *
ambuild (Relation heapRelation,
         Relation indexRelation,
         IndexInfo *indexInfo);

Строит новый индекс. Отношение индекса уже физически создано, но пока пусто. Оно должно быть наполнено фиксированными данными, которые требуются методу доступа, и записями для всех кортежей, уже существующих в таблице. Обычно функция ambuild вызывает IndexBuildHeapScan() для поиска в таблице существующих кортежей и для вычисления ключей, которые должны вставляться в этот индекс. Эта функция должна возвращать структуру, выделенную вызовом palloc и содержащую статистику нового индекса.

void
ambuildempty (Relation indexRelation);

Создаёт пустой индекс и записывает его в слой инициализации (INIT_FORKNUM) данного отношения. Этот метод вызывается только для нежурналируемых таблиц; пустой индекс, записанный в слой инициализации, будет копироваться в основной слой отношения при каждом перезапуске сервера.

bool
aminsert (Relation indexRelation,
          Datum *values,
          bool *isnull,
          ItemPointer heap_tid,
          Relation heapRelation,
          IndexUniqueCheck checkUnique);

Вставляет новый кортеж в существующий индекс. В массивах values и isnull передаются значения ключа, которые должны быть проиндексированы, а в heap_tid — идентификатор (TID) индексируемого кортежа. Если метод доступ поддерживает уникальные индексы (его флаг pg_am.amcanunique установлен), параметр checkUnique указывает, какая проверка уникальности должна выполняться. Это зависит от того, является ли ограничение уникальности откладываемым; за подробностями обратитесь к Разделу 55.5. Обычно параметр heapRelation нужен методу доступа только для проверки уникальности (так как он должен обратиться к основным данным, чтобы убедиться в актуальности кортежа).

Возвращаемый функцией булевский результат имеет значение, только когда параметр checkUnique равен UNIQUE_CHECK_PARTIAL. В этом случае результат TRUE означает, что новая запись признана уникальной, тогда как FALSE означает, что она может быть неуникальной (и требуется назначить отложенную проверку уникальности). В других случаях рекомендуется возвращать постоянный результат FALSE.

Некоторые индексы могут индексировать не все кортежи. Если кортеж не будет индексирован, aminsert должна просто завершиться, не делая ничего.

IndexBulkDeleteResult *
ambulkdelete (IndexVacuumInfo *info,
              IndexBulkDeleteResult *stats,
              IndexBulkDeleteCallback callback,
              void *callback_state);

Удаляет кортеж(и) из индекса. Это операция "массового удаления", которая предположительно будет реализована путём сканирования всего индекса и проверки для каждой записи, должна ли она удаляться. Переданная функция callback должна вызываться в стиле callback(TID, callback_state) с результатом bool, который говорит, должна ли удаляться запись индекса, на которую указывает передаваемый TID. Возвращать эта функция должна NULL или структуру, выделенную вызовом palloc и содержащую статистику результата удаления. NULL можно вернуть, если никакая информация не должна передаваться в amvacuumcleanup.

Из-за ограничения maintenance_work_mem процедура ambulkdelete может вызываться несколько раз, когда удалению подлежит большое количество кортежей. В аргументе stats передаётся результат предыдущего вызова для данного индекса (при первом вызове в ходе операции VACUUM он содержит NULL). Это позволяет методу доступа накапливать статистику в процессе всей операции. Обычно ambulkdelete модифицирует и возвращает одну и ту же структуру, если в stats передаётся не NULL.

IndexBulkDeleteResult *
amvacuumcleanup (IndexVacuumInfo *info,
                 IndexBulkDeleteResult *stats);

Провести очистку после операции VACUUM (до этого ambulkdelete могла вызываться несколько или ноль раз). От этой функции не требуется ничего, кроме как выдать статистику по индексу, но она может произвести массовую очистку, например, высвободить пустые страницы индекса. В stats ей передаётся структура, возвращённая при последнем вызове ambulkdelete, либо NULL, если ambulkdelete не вызывалась, так как никакие кортежи удалять не требовалось. Эта функция должна возвращать NULL или структуру, выделенную вызовом palloc. Содержащаяся в этой структуре статистика будет отражена в записи в pg_class и попадёт в вывод команды VACUUM, если она выполнялась с указанием VERBOSE. NULL может возвращаться, если индекс вовсе не изменился в процессе операции VACUUM, но в противном случае должна возвращаться корректная статистика.

Начиная с PostgreSQL версии 8.4, amvacuumcleanup также вызывается в конце операции ANALYZE. В этом случае stats всегда NULL и любое возвращаемое значение игнорируется. Этот вариант вызова можно распознать, проверив поле info->analyze_only. При таком вызове методу доступа рекомендуется ничего не делать, кроме как провести очистку после добавления данных, и только в рабочем процессе автоочистки.

bool
amcanreturn (Relation indexRelation);

Проверяет, поддерживается ли сканирование только индекса, когда для записи индекса возвращаются значения индексируемых колонок в виде IndexTuple. Должна вернуть TRUE, если такое сканирование поддерживается, и FALSE в противном случае. Если метод доступа индекса принципиально не поддерживает сканирование только индекса (как например, индексы по хешу, в которых хранятся только хешированные значения, а не исходные данные), достаточно обнулить флаг amcanreturn в pg_am.

void
amcostestimate (PlannerInfo *root,
                IndexPath *path,
                double loop_count,
                Cost *indexStartupCost,
                Cost *indexTotalCost,
                Selectivity *indexSelectivity,
                double *indexCorrelation);

Рассчитывает примерную стоимость сканирования индекса. Эта функция полностью описывается ниже в Разделе 55.6.

bytea *
amoptions (ArrayType *reloptions,
           bool validate);

Разбирает и проверяет массив параметров для индекса. Эта функция вызывается, только когда для индекса задан отличный от NULL массив reloptions. Массив reloptions состоит из элементов типа text, содержащих записи вида имя=значение. Данная функция должна получить значение типа bytea, которое будет скопировано в поле rd_options записи индекса в relcache. Содержимое этого значения bytea определяется самим методом доступа; большинство стандартных методов доступа помещают в него структуру StdRdOptions. Когда параметр validate равен true, эта функция должна выдать подходящее сообщение об ошибке, если какие-либо параметры нераспознаны или имеют недопустимые значения; если же validate равен false, некорректные записи должны просто игнорироваться. (В validate передаётся false, когда параметры уже загружены в pg_catalog; при этом неверная запись может быть обнаружена, только если в методе доступа поменялись правила обработки параметров, и в этом случае стоит просто игнорировать такие записи.) NULL можно вернуть, когда нужно получить поведение по умолчанию.

Цель индекса, конечно, в том, чтобы поддерживать поиск кортежей, соответствующих индексируемому условию WHERE, по ограничению или ключу поиска. Сканирование индекса описывается более полно ниже, в Разделе 55.3. Метод доступа индекса может поддерживать "простое" сканирование, сканирование по "битовой карте" или и то, и другое. Метод доступа должен или может реализовывать следующие функции, связанные со сканированием:

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. На практике возможность перезапуска используется, когда в соединении со вложенным циклом выбирается новый внешний кортеж, так что требуется сравнение с новым ключом, но структура ключей сканирования не меняется.

boolean
amgettuple (IndexScanDesc scan,
            ScanDirection direction);

Выбирает следующий кортеж в ходе данного сканирования, с передвижением по индексу в заданном направлении (вперёд или назад). Возвращает TRUE, если кортеж был получен, или FALSE, если подходящих кортежей не осталось. В случае успеха в структуре scan сохраняется TID кортежа. Заметьте, что под "успехом" здесь подразумевается только, что индекс содержит запись, соответствующую ключам сканирования, а не то, что данный кортеж обязательно существует в данных или оказывается видимым в снимке вызывающего субъекта. При положительном результате amgettuple должна также установить для свойства scan->xs_recheck значение TRUE или FALSE. FALSE будет означать, что запись индекса точно соответствует ключам сканирования, а TRUE, что есть сомнение в этом, так что условия, представленные ключами сканирования, необходимо ещё раз перепроверить для фактического кортежа, когда он будет получен. Это свойство введено для поддержки "неточных" операторов индексов. Заметьте, что такая перепроверка касается только условий сканирования; предикат частичного индекса (если он имеется) никогда не перепроверяется кодом, вызывающим amgettuple.

Если индекс поддерживает сканирование только индекса (то есть, amcanreturn выдаёт для него TRUE), то в случае успеха метод доступа должен также проверить флаг scan->xs_want_itup и, если он установлен, должен вернуть исходные индексированные данные для этой записи индекса, в виде указателя на IndexTuple, сохранённого в scan->xs_itup, и дескриптор кортежа scan->xs_itupdesc. (Контролировать структуру данных, на которую указывает этот указатель, должен сам метод доступа. Она должна сохраняться в рабочем состоянии как минимум до следующего вызова amgettuple, amrescan или amendscan в процессе текущего сканирования.)

Функция amgettuple должна реализовываться, только если метод доступа поддерживает "простое" сканирование индекса. В противном случае поле amgettuple в соответствующей строке pg_am должно содержать ноль.

int64
amgetbitmap (IndexScanDesc scan,
             TIDBitmap *tbm);

Выбирает все кортежи для данного сканирования и добавляет их в передаваемую вызывающим кодом структуру TIDBitmap (то есть, получает логическое объединение множества TID выбранных кортежей с множеством, уже записанным в битовой карте). Возвращает эта функция число полученных кортежей (это может быть только приблизительная оценка; например, некоторые методы доступа не учитывают повторяющиеся значения). Добавляя идентификаторы кортежей в битовую карту, amgetbitmap может обозначить, что для этих кортежей нужно перепроверить условия сканирования. Для этого так же, как и в amgettuple, устанавливается выходной параметр xs_recheck. Замечание: в текущей реализации эта возможность увязывается с возможностью неточного хранения самих битовых карт, таким образом вызывающий код перепроверяет для отмеченных кортежей и условия сканирования, и предикат частичного индекса (если он имеется). Однако так может быть не всегда. Функции amgetbitmap и amgettuple не могут использоваться в одном сканировании индекса; есть и другие ограничения в применении amgetbitmap, описанные в Разделе 55.3.

Функция amgetbitmap должна реализовываться, только если метод доступа поддерживает сканирование индекса "по битовой карте". В противном случае поле amgetbitmap в соответствующей строке pg_am должно содержать ноль.

void
amendscan (IndexScanDesc scan);

Завершает сканирование и освобождает ресурсы. Саму структуру scan освобождать не следует, но любые блокировки или закрепления объектов, установленные внутри метода доступа, должны быть сняты.

void
ammarkpos (IndexScanDesc scan);

Помечает текущую позицию сканирования. Метод доступа должен поддерживать сохранение только одной позиции в процессе сканирования.

void
amrestrpos (IndexScanDesc scan);

Восстанавливает позицию сканирования, отмеченную последней.

По соглашению запись в pg_proc для реализующей функции метода доступа должна описывать корректное число аргументов, но все они должны быть объявлены с типом internal (так как типы большинства аргументов неизвестны SQL, и нам всё равно не нужно, чтобы пользователи вызывали эти функции). В качестве возвращаемого типа выбирается void, internal или boolean, в соответствии с реальным типом. Единственным исключением является функция amoptions, которая должна корректно объявляться как принимающая параметры text[] и bool и возвращающая bytea. Благодаря этому, клиентский код сможет вызывать amoptions, чтобы проверить правильность параметров.