61.3. 可扩展性

比较两个键（不是被索引项）并且返回一个整数，整数可以是小于零、零、大于零， 分别表示第一个键小于、等于、大于第二个键。空值键不会被传递给这个函数。

给定一个要被索引的项，返回一个 palloc 过的键的数组。 被返回的键的数量必须被存储在*nkeys中。 如果键中的任意一个可能为空，还要 palloc 一个*nkeys个 bool域的数组，将它的地址存储在*nullFlags中， 并且根据需要设置这些空值标志。如果所有的键都非空， *nullFlags可以被留成NULL（其初始值）。 如果该项不包含键，返回值可以为NULL。

给定一个要被查询的值，返回一个 palloc 过的键的数组。 即query是一个可索引操作符（左手边是被索引列）的右手边的值。 n是操作符类中操作符的策略号（见第 35.14.2 节）。 通常，extractQuery将需要参考n来判断query 的数据类型以及它应该用什么方法来抽取键值。被返回的键的数量必须被存储在 *nkeys中。如果键中的任意一个可能为空，还要 palloc 一个 *nkeys个bool域的数组，将它的地址存储在 *nullFlags中，并且根据需要设置这些空值标志。如果所有的键都非空， *nullFlags可以被留成NULL（其初始值）。 如果该项不包含键，返回值可以为NULL。

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个布尔值的数组， 并且把它的地址存储在*pmatch中。如果一个键要求部分匹配， 该数组的对应元素应该被设置为 TRUE，否则设置为 FALSE。如果*pmatch 被设置为NULL，则 GIN 假定不需要部分匹配。在调用前， 该变量被初始化为NULL， 这样这个参数可以简单地被不支持部分匹配的操作符类忽略。

extra_data是一个输出参数，它允许extractQuery 传递额外数据给consistent和comparePartial方法。 要用它，extractQuery必须分配一个*nkeys个指针的数组， 并且把它的地址存储在*extra_data中， 然后把任何它想存储的东西存到单个指针中。在调用前该变量被初始化为 NULL，这样这个参数可以简单地被不需要额外数据的操作符类忽略。 如果*extra_data被设置，整个数组被传递给consistent方法， 并且适当的元素会被传递给comparePartial方法。

如果一个被索引项满足（如果重新检查指示被返回，则表示可能满足）有策略号 n的查询操作符，则返回 TRUE。这个函数并没有直接访问被索引项的值， 因为GIN没有显式存储项。 可用的是关于哪些从查询抽取出的键值出现在一个给定被索引项中的知识。 check数组的长度是nkeys，它和前面由 extractQuery为这个查询数据返回的键的数目相同。 如果被索引项包含一个查询键，那么check数组的对应元素为 TRUE， 即如果 (check[i] == TRUE) ，则extractQuery 结果数组的第 i 个键存在于被索引项中。在consistent 方法需要参考原始query数据的情况中，它会被传递进来， 前面由extractQuery返回的queryKeys[]和 nullFlags[]数组也一样。extra_data是由 extractQuery返回的额外数据数组， 如果没有额外数据则为NULL。

当extractQuery在queryKeys[]中返回一个空值键时， 如果被索引项包含一个空值键则对应的check[]元素为 TRUE。即， check[]的语义类似IS NOT DISTINCT FROM。 如果consistent函数需要说出一个常规值匹配和一个空值匹配之间的区别， 它可以检查对应的nullFlags[]元素。

在成功时，如果堆元组需要根据查询操作符被重新检查，则*recheck 应该被设置为 TRUE，或者如果索引测试是准确的则设置为 FALSE。即， 一个 FALSE 返回值保证堆元组不匹配查询；一个 TRUE 返回值以及设置为 FALSE 的 *recheck保证堆元组匹配查询；并且一个 TRUE 返回值和设置为 TRUE 的 *recheck表示堆元组可能匹配查询， 因此它需要被取出并且通过在原始的被索引项上计算查询操作符来重新检查。

triConsistent类似于consistent，但不是一个布尔的 check[]，对每个键有三种可能值：GIN_TRUE、 GIN_FALSE和GIN_MAYBE。GIN_FALSE和 GIN_TRUE具有和常规布尔值相同的含义。GIN_MAYBE 意味着键的存在未知。当GIN_MAYBE值出现时，如果项匹配 （不管该索引项是否包含对应的查询键），该函数应该只返回 GIN_TRUE。 同样地，如果项不匹配（不管它是否包含 GIN_MAYBE 键），该函数必须只返回 GIN_FALSE。 如果结果依赖于 GIN_MAYBE 项，即无法根据已知查询键确认或拒绝匹配， 该函数必须返回 GIN_MAYBE。

当在check向量中没有 GIN_MAYBE 值时，GIN_MAYBE 返回值等效于在布尔函数consistent中设置recheck标志。

比较一个部分匹配查询键和一个索引键。返回一个整数，其符号指示结果： 小于零表示索引键不匹配查询，但是索引扫描应该继续；零表示索引键匹配查询； 大于零表示索引扫描应该停止，因为没有更多可能的匹配。 产生该部分匹配查询的操作符的策略号n将被提供， 可以通过其语义决定什么时候结束扫描。还有，extra_data 是由extractQuery产生的额外数据数组中的对应元素， 如果没有则为NULL。空值不会被传递给这个函数。