给定一个索引条目 p 和一个查询值 q，此函数判断该索引条目是否与查询 “一致”；也就是说，谓词 “indexed_column indexable_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 模块中匹配的代码可以遵循这个骨架：

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;

    /*
     * determine return value as a function of strategy, key and query.
     *
     * Use GIST_LEAF(entry) to know where you're called in the index tree,
     * which comes handy when supporting the = operator for example (you could
     * check for non empty union() in non-leaf nodes and equality in leaf
     * nodes).
     */

    *recheck = true;        /* or false if check is exact */

    PG_RETURN_BOOL(retval);
}

这里，key 是索引中的一个元素， query 是正在索引中查找的值。 StrategyNumber 参数指示您的操作符类的哪个操作符正在被应用 — 它与 CREATE OPERATOR CLASS 命令中的某个操作符编号 相匹配。

取决于类中包含了哪些操作符，query 的数据类型 可能随操作符而变化，因为它将是操作符右侧的任何类型，可能与左侧 出现的被索引数据类型不同。 （上面的代码骨架假定只有一种可能的类型；如果不是，取 query 参数值时就必须依赖操作符。）建议 consistent 函数的 SQL 声明对 query 参数使用操作符类的被索引数据类型，即使 实际类型可能因操作符而异。

此方法合并树中的信息。给定一组条目，此函数生成一个代表所有给定 条目的新索引条目。

该函数的 SQL 声明必须形如：

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

C 模块中匹配的代码可以遵循这个骨架：

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 函数的结果必须是索引存储类型的一个 值，无论那是什么类型（它可能与被索引列的类型相同或不同）。 union 函数应返回一个指向新 palloc() 出的内存的指针。即使没有类型 变化，也不能按原样返回输入值。

如上所示，union 函数的第一个 internal 参数实际上是一个 GistEntryVector 指针。第二个参数是一个 指向整型变量的指针，可以忽略。 （过去要求 union 函数把其结果值的大小存入 该变量，但现在不再需要了。）

把数据项转换为适合在索引页面中物理存储的格式。 如果省略了 compress 方法，数据项将不经修改 地存入索引。

该函数的 SQL 声明必须形如：

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

C 模块中匹配的代码可以遵循这个骨架：

PG_FUNCTION_INFO_V1(my_compress);

Datum
my_compress(PG_FUNCTION_ARGS)
{
    GISTENTRY  *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
    GISTENTRY  *retval;

    if (entry->leafkey)
    {
        /* replace entry->key with a compressed version */
        compressed_data_type *compressed_data = palloc(sizeof(compressed_data_type));

        /* fill *compressed_data from entry->key ... */

        retval = palloc(sizeof(GISTENTRY));
        gistentryinit(*retval, PointerGetDatum(compressed_data),
                      entry->rel, entry->page, entry->offset, FALSE);
    }
    else
    {
        /* typically we needn't do anything with non-leaf entries */
        retval = entry;
    }

    PG_RETURN_POINTER(retval);
}

当然，您需要把 compressed_data_type 调整为您要转换到的具体类型，以压缩您的叶节点。

把数据项的存储表示转换为操作符类中其他 GiST 方法可以操纵的 格式。 如果省略了 decompress 方法，则假定其他 GiST 方法可以直接在存储的数据格式上工作。 （decompress 不一定是 compress 方法的逆过程；特别地，如果 compress 是有损的，那么 decompress 就不可能精确地重建原始数据。 decompress 也不一定等价于 fetch，因为其他 GiST 方法可能不需要对数据 做完整的重建。）

该函数的 SQL 声明必须形如：

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

C 模块中匹配的代码可以遵循这个骨架：

PG_FUNCTION_INFO_V1(my_decompress);

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

上面的骨架适用于无需解压的情形。 （当然，直接省略整个方法更容易，也推荐这样做。）

返回一个值，表示把新条目插入树的某个特定分支的 “代价”。条目将沿着树中 penalty 最小的路径插入。 penalty 返回的值应当是非负的。 如果返回了负值，它将被当作零。

该函数的 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 模块中匹配的代码可以遵循这个骨架：

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 函数并非只返回一个 float 结果；它必须把值存储在第三个参数指示的 位置。返回值本身会被忽略，不过习惯上会把该参数的地址传回。

penalty 函数对索引的良好性能至关重要。 在插入时，它会用于确定在树中选择把新条目加到哪里时沿哪个分支 下降。在查询时，索引越平衡，查找越快。

