Возвращает массив ключей, выделенный с помощью palloc, для заданного элемента, который должен быть проиндексирован. Количество возвращенных ключей должно быть сохранено в переменной *nkeys. Если какие-либо ключи могут быть null, также выделяется массив полей *nkeys типа bool, адрес которого сохраняется в **nullFlags, и устанавливаются соответствующие флаги null. *nullFlags может быть оставлен NULL (его начальное значение), если все ключи не являются null. Возвращаемое значение может быть NULL, если элемент не содержит ключей.

Возвращает массив ключей, выделенный с помощью palloc, при заданном значении для запроса; то есть, query - это значение справа от индексируемого оператора, левая часть которого - индексируемый столбец. n - это номер стратегии оператора внутри класса операторов (см. Раздел 34.15.2). Часто extractQuery должна обратиться к n, чтобы определить тип данных query и метод, который следует использовать для извлечения ключевых значений. Количество возвращаемых ключей должно быть сохранено в *nkeys. Если какие-либо ключи могут быть null, также нужно выделить массив *nkeys полей bool, сохранить его адрес в *nullFlags и установить эти флаги null по мере необходимости. *nullFlags может быть оставлено NULL (его начальное значение), если все ключи не являются null. Возвращаемое значение может быть NULL, если query не содержит ключей.

searchMode - это выходной аргумент, который позволяет extractQuery указать детали о том, как будет выполняться поиск. Если *searchMode установлено в GIN_SEARCH_MODE_DEFAULT (что является его исходным значением перед вызовом), рассматриваются только элементы, которые соответствуют хотя бы одному из возвращенных ключей. Если *searchMode установлено в GIN_SEARCH_MODE_INCLUDE_EMPTY, то помимо элементов, содержащих хотя бы один совпадающий ключ, рассматриваются также элементы, не содержащие ключей вообще. (Этот режим полезен для реализации операторов подмножества, например). Если *searchMode установлено в GIN_SEARCH_MODE_ALL, то все ненулевые элементы в индексе рассматриваются как возможные совпадения, независимо от того, соответствуют ли они какому-либо из возвращенных ключей или нет. (Этот режим гораздо медленнее других двух выборов, так как требует практически полного сканирования индекса, но может быть необходим для правильной реализации крайних случаев. Оператор, который в большинстве случаев требует этот режим, вероятно, не является хорошим кандидатом для класса операторов GIN). Символы для установки этого режима определены в access/gin.h.

pmatch - это выходной аргумент, используемый при поддержке частичного совпадения. Чтобы использовать его, extractQuery должна выделить массив из *nkeys элементов типа bool и сохранить его адрес в *pmatch. Каждый элемент массива должен быть установлен в true, если соответствующий ключ требует частичного совпадения, и в false, если нет. Если *pmatch установлено в NULL, то GIN предполагает, что частичное совпадение не требуется. Переменная инициализируется значением NULL перед вызовом, поэтому этот аргумент можно просто игнорировать операторными классами, которые не поддерживают частичное совпадение.

extra_data - это выходной аргумент, который позволяет extractQuery передавать дополнительные данные в методы consistent и comparePartial. Чтобы использовать его, extractQuery должен выделить массив указателей размером *nkeys и сохранить его адрес в *extra_data, а затем сохранить в него любые данные. Переменная инициализируется значением NULL перед вызовом, поэтому этот аргумент можно просто игнорировать классами операторов, которым не требуются дополнительные данные. Если *extra_data установлено, весь массив передается в метод consistent, а соответствующий элемент - в метод comparePartial.

Возвращает true, если индексированный элемент удовлетворяет оператору запроса с номером стратегии n (или может удовлетворять его, если возвращается индикация повторной проверки). Эта функция не имеет прямого доступа к значению индексированного элемента, так как GIN не хранит элементы явно. Вместо этого доступна информация о том, какие ключевые значения, извлеченные из запроса, присутствуют в данном индексированном элементе. Массив check имеет длину nkeys, которая совпадает с количеством ключей, ранее возвращенных функцией extractQuery для этого элемента запроса query. Каждый элемент массива check равен true, если индексированный элемент содержит соответствующий ключ запроса, то есть если (check[i] == true), i-й ключ массива результатов extractQuery присутствует в индексированном элементе. Исходный элемент запроса передается в случае, если метод consistent должен обратиться к нему, а также массивы queryKeys[] и nullFlags[], ранее возвращенные функцией extractQuery. extra_data - это массив дополнительных данных, возвращенных функцией extractQuery, или NULL, если таковых нет.

Когда функция extractQuery возвращает пустой ключ в queryKeys[], соответствующий элемент check[] становится true, если индексированный элемент содержит пустой ключ; то есть семантика check[] аналогична IS NOT DISTINCT FROM. Функция consistent может проверить соответствующий элемент nullFlags[], если ей нужно различать обычное совпадение значений и совпадение с пустым значением.

При успешном выполнении, значение *recheck должно быть установлено в true, если кортеж кучи должен быть проверен снова с помощью оператора запроса, или в false, если индексный тест является точным. То есть, значение false гарантирует, что кортеж кучи не соответствует запросу; значение true с установленным значением *recheck в false гарантирует, что кортеж кучи соответствует запросу; и значение true с установленным значением *recheck в true означает, что кортеж кучи может соответствовать запросу, поэтому его необходимо получить и проверить, выполнив оператор запроса непосредственно против исходного индексированного элемента.

