63.3. Опорные функции B-деревьев
Как показано в Таблице 39.9, btree определяет одну необходимую и четыре необязательных опорных функции. Таким образом, пользователь может задать пять методов:
order
Для всех комбинаций типов данных, для которых семейство операторов btree предоставляет операторы сравнения, оно должно предоставлять опорную функцию сравнения в
pg_amproc
с номером 1 и camproclefttype
/amprocrighttype
, равными левому и правому типу сравнения (то есть тем же типам данных, с которыми соответствующие операторы зарегистрированы вpg_amop
). Эта функция сравнения должна принимать два отличных от NULL значенияA
иB
и возвращать значениеint32
, которое будет<
0
,0
или>
0
, когдаA
<
B
,A
=
B
илиA
>
B
, соответственно. Результат NULL не допускается: все значения типа данных должны быть сравнимыми.Если сравниваемые значения имеют сортируемый тип данных, опорной функции сравнения будет передан OID соответствующего правила сортировки через стандартный механизм
PG_GET_COLLATION()
.sortsupport
Дополнительно семейство операторов btree может предоставить функции поддержки сортировки, которые регистрируются под номером опорной функции 2. Эти функции позволяют реализовывать сравнения для целей сортировки гораздо эффективнее, чем это возможно при прямолинейном вызове функции поддержки сравнения. Задействованные в этом программные интерфейсы определены в
src/include/utils/sortsupport.h
.in_range
Дополнительно семейство операторов btree может предоставить опорные функции in_range, которые регистрируются под номером 3. Они не используются в ходе операций с индексом btree; вместо этого они расширяют семантику семейства операторов, чтобы оно могло поддерживать оконные предложения
RANGE
смещение
PRECEDING
иRANGE
смещение
FOLLOWING
(см. Подраздел 4.2.8). По сути они предоставляют дополнительную информацию, позволяющую добавлять или вычитатьсмещение
в соответствии с порядком сортировки, принятым в семействе.Функция
in_range
должна иметь сигнатуруin_range(
значение
type1,база
type1,смещение
type2,вычитание
bool,меньше
bool) returns boolЗначение
ибаза
должны быть одного типа данных, и этот тип должен поддерживаться семейством операторов (то есть это должен быть тип, для которого реализуется сортировка). Однакосмещение
может быть другого типа, который никаким другим образом не поддерживается данным семейством. Например, встроенное семействоtime_ops
предоставляет функцию, для которойсмещение
имеет типinterval
. Семейство может предоставлять функцииin_range
для любых из своих поддерживаемых типов и одного или нескольких типовсмещений
. Каждая функцияin_range
должна регистрироваться вpg_amproc
с полемamproclefttype
, равнымtype1
, иamprocrighttype
, равнымtype2
.Суть действия функции
in_range
зависит от двух логических флагов. Она должна прибавить или вычесть избазы
смещение
, а затем сравнитьзначение
с результатом следующим образом:если
!
вычитание
и!
меньше
, возвращаетсязначение
>=
(база
+
смещение
)если
!
вычитание
именьше
, возвращаетсязначение
<=
(база
+
смещение
)если
вычитание
и!
меньше
, возвращаетсязначение
>=
(база
-
смещение
)если
вычитание
именьше
, возвращаетсязначение
<=
(база
-
смещение
)
Прежде чем делать это, функция должна проверить знак
смещения
и, если оно отрицательное, выдать ошибкуERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE
(22013) с текстом ошибки «invalid preceding or following size in window function» (неверная предшествующая или последующая величина в оконной функции). (Это требуется стандартом SQL, но нестандартные семейства операторов могут проигнорировать данное ограничение, так как оно не несёт большой смысловой нагрузки.) Проверка этого требования делегируется функцииin_range
, чтобы коду ядра не требовалось понимать, что означает «меньше нуля» для произвольного типа данных.Кроме того, функции
in_range
, если это практично, могут не выдавать ошибку, когда операциябаза
+
смещение
илибаза
-
смещение
приводит к переполнению. Правильный результат сравнения можно получить, даже если это значение выходит за границы допустимого диапазона этого типа данных. Заметьте, что если для типа данных определены такие понятия, как «бесконечность» и «NaN», могут потребоваться дополнительные меры для обеспечения согласованности результатовin_range
с обычным порядком сортировки данного семейства операторов.Результаты функции
in_range
должны соответствовать порядку сортировки, устанавливаемому семейством операторов. Точнее говоря, при любых фиксированных аргументахсмещение
ивычитание
справедливо:Если
in_range
сменьше
= true возвращает true для некоторогозначения1
ибазы
, true должно возвращаться для каждогозначения2
<=
значению1
с той жебазой
.Если
in_range
сменьше
= true возвращает false для некоторогозначения1
ибазы
, false должно возвращаться для любогозначения2
>=
значению1
с той жебазой
.Если
in_range
сменьше
= true возвращает true для некоторогозначения
ибазы1
, true должно возвращаться для каждойбазы2
>=
базе1
с тем жезначением
.Если
in_range
сменьше
= true возвращает false для некоторогозначения
ибазы1
, false должно возвращаться для любойбазы2
<=
базе1
с тем жезначением
.
Аналогичные утверждения с противоположными условиями должны выполняться при
меньше
= false.Если упорядочиваемый тип (
type1
) является сортируемым, функцииin_range
будет передан OID соответствующего правила сортировки через стандартный механизм PG_GET_COLLATION().Функции
in_range
не должны обрабатывать NULL в аргументах и обычно помечаются как строгие.equalimage
Дополнительно семейство операторов btree может предоставить опорные функции
equalimage
(«равенство подразумевает равенство образов»), регистрируемые под номером 4. Эти функции позволяют коду ядра определить, безопасно ли применять исключение дубликатов в B-дереве. В настоящее время функцииequalimage
вызываются только при построении или перестроении индекса.Функция
equalimage
должна иметь сигнатуруequalimage(
opcintype
oid
) returns boolЕё результатом будет статическая информация о классе операторов и правиле сортировки. Результат
true
означает, что функцияorder
для класса операторов будет возвращать0
(признак равенства аргументов), только когда аргументыA
иB
взаимозаменяемы без потери семантической информации. Если функцияequalimage
не определена или она возвращаетfalse
, рассчитывать на выполнение данного условия нельзя.В аргументе
opcintype
передаётся
типа данных, индексируемого данным классом операторов. Это сделано для удобства повторного использования нижележащей функцииpg_type
.oidequalimage
в разных классах операторов. Если типopcintype
поддерживает правила сортировки, функцииequalimage
будет передан OID соответствующего правила через стандартный механизмPG_GET_COLLATION()
.С точки зрения класса операторов возвращаемое значение
true
означает, что возможно безопасное применение исключения дубликатов (или оно безопасно для правила сортировки, OID которого был передан функцииequalimage
). Однако код ядра будет считать исключение дубликатов безопасным для индекса, только если для каждого столбца в этом индексе используется класс операторов, регистрирующий функциюequalimage
, и все эти функции при вызове возвращаютtrue
.Равенство образов почти равнозначно простому битовому равенству. Но есть одно небольшое различие: когда индексируется тип данных varlena, представление двух равных образов на диске может отличаться из-за различного применения сжатия TOAST к входным данным. Говоря формально, когда функция
equalimage
класса операторов возвращаетtrue
, можно полагать, что функция на Cdatum_image_eq()
гарантированно будет согласованной с функциейorder
класса операторов (при условии передачи обеим функциям одинакового OID правила сортировки).Код ядра в принципе не может сделать какие-то выводы о свойстве класса операторов «равенство подразумевает равенство образов» в семействе операторов для множества типов, анализируя другие классы операторов в том же семействе. Также не имеет смысла регистрировать межтиповую функцию
equalimage
для семейства операторов, и при попытке сделать это произойдёт ошибка. Это связано с тем, что свойство «равенство подразумевает равенство образов» зависит не только от семантики сортировки/равенства, определяемой в некоторой степени на уровне семейства операторов. Вообще говоря, это свойство относится к конкретному типу и должно рассматриваться отдельно.Для классов операторов, поставляемых в базовом продукте Postgres Pro, принято соглашение регистрировать универсальную функцию
equalimage
. Большинство классов операторов регистрируют в качестве такой функцииbtequalimage()
, которая устанавливает, что исключение дубликатов безопасно без дополнительных условий. Операторы классов для типов данных, поддерживающих правила сортировки, например, для типаtext
, регистрируют функциюbtvarstrequalimage()
, которая устанавливает, что исключение дубликатов безопасно с детерминированными правилами сортировки. Для сохранения порядка в сторонних расширениях также рекомендуется регистрировать их собственные функцииequalimage
.options
В дополнение семейство операторов btree может предоставить опорные функции
options
(«параметры класса операторов»), регистрируемые под номером 5. Эти функции позволяют определить набор видимых пользователю параметров, управляющих поведением класса операторов.Опорная функция
options
должна иметь сигнатуруoptions(
relopts
local_relopts *
) returns voidЭтой функции передаётся указатель на структуру
local_relopts
, в которую нужно внести набор параметров, относящихся к классу операторов. Обращаться к этим параметрам из других опорных функций можно с помощью макросовPG_HAS_OPCLASS_OPTIONS()
иPG_GET_OPCLASS_OPTIONS()
.В настоящее время опорная функция
options
не определена ни для одного из классов операторов btree. Сама организация B-дерева не позволяет гибко менять представление ключей, как это возможно с GiST, SP-GiST, GIN и BRIN. Поэтому с существующим методом доступа к индексу-B-дереву для функцииoptions
нет полезных применений. Тем не менее эта опорная функция была добавлена для B-дерева ради единообразия и не исключено, что она окажется полезной по мере развития реализации B-дерева в Postgres Pro.