文档

创建多元索引

更新时间:

使用CreateSearchIndex接口在数据表上创建一个多元索引。一个数据表支持创建多个多元索引。创建多元索引时,您需要将要查询的字段添加到多元索引中,您还可以配置多元索引路由键、预排序等高级选项。

前提条件

  • 已初始化Client。具体操作,请参见初始化OTSClient

  • 已创建数据表,并且数据表的最大版本数(max Versions)必须为1,数据生命周期(Time to Live)必须满足如下条件中的任意一个。具体操作,请参见创建数据表

    • 数据表的数据生命周期为-1(数据永不过期)。

    • 数据表的数据生命周期不为-1时,数据表为禁止更新状态(即是否允许更新)。

注意事项

  • 创建多元索引时,多元索引中字段的数据类型必须与数据表中字段的数据类型相匹配。更多信息,请参见基础数据类型及映射

  • 如果要修改多元索引为指定数据生命周期(即取值不为-1),则您必须禁用数据表的UpdateRow更新写入功能。同时多元索引的TTL值必须小于或等于数据表的TTL值。更多信息,请参见生命周期管理

参数

创建多元索引时,需要指定数据表名称(TableName)、多元索引名称(IndexName)和索引的结构信息(IndexSchema),其中IndexSchema包含FieldSchemas(Index的所有字段的设置)、IndexSetting(索引设置)和IndexSort(索引预排序设置)。详细参数说明请参见下表。

参数

说明

TableName

数据表名称。

IndexName

多元索引名称。

FieldSchemas

FieldSchema的列表,每个FieldSchema包含如下内容:

  • FieldName(必选):创建多元索引的字段名,即列名,类型为String。

    多元索引中的字段可以是主键列或属性列。

  • FieldType(必选):字段类型,类型为tablestore.FieldType_XXX。更多信息,请参见基础数据类型及映射

  • Array(可选):是否为数组,类型为Boolean。

    如果设置为true,则表示该列是一个数组,在写入时,必须按照JSON数组格式写入,例如["a","b","c"]。

    由于Nested类型是一个数组,当FieldType为Nested类型时,无需设置此参数。

  • Index(可选):是否开启索引,类型为Boolean。

    默认为true,表示对该列构建倒排索引或者空间索引;如果设置为false,则不会对该列构建索引。

  • Analyzer(可选):分词器类型。当字段类型为Text时,可以设置此参数;如果不设置,则默认分词器类型为单字分词。关于分词的更多信息,请参见分词

  • EnableSortAndAgg(可选):是否开启排序与统计聚合功能,类型为Boolean。

    只有EnableSortAndAgg设置为true的字段才能进行排序。关于排序的更多信息,请参见排序和翻页

    重要

    Nested类型的字段不支持开启排序与统计聚合功能,但是Nested类型内部的子列支持开启排序与统计聚合功能。

  • Store(可选):是否在多元索引中附加存储该字段的值,类型为Boolean。

    开启后,可以直接从多元索引中读取该字段的值,而不必反查数据表,可用于查询性能优化。

  • DateFormats(可选):日期的格式,类型为String。当字段类型为Date时,必须设置此参数。更多信息,请参见日期时间类型

  • EnableHighlighting(可选):是否开启查询高亮功能,类型为Boolean。默认值为false,表示不开启查询高亮。如果要使用查询高亮,请设置此参数为true。仅Text类型字段支持查询高亮功能。关于查询高亮的更多信息,请参见查询高亮

    重要

    目前此参数只支持通过表格存储SDK进行配置。

  • VectorOptions(可选):向量字段类型的属性参数。当字段类型为Vector时,必须设置此参数。包括如下内容:

    • DataType:向量数据类型。当前仅支持float32。如果有其他类型需求,请提交工单联系我们。

    • Dimension:向量维度。关于维度限制说明请参见多元索引限制

    • MetricType:向量之间距离度量的算法,支持欧氏距离(euclidean)、余弦相似度(cosine)、点积(dot_product)。

      • 欧氏距离(euclidean):多维空间中两个向量之间的直线距离。出于性能考虑,表格存储中的欧氏距离算法未进行最后的平方根计算。欧氏距离的评分越大表示两个向量的相似度越大。

      • 余弦相似度(cosine):向量空间中两个向量间夹角的余弦值。余弦相似度的评分越高表示两个向量的相似度越大。常用于文本数据的相似度计算。

      • 点积(dot_product):维度相同的两个向量的对应坐标相乘,然后将结果相加。点积的评分越高标识两个向量的相似度越大。

      关于如何选用距离度量算法的更多信息,请参见附录:距离度量算法说明