triConsistent похожа на consistent, но вместо логических значений в векторе check есть три возможных значения для каждого ключа: GIN_TRUE, GIN_FALSE и GIN_MAYBE. GIN_FALSE и GIN_TRUE имеют тот же смысл, что и обычные логические значения, в то время как GIN_MAYBE означает, что наличие этого ключа неизвестно. Когда присутствуют значения GIN_MAYBE, функция должна возвращать только GIN_TRUE, если элемент точно соответствует, независимо от того, содержит ли он соответствующие ключи запроса. Аналогично, функция должна возвращать GIN_FALSE только если элемент точно не соответствует, независимо от того, содержит ли он ключи GIN_MAYBE. Если результат зависит от записей GIN_MAYBE, то есть, соответствие нельзя подтвердить или опровергнуть на основе известных ключей запроса, функция должна возвращать GIN_MAYBE.

Когда в векторе проверки check нет значений GIN_MAYBE, возвращаемое значение GIN_MAYBE эквивалентно установке флага recheck в функции consistent типа Boolean.

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

Сравните частично совпадающий ключ запроса с индексным ключом. Возвращает целое число, знак которого указывает на результат: отрицательное значение означает, что индексный ключ не соответствует запросу, но индексное сканирование должно продолжаться; ноль означает, что индексный ключ соответствует запросу; положительное значение указывает, что индексное сканирование должно остановиться, потому что больше нет совпадений возможно. Номер стратегии n оператора, который сгенерировал запрос с частичным совпадением, предоставляется, на случай, если его семантика необходима для определения момента окончания сканирования. Кроме того, extra_data - это соответствующий элемент массива extra-data, созданный с помощью extractQuery, или NULL, если таковой отсутствует. В эту функцию никогда не передаются пустые ключи.

Определяет набор параметров, видимых пользователем, которые управляют поведением класса операторов.

Функция options получает указатель на структуру local_relopts, которую необходимо заполнить набором специфичных для класса операторов опций. Опции могут быть доступны из других вспомогательных функций с использованием макросов PG_HAS_OPCLASS_OPTIONS() и PG_GET_OPCLASS_OPTIONS().

Поскольку и извлечение ключа из индексированных значений, и представление ключа в GIN являются гибкими, они могут зависеть от параметров, указанных пользователем.

Вставка в индекс GIN может быть медленной из-за вероятности вставки множества ключей для каждого элемента. Поэтому, для массовых вставок в таблицу рекомендуется удалить индекс GIN и создать его заново после завершения массовой вставки.

Когда fastupdate включен для GIN (см. Раздел 62.4.4.1 для получения более подробной информации), штраф меньше, чем когда он отключен. Но для очень больших обновлений может быть лучше удалить и создать индекс заново.

Время сборки индекса GIN очень чувствительно к настройке maintenance_work_mem; не стоит экономить на рабочей памяти во время создания индекса.

Во время серии вставок в существующий индекс GIN, включенный fastupdate, система будет очищать список ожидающих записей, когда этот список станет больше, чем gin_pending_list_limit. Чтобы избежать колебаний во времени отклика, желательно, чтобы очистка списка ожидающих записей происходила в фоновом режиме (т.е. с помощью автоочистки). Операции очистки в переднем плане можно избежать, увеличив gin_pending_list_limit или сделав автоочистку более агрессивной. Однако увеличение порога операции очистки означает, что если все же произойдет очистка в переднем плане, она займет еще больше времени.

gin_pending_list_limit может быть переопределен для отдельных GIN-индексов путем изменения параметров хранения, что позволяет каждому GIN-индексу иметь свой собственный порог очистки. Например, возможно увеличить порог только для GIN-индекса, который может быть часто обновляемым, и уменьшить его в остальных случаях.

Основная цель разработки индексов GIN заключалась в создании поддержки высокомасштабируемого полнотекстового поиска в Tantor BE, и часто возникают ситуации, когда полнотекстовый поиск возвращает очень большой набор результатов. Более того, это часто происходит, когда запрос содержит очень часто встречающиеся слова, так что большой набор результатов даже не полезен. Поскольку чтение множества кортежей с диска и их сортировка может занять много времени, это неприемлемо для производства. (Обратите внимание, что сам поиск по индексу очень быстрый).

Для облегчения контролируемого выполнения таких запросов, GIN имеет настраиваемый мягкий верхний предел на количество возвращаемых строк: параметр конфигурации gin_fuzzy_search_limit. По умолчанию он установлен в 0 (что означает отсутствие ограничения). Если установлено ненулевое значение предела, то возвращаемое множество является подмножеством всего результирующего множества, выбранным случайным образом.

“Soft” означает, что фактическое количество возвращаемых результатов может немного отличаться от указанного лимита, в зависимости от запроса и качества генератора случайных чисел системы.

Из опыта, значения в тысячах (например, 5000 — 20000) работают хорошо.

Эквивалент функциональности B-дерева для нескольких типов данных

Модуль для хранения пар (ключ, значение)

Улучшенная поддержка для int[]

Сходство текста с использованием сопоставления триграмм