如表 38.8中所示,btree定义了一种必需的和两种可选的支持函数。
对于btree操作符族为其提供了比较操作符的每一种数据类型组合,操作符族必须提供一个比较支持函数,在pg_amproc
中注册:支持函数编号为1,amproclefttype
/amprocrighttype
等于比较的左右数据类型(即匹配的操作符注册在pg_amop
中的数据类型)。比较函数必须接收两个非空值A
和B
并且返回一个int32
值,返回值在A
<
B
、A
=
B
以及A
>
B
时分别为<
0
、0
和>
0
。不允许空值结果:该数据类型的所有值必须是可比较的。例子请见src/backend/access/nbtree/nbtcompare.c
。
如果被比较的值是一种可排序的数据类型,合适的排序规则OID将使用标准的PG_GET_COLLATION()机制被传递给比较支持函数。
可选地,btree操作符族可以提供排序支持函数,它们以支持函数编号2注册。这些函数允许以一种比单纯调用比较支持函数更加高效的方式实现排序比较。涉及的API在src/include/utils/sortsupport.h
中定义。
可选地,btree操作符族可以提供in_range支持函数,它们以支持函数编号3注册。在btree索引操作期间不会用到这些函数,它们扩展了操作符族的语义,这样就能支持包含RANGE
offset
PRECEDING
以及RANGE
offset
FOLLOWING
窗口帧界类型(见第 4.2.8 节)的窗口子句。归根到底,这些函数所提供的额外信息是如何以一种与该操作符族的数据排序相兼容的方式加上或者减去一个offset
值。
一个in_range
函数必须具有这样的签名
in_range(val
type1,base
type1,offset
type2,sub
bool,less
bool) returns bool
val
和base
必须是同一种类型,该类型也是操作符族所支持的类型之一(即它提供排序的一种类型)。不过,offset
可以是一种不同的类型,该类型有可能不被该操作符族所支持。例如内建的time_ops
族提供了一个in_range
函数,其offset
是类型interval
。一个操作符族可以为其所支持的任意类型提供in_range
函数以及一个或者更多种offset
类型。每一个in_range
函数在进入到pg_amproc
时,需要有amproclefttype
等于type1
以及amprocrighttype
等于type2
。
in_range
函数的本质语义取决于两个布尔标志参数。它应该将base
和offset
相加或者相减,然后用val
与其结果比较:
如果!
sub
并且!
less
,则返回val
>=
(base
+
offset
)
如果!
sub
并且less
,则返回val
<=
(base
+
offset
)
如果sub
并且!
less
,则返回val
>=
(base
-
offset
)
如果sub
并且less
,则返回val
<=
(base
-
offset
)
在这样做之前,该函数应该检查offset
的符号:如果它小于零,则抛出错误ERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE
(22013)外加“invalid preceding or following size in window function”这样的错误文本(这是SQL标准所要求的,不过非标准操作符族可能会选择忽视这一限制,因为似乎其语义必要性很小)。这种要求被委托给了in_range
函数,这样核心代码不需要理解对一种特定数据类型“less than zero”表示什么。
一个额外的期望是,如果可行,in_range
函数应当在base
+
offset
或者base
-
offset
溢出时避免抛出错误。即便值超过了该数据类型的范围,也可以确定正确的比较结果。注意,如果数据类型包括诸如“infinity”或者“NaN”之类的概念,就需要额外的注意确保in_range
的结果符合该操作符族的正常排序顺序。
in_range
函数的结果必须与操作符族施加的排序顺序保持一致。准确的来说,给定任意固定的offset
值以及sub
值,那么:
如果带有less
= true的in_range
对某个val1
和base
为真,则它必须对每一个有相同base
的val2
<=
val1
为真。
如果带有less
= true的in_range
对某个val1
和base
为假,则它必须对每一个有相同base
的val2
>=
val1
为假。
如果带有less
= true的in_range
对于某些val
和base1
为真,那么它对于每一个有相同val
的base2
>=
base1
也必须为真。
如果带有less
=
true的in_range
对于某些val
和base1
为假, name它对于每一个有相同val
的base2
<=
base1
也必须为假。
当less
= false时,类似的具有相逆条件的语句成立。
如果被排序的类型(type1
)是可排序的,合适的排序规则OID将使用标准的PG_GET_COLLATION()机制被传递给in_range
函数。
in_range
函数不需要处理NULL输入,并且通常将被标记为strict。