IndexSetting

索引设置,包含RoutingFields设置。

RoutingFields(可选):自定义路由字段。可以选择部分主键列作为路由字段,在进行索引数据写入时,会根据路由字段的值计算索引数据的分布位置,路由字段的值相同的记录会被索引到相同的数据分区中。

IndexSort

索引预排序设置,包含Sorters设置。如果不设置,则默认按照主键排序。

说明

含有Nested类型的索引不支持IndexSort,没有预排序。

Sorters(必选):索引的预排序方式,支持按照主键排序和字段值排序。关于排序的更多信息,请参见排序和翻页

  • PrimaryKeySort表示按照主键排序,包含如下设置:

    Order:排序的顺序,可按升序或者降序排序,默认为升序。

  • FieldSort表示按照字段值排序, 包含如下设置:

    只有建立索引且开启排序与统计聚合功能的字段才能进行预排序。

    • FieldName:排序的字段名。

    • Order:排序的顺序,可按照升序或者降序排序,默认为升序。

    • Mode:当字段存在多个值时的排序方式。

TimeToLive

可选参数,默认值为-1。数据生命周期(TTL),即数据的保存时间。

当数据的保存时间超过设置的数据生命周期时,系统会自动清理超过数据生命周期的数据。

数据生命周期至少为86400秒(一天)或-1(数据永不过期)。

多元索引生命周期的使用方式,请参见生命周期管理

示例

创建多元索引时使用默认配置

以下示例用于创建一个多元索引。该多元索引包含col_keyword(Keyword类型)、col_long(Long类型)和col_vector(Vector类型)三列。

func createSearchIndex(client *tablestore.TableStoreClient) {
    request := &tablestore.CreateSearchIndexRequest{}
    request.TableName = "<TABLE_NAME>"
    request.IndexName = "<SEARCH_INDEX_NAME>"
    request.IndexSchema = &tablestore.IndexSchema{
        FieldSchemas: []*tablestore.FieldSchema{
            {
                FieldName:        proto.String("col_keyword"),
                FieldType:        tablestore.FieldType_KEYWORD, // 字符串类型
                Index:            proto.Bool(true),
                EnableSortAndAgg: proto.Bool(true),
            },
            {
                FieldName:        proto.String("col_long"),
                FieldType:        tablestore.FieldType_LONG, // 数字类型
                Index:            proto.Bool(true),
                EnableSortAndAgg: proto.Bool(true),
            },
            {
                FieldName: proto.String("col_vector"),
                FieldType: tablestore.FieldType_VECTOR, // 向量类型
                Index:     proto.Bool(true),
                VectorOptions: &tablestore.VectorOptions{
                    VectorDataType:   tablestore.VectorDataType_FLOAT_32.Enum(),
                    Dimension:        proto.Int32(4), // 向量维度为4,相似度算法为点积
                    VectorMetricType: tablestore.VectorMetricType_DOT_PRODUCT.Enum(),
                },
            },
        },
    }
    _, err := client.CreateSearchIndex(request)
    if err != nil {
        fmt.Println("Failed to create searchIndex with error:", err)
        return
    }
}

创建多元索引时指定IndexSort

以下示例用于创建一个多元索引,同时指定索引预排序。该多元索引包含col1(Keyword类型)和col2(Long类型)两列。

