Table Store Python SDK 建立多元索引 - Tablestore

使用 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)