AI 助理
文档备案控制台
官方文档
首页

创建多元索引

更新时间：
复制 MD 格式
产品详情
我的收藏

使用 Python SDK 为数据表创建多元索引，并配置索引字段、预排序、生命周期、虚拟列及摘要与高亮。

前提条件

  • 安装Tablestore Python SDK并初始化客户端。

  • 已创建数据表，并将最大版本数设置为 1。

  • 数据表的数据生命周期为 -1，或已禁止通过 UpdateRow 更新数据。

功能说明

调用 create_search_index 方法为指定数据表创建多元索引。同一数据表可以创建多个多元索引。请求中需要指定数据表、索引名称和完整的索引配置，并将需要查询的列添加到 fields。索引字段的数据类型必须与数据表中对应列的数据类型匹配，支持的类型请参见数据类型。

create_search_index(table_name, index_name, index_meta)
说明

创建多元索引是异步操作。请求成功后，等待索引数据同步完成，再使用索引查询数据。

以下示例为 example_table 创建包含 Keyword 和 Long 字段的 example_index。未设置预排序和生命周期时，索引默认按主键排序，数据永不过期。

table_name = "example_table"
index_name = "example_index"

fields = [
    FieldSchema("category", FieldType.KEYWORD, index=True),
    FieldSchema("price", FieldType.LONG, index=True),
]
index_meta = SearchIndexMeta(fields)

client.create_search_index(table_name, index_name, index_meta)

参数说明

create_search_index 包含以下参数。

名称

类型

说明

table_name（必选）

str

数据表名称。

index_name（必选）

str

多元索引名称。

index_meta（必选）

SearchIndexMeta

索引配置。

索引配置

index_meta 的类型为 SearchIndexMeta，包含以下参数。

名称

类型

说明

fields（必选）

List[FieldSchema]

索引字段列表。

index_setting（可选）

IndexSetting

索引设置。

index_sort（可选）

Sort

索引预排序配置。不设置且索引不包含 Nested 字段时，系统默认按主键排序。Nested 索引不支持预排序。

time_to_live（可选）

int

索引数据的生命周期，单位为秒，默认值为 -1。取值为 -1 或不小于 86400 的整数；-1 表示数据永不过期。设置非 -1 值时，必须禁止通过 UpdateRow 更新数据，且索引生命周期不能超过数据表生命周期。创建后可以通过 update_search_index 修改该值。更多信息，请参见生命周期管理。

索引字段

index_meta.fields[] 中每个元素的类型为 FieldSchema，包含以下参数。

名称

类型

说明

field_name（必选）

str

索引字段名称，可以对应主键列或属性列。

field_type（必选）

FieldType

索引字段的数据类型。多层逻辑关系使用 Nested 类型，JSON 格式数据使用 JSON 类型，地理位置数据使用 Geo-point 类型。

index（可选）

bool

是否为字段建立倒排索引或空间索引，默认值为 False。需要使用该字段查询数据时，设置为 True。

enable_highlighting（可选）

bool

是否启用摘要与高亮。仅 Text 字段支持，默认值为 False。该参数需要使用 6.0.0 及以上版本的 Python SDK，建议使用最新版本。

analyzer（可选）

str

Text 字段使用的分词器。不设置时使用单字分词。

analyzer_parameter（可选）

AnalyzerParameter

分词器参数。设置 analyzer 时，按分词器类型配置对应参数。

enable_sort_and_agg（可选）

bool

是否启用排序与统计聚合，默认值为 False。Text 和 Nested 字段不支持排序与统计聚合，但 Nested 字段的子字段支持。

is_array（可选）

bool

字段是否为数组，默认值为 False。数组值必须以 JSON 数组格式写入，Nested 字段无需设置。

sub_field_schemas（可选）

List[FieldSchema]

Nested 或 JSON 字段的子字段列表。Nested 或 JSON 字段必须配置。

is_virtual_field（可选）

bool

字段是否为虚拟列，默认值为 False。

source_fields（可选）

List[str]

虚拟列映射的数据表字段列表。设置虚拟列时必须配置，当前仅支持一个源字段。

date_formats（可选）

List[str]

Date 字段支持的日期格式列表。Date 字段必须配置。

vector_options（可选）

VectorOptions

Vector 字段的向量配置，包括数据类型、维度和距离度量算法。Vector 字段必须配置。

json_type（可选）

JsonType

JSON 字段的索引类型，取值为 JsonType.OBJECT_JSON 或 JsonType.NESTED_JSON。JSON 字段必须配置。

text_similarity（可选）

TextSimilarity

Text 字段的相似度算法，取值为 TextSimilarity.BM25 或 TextSimilarity.SHORT_TEXT。

向量配置

index_meta.fields[].vector_options 的类型为 VectorOptions，包含以下参数。

名称

类型

说明

data_type（必选）

VectorDataType

向量数据类型，当前仅支持 VectorDataType.VD_FLOAT_32。

dimension（必选）

int

向量维度，最大值为 4096。

metric_type（必选）

VectorMetricType

距离度量算法，取值为 VectorMetricType.VM_EUCLIDEAN、VectorMetricType.VM_COSINE 或 VectorMetricType.VM_DOT_PRODUCT。更多信息，请参见向量检索。