当需要拆分索引页面时，此函数决定页面上的哪些条目留在旧页面， 哪些条目移到新页面。

该函数的 SQL 声明必须形如：

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

C 模块中匹配的代码可以遵循这个骨架：

PG_FUNCTION_INFO_V1(my_picksplit);

Datum
my_picksplit(PG_FUNCTION_ARGS)
{
    GistEntryVector *entryvec = (GistEntryVector *) PG_GETARG_POINTER(0);
    GIST_SPLITVEC *v = (GIST_SPLITVEC *) PG_GETARG_POINTER(1);
    OffsetNumber maxoff = entryvec->n - 1;
    GISTENTRY  *ent = entryvec->vector;
    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;

    /* Initialize the raw entry vector. */
    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);

        /*
         * Choose where to put the index entries and update unionL and unionR
         * accordingly. Append the entries to either v->spl_left or
         * v->spl_right, and care about the counters.
         */

        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
        {
            /*
             * Same on the right
             */
        }
    }

    v->spl_ldatum = DataTypeGetDatum(unionL);
    v->spl_rdatum = DataTypeGetDatum(unionR);
    PG_RETURN_POINTER(v);
}

注意，picksplit 函数的结果是通过修改传入的 v 结构来传递的。返回值本身会被忽略， 不过习惯上会把 v 的地址传回。

与 penalty 一样，picksplit 函数对索引的良好性能至关重要。设计合适的 penalty 和 picksplit 实现正是实现高性能 GiST 索引的挑战所在。

如果两个索引条目完全相同则返回 true，否则返回 false。 （“索引条目”是索引存储类型的一个值，不一定是原始 被索引列的类型。）

该函数的 SQL 声明必须形如：

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

C 模块中匹配的代码可以遵循这个骨架：

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 函数并非只返回一个布尔 结果；它必须把标志存储在第三个参数指示的位置。返回值本身会被 忽略，不过习惯上会把该参数的地址传回。

给定一个索引条目 p 和一个查询值 q，此函数确定该索引条目与查询值的 “距离”。如果操作符类包含任何排序操作符，则必须提供 此函数。使用排序操作符的查询将通过首先返回具有最小 “距离”值的索引条目来实现，因此结果必须与操作符的 语义一致。对于叶索引条目，结果只表示到该索引条目的距离；对于 内部树节点，结果必须是任何子条目可能具有的最小距离。

该函数的 SQL 声明必须形如：

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

C 模块中匹配的代码可以遵循这个骨架：

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); */
    /* bool *recheck = (bool *) PG_GETARG_POINTER(4); */
    data_type  *key = DatumGetDataType(entry->key);
    double      retval;

    /*
     * determine return value as a function of strategy, key and query.
     */

    PG_RETURN_FLOAT8(retval);
}

distance 函数的参数与 consistent 函数的参数完全相同。

在确定距离时允许一定的近似，只要结果绝不大于该条目的实际距离。 因此，例如在几何应用中，到外接框的距离通常就足够了。 对于内部树节点，返回的距离不得大于到任何子节点的距离。 如果返回的距离不精确，函数必须把 *recheck 设为 true。（对内部树节点无需如此；对它们，计算总是被假定为不精确 的。）这种情况下，执行器会在从堆中取回元组之后计算精确的距离， 并在必要时对元组重新排序。

如果距离函数对任何叶节点返回 *recheck = true， 那么原始排序操作符的返回类型必须是 float8 或 float4，并且距离函数的结果值必须可与原始排序操作符 的结果值比较，因为执行器将同时使用距离函数结果和重新计算的排序 操作符结果进行排序。否则，距离函数的结果值可以是任何有限的 float8 值，只要结果值的相对顺序与排序操作符返回的 顺序一致。（无穷和负无穷在内部被用于处理空值等情况，因此不建议 distance 函数返回这些值。）

把数据项的压缩索引表示转换为原始数据类型，用于仅索引扫描。 返回的数据必须是原始被索引值的精确、无损的副本。

该函数的 SQL 声明必须形如：

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

参数是一个指向 GISTENTRY 结构的指针。 进入时，其 key 字段包含一个非空的 压缩形式的叶 datum。返回值是另一个 GISTENTRY 结构，其 key 字段包含同一个 datum 的原始未 压缩形式。如果操作符类的 compress 函数对叶条目不做任何处理， fetch 方法可以按原样返回参数。或者，如果 操作符类没有 compress 函数，fetch 方法也 可以省略，因为它必然是空操作。