func createSearchIndex_withIndexSort(client *tablestore.TableStoreClient){
    request := &tablestore.CreateSearchIndexRequest{}
    request.TableName = "<TABLE_NAME>" //设置数据表名称。
    request.IndexName = "<SEARCH_INDEX_NAME>" //设置多元索引名称。

    schemas := []*tablestore.FieldSchema{}
    field1 := &tablestore.FieldSchema{
        FieldName: proto.String("col1"), //设置字段名,使用proto.String用于获取字符串指针。
        FieldType: tablestore.FieldType_KEYWORD, //设置字段类型。
        Index:     proto.Bool(true), //设置开启索引。
        EnableSortAndAgg: proto.Bool(true), //设置开启排序与统计聚合功能。
    }
    field2 := &tablestore.FieldSchema{
        FieldName: proto.String("col2"),
        FieldType: tablestore.FieldType_LONG,
        Index:     proto.Bool(true),
        EnableSortAndAgg: proto.Bool(true),
    }

    schemas = append(schemas, field1, field2)
    request.IndexSchema = &tablestore.IndexSchema{
        FieldSchemas: schemas, //设置多元索引包含的字段。
        IndexSort: &search.Sort{ // 指定索引预排序。先按照col2升序,再按照col1降序排序。
            Sorters: []search.Sorter{
                &search.FieldSort{
                    FieldName: "col2",
                    Order:     search.SortOrder_ASC.Enum(),
                },
                &search.FieldSort{
                    FieldName: "col1",
                    Order:     search.SortOrder_DESC.Enum(),
                },
            },
        },
    }
    resp, err := client.CreateSearchIndex(request) //调用client创建多元索引。
    if err != nil {
        fmt.Println("error :", err)
        return
    }
    fmt.Println("CreateSearchIndex finished, requestId:", resp.ResponseInfo.RequestId)
}

创建多元索引时设置数据生命周期

重要

请确保数据表的更新状态为禁止。

func createIndexWithTTL(client *tablestore.TableStoreClient) {
    request := &tablestore.CreateSearchIndexRequest{}
    request.TableName = "<TABLE_NAME>"
    request.IndexName = "<SEARCH_INDEX_NAME>"
    schemas := []*tablestore.FieldSchema{}
    field1 := &tablestore.FieldSchema{
        FieldName:        proto.String("col1"),         //设置字段名,使用proto.String用于获取字符串指针。
        FieldType:        tablestore.FieldType_KEYWORD, //设置字段类型。
        Index:            proto.Bool(true),             //设置开启索引。
        EnableSortAndAgg: proto.Bool(true),             //设置开启排序与统计聚合功能。
    }
    field2 := &tablestore.FieldSchema{
        FieldName:        proto.String("col2"),
        FieldType:        tablestore.FieldType_LONG,
        Index:            proto.Bool(true),
        EnableSortAndAgg: proto.Bool(true),
    }
    schemas = append(schemas, field1, field2)
    request.IndexSchema = &tablestore.IndexSchema{
        FieldSchemas: schemas, //设置多元索引包含的字段。
    }
    request.TimeToLive = proto.Int32(3600 * 24 * 7) // 设置多元索引TTL为7天过期。
    resp, err := client.CreateSearchIndex(request)
    if err != nil {
       fmt.Println("error :", err)
       return
   }
    fmt.Println("createIndexWithTTL finished, requestId:", resp.ResponseInfo.RequestId)
}

创建多元索引时开启查询高亮

以下示例用于创建一个多元索引。该多元索引包含col_keyword(Keyword类型)、col_long(Long类型)、col_text(Text类型)和col_nested(Nested类型)四列,其中col_nested包括level1_text(Text类型)和level1_nested(Nested类型)两个子列,level1_nested子列还包含了level2_text(Text类型)一个子列。同时为col_text列、col_nested中的level1_text列、col_nested.level1_nested中的level2_text列开启查询高亮功能。

