56.3. 扩展性

给定一个索引项p和查询值q,这个函数决定是否索引项和查询"一致"; 也即是,对任何该索引项代表的行,谓词 "indexed_columnindexable_operator q"是否可能为真? 对叶子索引项这等价于测试索引条件,对内部树节点它指示是否有必要扫描该节点代表的索引子树。 当结果为true,必须还要返回recheck标志位。这指示了谓词是精确为真还是只是可能为真。 如果recheck = false,索引已经精确地测试了谓词条件, 如果recheck= true,相应的行仅仅是一个候选匹配。 这种情况下,系统还将自动对实际的行值进行评价indexable_operator以检查是否真的匹配。 这一规则允许GiST同时支持无损索引和有损索引。

这个函数的SQL声明必须按照如下方式。

CREATE OR REPLACE FUNCTION my_consistent(internal, data_type, smallint, oid, internal)
RETURNS bool
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT;

C模块中的对应代码可以参考下面的骨架代码。

Datum my_consistent(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(my_consistent);
Datum
my_consistent(PG_FUNCTION_ARGS)
{
 GISTENTRY *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
 data_type *query = PG_GETARG_DATA_TYPE_P(1);
 StrategyNumber strategy = (StrategyNumber) PG_GETARG_UINT16(2);
 /* Oid subtype = PG_GETARG_OID(3); */
 bool *recheck = (bool *) PG_GETARG_POINTER(4);
 data_type *key = DatumGetDataType(entry->key);
 bool retval;
 /*
 * 根据strategy,key和query决定返回值。
 *
 * 使用GIST_LEAF(entry)可以感知函数在索引树的什么位置被调用,比如这在支持=操作符时很方便
 * (可以在非叶子节点检查非空的union()和在叶子节点检测等价性)。
 */
 *recheck = true; /* 如果是精确检查则为假 */
 PG_RETURN_BOOL(retval);
}

这里key是索引中的一个元素,而query是要在索引中查找的值。 StrategyNumber参数指示要应用操作符类中的哪个操作符, 它必须是CREATE OPERATOR CLASS命令指定的操作符编号之一。 依赖于在操作符类中包含的操作符,query的数据类型可能和操作符不同,但是上面的骨架代码假设不是这种情况。

这个方法用于合并树中的信息。输入一个项目的集合,这个函数生成一个代表所有给定项目的新的索引项目。

这个函数的SQL声明必须按照如下方式。

CREATE OR REPLACE FUNCTION my_union(internal, internal)
RETURNS internal
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT;

C模块中的对应代码可以参考下面的骨架代码。

Datum my_union(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(my_union);
Datum
my_union(PG_FUNCTION_ARGS)
{
 GistEntryVector *entryvec = (GistEntryVector *) PG_GETARG_POINTER(0);
 GISTENTRY *ent = entryvec->vector;
 data_type *out,
 *tmp,
 *old;
 int numranges,
 i = 0;
 numranges = entryvec->n;
 tmp = DatumGetDataType(ent[0].key);
 out = tmp;
 if (numranges == 1)
 {
 out = data_type_deep_copy(tmp);
 PG_RETURN_DATA_TYPE_P(out);
 }
 for (i = 1; i < numranges; i++)
 {
 old = out;
 tmp = DatumGetDataType(ent[i].key);
 out = my_union_implementation(out, tmp);
 }
 PG_RETURN_DATA_TYPE_P(out);
}

正如你看到的,这个骨架代码中我们处理了符合union(X, Y, Z) = union(union(X, Y), Z)的数据类型。 在GiST支持方法中实现适当的union算法也可以很容易地支持其它不符合这一条件的数据类型。

union的实现函数应该返回一个由palloc()分配的内存的指针。 不能简单地直接返回输入的东西。

把数据项转换为适合在索引页中存储的格式。

这个函数的SQL声明必须按照如下方式。

CREATE OR REPLACE FUNCTION my_compress(internal)
RETURNS internal
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT;

C模块中的对应代码可以参考下面的骨架代码。

Datum my_compress(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(my_compress);
Datum
my_compress(PG_FUNCTION_ARGS)
{
 GISTENTRY *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
 GISTENTRY *retval;
 if (entry->leafkey)
 {
 /* 把entry->key替换为压缩的版本 */
 compressed_data_type *compressed_data = palloc(sizeof(compressed_data_type));
 /* 从entry->key填充*compressed_data */
 retval = palloc(sizeof(GISTENTRY));
 gistentryinit(*retval, PointerGetDatum(compressed_data),
 entry->rel, entry->page, entry->offset, FALSE);
 }
 else
 {
 /* 通常不需要对非叶子节点做任何处理 */
 retval = entry;
 }
 PG_RETURN_POINTER(retval);
}

当然,为了压缩叶子节点,你需要把compressed_data_type适配到特定的数据类型。

根据你的需求,可能还需要关心如何压缩NULL值,例如存储为(Datum) 0,就像gist_circle_compress那样。

与compress函数正好相反。 把数据项的索引表现转换为可以被数据库处理的格式。

这个函数的SQL声明必须按照如下方式。

CREATE OR REPLACE FUNCTION my_decompress(internal)
RETURNS internal
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT;

C模块中的对应代码可以参考下面的骨架代码。

Datum my_decompress(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(my_decompress);
Datum
my_decompress(PG_FUNCTION_ARGS)
{
 PG_RETURN_POINTER(PG_GETARG_POINTER(0));
}

上面的骨架代码适合不需要解压缩的场合。

返回插入新项目到特定分支的"代价"值。 项目将会被插入到树中penalty最小的路径。 penalty的返回值应该是非负数。 如果返回了负数将会被当作0处理。

这个函数的SQL声明必须按照如下方式。

CREATE OR REPLACE FUNCTION my_penalty(internal, internal, internal)
RETURNS internal
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT; -- in some cases penalty functions need not be strict

C模块中的对应代码可以参考下面的骨架代码。

Datum my_penalty(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(my_penalty);
Datum
my_penalty(PG_FUNCTION_ARGS)
{
 GISTENTRY *origentry = (GISTENTRY *) PG_GETARG_POINTER(0);
 GISTENTRY *newentry = (GISTENTRY *) PG_GETARG_POINTER(1);
 float *penalty = (float *) PG_GETARG_POINTER(2);
 data_type *orig = DatumGetDataType(origentry->key);
 data_type *new = DatumGetDataType(newentry->key);
 *penalty = my_penalty_implementation(orig, new);
 PG_RETURN_POINTER(penalty);
}

penalty函数对索引的性能非常重要。 在插入阶段,它可以用来决定把新增加项目插入到哪个分支。 在查询阶段,越平衡的索引,检索速度越快。

如果需要分裂一个索引页面的时候,这个函数决定页面中哪些项目保存在旧页面里,哪些移动到新页面里。

这个函数的SQL声明必须按照如下方式。

CREATE OR REPLACE FUNCTION my_picksplit(internal, internal)
RETURNS internal
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT;

C模块中的对应代码可以参考下面的骨架代码。

Datum my_picksplit(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(my_picksplit);
Datum
my_picksplit(PG_FUNCTION_ARGS)
{
 GistEntryVector *entryvec = (GistEntryVector *) PG_GETARG_POINTER(0);
 OffsetNumber maxoff = entryvec->n - 1;
 GISTENTRY *ent = entryvec->vector;
 GIST_SPLITVEC *v = (GIST_SPLITVEC *) PG_GETARG_POINTER(1);
 int i,
 nbytes;
 OffsetNumber *left,
 *right;
 data_type *tmp_union;
 data_type *unionL;
 data_type *unionR;
 GISTENTRY **raw_entryvec;
 maxoff = entryvec->n - 1;
 nbytes = (maxoff + 1) * sizeof(OffsetNumber);
 v->spl_left = (OffsetNumber *) palloc(nbytes);
 left = v->spl_left;
 v->spl_nleft = 0;
 v->spl_right = (OffsetNumber *) palloc(nbytes);
 right = v->spl_right;
 v->spl_nright = 0;
 unionL = NULL;
 unionR = NULL;
 /* 初始化项目数组 */
 raw_entryvec = (GISTENTRY **) malloc(entryvec->n * sizeof(void *));
 for (i = FirstOffsetNumber; i <= maxoff; i = OffsetNumberNext(i))
 raw_entryvec[i] = &(entryvec->vector[i]);
 for (i = FirstOffsetNumber; i <= maxoff; i = OffsetNumberNext(i))
 {
 int real_index = raw_entryvec[i] - entryvec->vector;
 tmp_union = DatumGetDataType(entryvec->vector[real_index].key);
 Assert(tmp_union != NULL);
 /*
 * 选择放置索引项目的位置,并相应地更新unionL和unionR。
 * 追加项目到v_spl_left或者v_spl_right,并注意处理计数器。
 */
 if (my_choice_is_left(unionL, curl, unionR, curr))
 {
 if (unionL == NULL)
 unionL = tmp_union;
 else
 unionL = my_union_implementation(unionL, tmp_union);
 *left = real_index;
 ++left;
 ++(v->spl_nleft);
 }
 else
 {
 /*
 * 右边做相同处理
 */
 }
 }
 v->spl_ldatum = DataTypeGetDatum(unionL);
 v->spl_rdatum = DataTypeGetDatum(unionR);
 PG_RETURN_POINTER(v);
}

像penalty一样,picksplit函数对索引的性能也非常重要, 设计合适的penalty和picksplit函数直接关系到实现良好性能的GiST索引。

2个索引项目等价时为真,否则为假。

这个函数的SQL声明必须按照如下方式。

CREATE OR REPLACE FUNCTION my_same(internal, internal, internal)
RETURNS internal
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT;

C模块中的对应代码可以参考下面的骨架代码。

Datum my_same(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(my_same);
Datum
my_same(PG_FUNCTION_ARGS)
{
 prefix_range *v1 = PG_GETARG_PREFIX_RANGE_P(0);
 prefix_range *v2 = PG_GETARG_PREFIX_RANGE_P(1);
 bool *result = (bool *) PG_GETARG_POINTER(2);
 *result = my_eq(v1, v2);
 PG_RETURN_POINTER(result);
}

由于历史的原因,same函数并不是单纯地返回布尔值, 而是将标志位存储到由第3个参数指向的位置。

给定一个索引项目p和查询值q,这个函数决定这2者之间的"距离"。 如果操作符类包含任何排序的操作符,必须要提供这个函数。 通过先返回最小"距离"值的索引项目,可以实现使用了排序操作符的查询,因此结果必须和操作符的语义一致。 对一个叶子索引项目,结果只是到索引项目的距离;对内部项目,结果必须是任何子节点项目的最小距离。

这个函数的SQL声明必须按照如下方式。

CREATE OR REPLACE FUNCTION my_distance(internal, data_type, smallint, oid)
RETURNS float8
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT;

C模块中的对应代码可以参考下面的骨架代码。

Datum my_distance(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(my_distance);
Datum
my_distance(PG_FUNCTION_ARGS)
{
 GISTENTRY *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
 data_type *query = PG_GETARG_DATA_TYPE_P(1);
 StrategyNumber strategy = (StrategyNumber) PG_GETARG_UINT16(2);
 /* Oid subtype = PG_GETARG_OID(3); */
 data_type *key = DatumGetDataType(entry->key);
 double retval;
 /*
 * determine return value as a function of strategy, key and query.
 */
 PG_RETURN_FLOAT8(retval);
}

distance函数的参数,除了recheck标志位,其他和consistent函数相同。 一个叶子节点的距离值必须是精确的,因为一旦返回了元组就没有办法再进行排序了。 对内部节点允许一定程度的近似,只要不大于任何一个子节点的实际距离。 比如,在地理应用中到矩形边界的距离就足够了。 结果值可以是任何有限的float8类型值。 (无穷和负无穷用于在内部作为空等情况使用,因此,不建议distance返回这些值。)