C 模块中匹配的代码可以遵循这个骨架：

PG_FUNCTION_INFO_V1(my_fetch);

Datum
my_fetch(PG_FUNCTION_ARGS)
{
    GISTENTRY  *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
    input_data_type *in = DatumGetPointer(entry->key);
    fetched_data_type *fetched_data;
    GISTENTRY  *retval;

    retval = palloc(sizeof(GISTENTRY));
    fetched_data = palloc(sizeof(fetched_data_type));

    /*
     * Convert 'fetched_data' into the a Datum of the original datatype.
     */

    /* fill *retval from fetched_data. */
    gistentryinit(*retval, PointerGetDatum(converted_datum),
                  entry->rel, entry->page, entry->offset, FALSE);

    PG_RETURN_POINTER(retval);
}

如果 compress 方法对叶条目是有损的，操作符类就不能支持仅索引 扫描，并且不得定义 fetch 函数。

允许定义控制操作符类行为的用户可见参数。

该函数的 SQL 声明必须形如：

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

该函数会接收一个指向 local_relopts 结构的指针，该结构需要被填充为一组操作符类特定的选项。其他支持 函数可以使用 PG_HAS_OPCLASS_OPTIONS() 和 PG_GET_OPCLASS_OPTIONS() 宏来访问这些选项。

下面给出了 my_options() 的一个示例实现，以及其他支持函数使用 这些参数的方式：

typedef enum MyEnumType
{
    MY_ENUM_ON,
    MY_ENUM_OFF,
    MY_ENUM_AUTO
} MyEnumType;

typedef struct
{
    int32   vl_len_;    /* varlena header (do not touch directly!) */
    int     int_param;  /* integer parameter */
    double  real_param; /* real parameter */
    MyEnumType enum_param; /* enum parameter */
    int     str_param;  /* string parameter */
} MyOptionsStruct;

/* String representation of enum values */
static relopt_enum_elt_def myEnumValues[] =
{
    {"on", MY_ENUM_ON},
    {"off", MY_ENUM_OFF},
    {"auto", MY_ENUM_AUTO},
    {(const char *) NULL}   /* list terminator */
};

static char *str_param_default = "default";

/*
 * Sample validator: checks that string is not longer than 8 bytes.
 */
static void
validate_my_string_relopt(const char *value)
{
    if (strlen(value) > 8)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("str_param must be at most 8 bytes")));
}

/*
 * Sample filler: switches characters to lower case.
 */
static Size
fill_my_string_relopt(const char *value, void *ptr)
{
    char   *tmp = str_tolower(value, strlen(value), DEFAULT_COLLATION_OID);
    int     len = strlen(tmp);

    if (ptr)
        strcpy(ptr, tmp);

    pfree(tmp);
    return len + 1;
}

PG_FUNCTION_INFO_V1(my_options);

Datum
my_options(PG_FUNCTION_ARGS)
{
    local_relopts *relopts = (local_relopts *) PG_GETARG_POINTER(0);

    init_local_reloptions(relopts, sizeof(MyOptionsStruct));
    add_local_int_reloption(relopts, "int_param", "integer parameter",
                            100, 0, 1000000,
                            offsetof(MyOptionsStruct, int_param));
    add_local_real_reloption(relopts, "real_param", "real parameter",
                             1.0, 0.0, 1000000.0,
                             offsetof(MyOptionsStruct, real_param));
    add_local_enum_reloption(relopts, "enum_param", "enum parameter",
                             myEnumValues, MY_ENUM_ON,
                             "Valid values are: \"on\", \"off\" and \"auto\".",
                             offsetof(MyOptionsStruct, enum_param));
    add_local_string_reloption(relopts, "str_param", "string parameter",
                               str_param_default,
                               &validate_my_string_relopt,
                               &fill_my_string_relopt,
                               offsetof(MyOptionsStruct, str_param));

    PG_RETURN_VOID();
}

PG_FUNCTION_INFO_V1(my_compress);