索引设置

index_meta.index_setting 的类型为 IndexSetting，包含以下参数。

名称

类型

说明

routing_fields（可选）

List[str]

自定义路由字段。可以指定一个或多个主键列，通常设置一个。设置多个路由字段时，系统将字段值拼接为一个值。系统根据路由字段值计算索引数据的分布位置，值相同的记录写入同一数据分区。

预排序配置

index_meta.index_sort 的类型为 Sort，包含以下参数。

名称

类型

说明

sorters（必选）

List[Sorter]

预排序方式列表。PrimaryKeySort 按主键排序，FieldSort 按字段值排序。用于 FieldSort 的字段必须开启排序与统计聚合。更多信息，请参见排序和翻页。

主键排序

index_meta.index_sort.sorters[] 中类型为 PrimaryKeySort 的元素用于按主键预排序，包含以下参数。

名称

类型

说明

sort_order（可选）

SortOrder

主键排序顺序，取值为 SortOrder.ASC 或 SortOrder.DESC，默认值为 SortOrder.ASC。

字段值排序

index_meta.index_sort.sorters[] 中类型为 FieldSort 的元素用于按字段值预排序，包含以下参数。

名称

类型

说明

field_name（必选）

str

用于预排序的字段名称。

sort_order（可选）

SortOrder

字段值排序顺序，取值为 SortOrder.ASC 或 SortOrder.DESC，默认值为 SortOrder.ASC。

sort_mode（可选）

SortMode

字段存在多个值时使用的排序方式。

场景示例

设置索引预排序

以下示例按 created_at 字段升序预排序索引数据。

table_name = "example_table"
index_name = "example_index"

fields = [
    FieldSchema("category", FieldType.KEYWORD, index=True),
    FieldSchema(
        "created_at",
        FieldType.LONG,
        index=True,
        enable_sort_and_agg=True,
    ),
]
index_sort = Sort([FieldSort("created_at", SortOrder.ASC)])
index_meta = SearchIndexMeta(fields, index_sort=index_sort)

client.create_search_index(table_name, index_name, index_meta)

设置索引生命周期

以下示例将索引生命周期设置为 7 天。

table_name = "example_table"
index_name = "example_index"

fields = [
    FieldSchema("category", FieldType.KEYWORD, index=True),
    FieldSchema("price", FieldType.LONG, index=True),
]
index_meta = SearchIndexMeta(fields, time_to_live=7 * 24 * 60 * 60)

client.create_search_index(table_name, index_name, index_meta)

设置分词

以下示例为 Text 字段 description 设置分隔符分词，并使用半角逗号（,）分隔写入内容。

table_name = "example_table"
index_name = "example_index"

fields = [
    FieldSchema("category", FieldType.KEYWORD, index=True),
    FieldSchema(
        "description",
        FieldType.TEXT,
        index=True,
        analyzer=AnalyzerType.SPLIT,
        analyzer_parameter=SplitAnalyzerParameter(","),
    ),
]
index_meta = SearchIndexMeta(fields)

client.create_search_index(table_name, index_name, index_meta)

创建向量字段

以下示例创建维度为 4、使用点积计算相似度的 Vector 字段 embedding。

table_name = "example_table"
index_name = "example_index"

fields = [
    FieldSchema("category", FieldType.KEYWORD, index=True),
    FieldSchema(
        "embedding",
        FieldType.VECTOR,
        index=True,
        vector_options=VectorOptions(
            data_type=VectorDataType.VD_FLOAT_32,
            dimension=4,
            metric_type=VectorMetricType.VM_DOT_PRODUCT,
        ),
    ),
]
index_meta = SearchIndexMeta(fields)

client.create_search_index(table_name, index_name, index_meta)

创建虚拟列

以下示例将 Keyword 字段 category 映射为 Long 虚拟列，并将 Long 字段 price 映射为 Keyword 虚拟列。

table_name = "example_table"
index_name = "example_index"

fields = [
    FieldSchema("category", FieldType.KEYWORD, index=True),
    FieldSchema(
        "category_as_long",
        FieldType.LONG,
        index=True,
        is_virtual_field=True,
        source_fields=["category"],
    ),
    FieldSchema("price", FieldType.LONG, index=True),
    FieldSchema(
        "price_as_keyword",
        FieldType.KEYWORD,
        index=True,
        is_virtual_field=True,
        source_fields=["price"],
    ),
]
index_meta = SearchIndexMeta(fields)

client.create_search_index(table_name, index_name, index_meta)

启用摘要与高亮

以下示例为 Text 字段 description 启用摘要与高亮。

table_name = "example_table"
index_name = "example_index"

fields = [
    FieldSchema("category", FieldType.KEYWORD, index=True),
    FieldSchema("price", FieldType.LONG, index=True),
    FieldSchema(
        "description",
        FieldType.TEXT,
        index=True,
        enable_highlighting=True,
    ),
]
index_meta = SearchIndexMeta(fields)

client.create_search_index(table_name, index_name, index_meta)
上一篇：索引管理下一篇：列出多元索引