func createSearchIndexwithHighlighting(client *tablestore.TableStoreClient) {
    request := &tablestore.CreateSearchIndexRequest{}
    request.TableName = "<TABLE_NAME>"
    request.IndexName = "<SEARCH_INDEX_NAME>"
    request.IndexSchema = &tablestore.IndexSchema{
        FieldSchemas: []*tablestore.FieldSchema{
            {
                FieldName:        proto.String("col_keyword"),
                FieldType:        tablestore.FieldType_KEYWORD, // 字符串类型。
                Index:            proto.Bool(true),
                EnableSortAndAgg: proto.Bool(true),
            },
            {
                FieldName:        proto.String("col_long"),
                FieldType:        tablestore.FieldType_LONG, // 数字类型。
                Index:            proto.Bool(true),
                EnableSortAndAgg: proto.Bool(true),
            },
            {//为非嵌套类型开启查询高亮功能。
                FieldName: proto.String("col_text"),
                FieldType: tablestore.FieldType_TEXT, // 可分词字符串类型。
                Index:     proto.Bool(true),
                EnableSortAndAgg: proto.Bool(true),
                EnableHighlighting: proto.Bool(true),
            },
            {//为嵌套类型字段中的子列开启查询高亮功能。
                FieldName: proto.String("col_nested"),
                FieldType: tablestore.FieldType_NESTED,
                FieldSchemas: []*tablestore.FieldSchema{
                    {
                        FieldName:          proto.String("level1_text"),
                        FieldType:          tablestore.FieldType_TEXT,
                        Index:              proto.Bool(true),
                        EnableHighlighting: proto.Bool(true),
                    },
                    {
                        FieldName: proto.String("level1_nested"),
                        FieldType: tablestore.FieldType_NESTED,
                        FieldSchemas: []*tablestore.FieldSchema{
                            {
                                FieldName:          proto.String("level2_text"),
                                FieldType:          tablestore.FieldType_TEXT,
                                Index:              proto.Bool(true),
                                EnableHighlighting: proto.Bool(true),
                            },
                        },
                    },
                },
            },
        },
    }
    _, err := client.CreateSearchIndex(request)
    if err != nil {
        fmt.Println("Failed to create searchIndex with error:", err)
        return
    }
}

常见问题

相关文档

  • 创建多元索引后,您可以选择合适的查询类型进行多维度数据查询。多元索引查询类型包括精确查询多词精确查询全匹配查询匹配查询短语匹配查询前缀查询范围查询通配符查询地理位置查询多条件组合查询向量检索嵌套类型查询列存在性查询

    当通过Search接口查询数据时,如果要对结果集进行排序或者翻页,您可以使用排序和翻页功能来实现。具体操作,请参见排序和翻页

  • 当通过Search接口查询数据时,如果要按照某一列对结果集做折叠,使对应类型的数据在结果展示中只出现一次,您可以使用折叠(去重)功能来实现。具体操作,请参见折叠(去重)

  • 如果希望清理多元索引中的历史数据或者希望延长数据保存时间,您可以修改多元索引的数据生命周期。具体操作,请参见生命周期管理

  • 如果要进行数据分析,例如求最值、求和、统计行数等,您可以使用Search接口的统计聚合功能或者SQL查询来实现。具体操作,请参见统计聚合SQL查询

  • 如果要快速导出数据,而不关心整个结果集的顺序时,您可以使用ParallelScan接口和ComputeSplits接口实现多并发导出数据。具体操作,请参见并发导出数据

  • 如果要在多元索引中新增、更新或者删除索引列,您可以使用动态修改schema功能实现。具体操作,请参见动态修改schema

  • 如果要获取某个数据表关联的所有多元索引的列表信息,您可以使用列出多元索引列表功能实现。具体操作,请参见列出多元索引列表

  • 如果要查询多元索引的描述信息,包括多元索引的字段信息和索引配置等,您可以使用查询多元索引描述信息功能实现。具体操作,请参见查询多元索引描述信息

  • 如果不再需要使用多元索引,您可以删除多元索引。具体操作,请参见删除多元索引