Datum
my_compress(PG_FUNCTION_ARGS)
{
    int     int_param = 100;
    double  real_param = 1.0;
    MyEnumType enum_param = MY_ENUM_ON;
    char   *str_param = str_param_default;

    /*
     * Normally, when opclass contains 'options' method, then options are always
     * passed to support functions.  However, if you add 'options' method to
     * existing opclass, previously defined indexes have no options, so the
     * check is required.
     */
    if (PG_HAS_OPCLASS_OPTIONS())
    {
        MyOptionsStruct *options = (MyOptionsStruct *) PG_GET_OPCLASS_OPTIONS();

        int_param = options->int_param;
        real_param = options->real_param;
        enum_param = options->enum_param;
        str_param = GET_STRING_RELOPTION(options, str_param);
    }

    /* the rest implementation of support function */
}

由于键在 GiST 中的表示方式是灵活的，它可能 依赖于用户指定的参数。例如，可以指定键签名的长度。 示例参见 gtsvector_options()。

返回一个比较器函数，用于以保持局部性的方式对数据排序。它被 CREATE INDEX 和 REINDEX 命令使用。所创建索引的质量取决于 比较器函数确定的排序顺序在多大程度上保持了输入的局部性。

sortsupport 方法是可选的。如果不提供它， CREATE INDEX 会使用 penalty 和 picksplit 函数把每个元组逐个插入树中来构建索引，这要慢得多。

该函数的 SQL 声明必须形如 ：

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

参数是一个指向 SortSupport 结构的指针。至少，函数必须填写其比较器字段。 比较器接收三个参数：两个要比较的 Datum，以及一个指向 SortSupport 结构的指针。 这些 Datum 是两个被索引值，采用它们在索引中的存储格式；也就是 compress 方法返回的格式。 完整的 API 定义在 src/include/utils/sortsupport.h 中。

C 模块中匹配的代码可以遵循这个骨架：

PG_FUNCTION_INFO_V1(my_sortsupport);

static int
my_fastcmp(Datum x, Datum y, SortSupport ssup)
{
  /* establish order between x and y by computing some sorting value z */

  int z1 = ComputeSpatialCode(x);
  int z2 = ComputeSpatialCode(y);

  return z1 == z2 ? 0 : z1 > z2 ? 1 : -1;
}

Datum
my_sortsupport(PG_FUNCTION_ARGS)
{
  SortSupport ssup = (SortSupport) PG_GETARG_POINTER(0);

  ssup->comparator = my_fastcmp;
  PG_RETURN_VOID();
}

给定一个来自 src/include/access/cmptype.h 的 CompareType 值，返回本操作符类用于匹配该功能 的策略号。如果操作符类没有匹配的策略，函数应返回 InvalidStrategy。

它用于时间索引约束（即 PRIMARY KEY 和 UNIQUE）。如果操作符类 提供此函数，并且它能对 COMPARE_EQ 返回 结果，那么它就可以被用于索引约束的非 WITHOUT OVERLAPS 部分。

这个支持函数对应于索引访问方法的回调函数 amtranslatecmptype（见 Section 63.2）。GiST 索引的 amtranslatecmptype 回调函数只是向下 调用相应操作符族的 translate_cmptype 支持函数，因为 GiST 索引 访问方法本身没有固定的策略号。

该函数的 SQL 声明必须形如 ：

CREATE OR REPLACE FUNCTION my_translate_cmptype(integer)
RETURNS smallint
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT;

操作符族的注册则必须形如：

ALTER OPERATOR FAMILY my_opfamily USING gist ADD
    FUNCTION 12 ("any", "any") my_translate_cmptype(int);

C 模块中匹配的代码可以遵循这个骨架：

PG_FUNCTION_INFO_V1(my_translate_cmptype);

Datum
my_translate_cmptype(PG_FUNCTION_ARGS)
{
    CompareType cmptype = PG_GETARG_INT32(0);
    StrategyNumber ret = InvalidStrategy;

    switch (cmptype)
    {
        case COMPARE_EQ:
            ret = BTEqualStrategyNumber;
    }

    PG_RETURN_UINT16(ret);
}

PostgreSQL 提供了一个转换函数： gist_translate_cmptype_common，供使用 RT*StrategyNumber 常量的操作符类使用。 btree_gist 扩展定义了第二个转换函数 gist_translate_cmptype_btree，供使用 BT*StrategyNumber 常量的操作符类使用。

多种数据类型的 B-tree 等价功能

多维立方体的索引

存储 (键, 值) 对的模块

用于 int4 值一维数组的 RD-Tree

树形结构的索引

基于三元组匹配的文本相似度

“浮点区间”的索引