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

使用 Java SDK 為資料表建立多元索引，並配置索引欄位、預排序、生命週期、虛擬列及摘要與高亮。

前提條件

開始前，完成以下準備工作：

安裝Tablestore Java SDK並初始化用戶端。
已建立資料表，並將最大版本數設定為 1。
資料表的資料生命週期為 -1，或者已禁止通過 UpdateRow 更新資料。

功能說明

調用 createSearchIndex 方法為指定資料表建立多元索引。同一資料表可以建立多個多元索引。請求中需要指定資料表、索引名稱和完整的索引 Schema，並將需要查詢的列添加到 fieldSchemas。索引欄位的資料類型必須與資料表中對應列的資料類型匹配，支援的類型請參見資料類型。

public CreateSearchIndexResponse createSearchIndex(CreateSearchIndexRequest request)

說明

建立多元索引是非同步作業。請求成功後，查詢索引資訊並等待索引狀態變為 RUNNING，再使用索引查詢資料。

以下樣本為 example_table 建立包含 Keyword 和 Long 欄位的 example_index。未設定預排序和生命週期時，索引預設按主鍵排序，資料永不到期。

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("price", FieldType.LONG)));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);

client.createSearchIndex(request);

參數說明

CreateSearchIndexRequest 包含以下參數：

名稱	類型	說明
tableName（必選）	`String`	資料表名稱。
indexName（必選）	`String`	多元索引名稱。
indexSchema（必選）	`IndexSchema`	索引結構。
sourceIndexName（可選）	`String`	重建索引時使用的源索引名稱。僅動態修改多元索引 Schema 時設定。
timeToLive（可選）	`Integer`	索引資料的生命週期，單位為秒，預設值為 -1。取值為 -1 或不小於 86400 的整數；-1 表示資料永不到期。資料保留時間超過該值後，系統自動清理到期資料。設定非 -1 值時，必須禁止通過 `UpdateRow` 更新資料，且索引生命週期不能超過資料表生命週期。建立後可以通過 `updateSearchIndex` 修改該值，也可以通過 `setTimeToLiveInDays` 按天設定。更多資訊，請參見生命週期管理。

索引結構

indexSchema 的類型為 IndexSchema，包含以下參數。

名稱	類型	說明
fieldSchemas（必選）	`List<FieldSchema>`	索引欄位列表。
indexSetting（可選）	`IndexSetting`	索引設定。
indexSort（可選）	`Sort`	索引預排序配置。不設定且索引不包含 Nested 欄位時，系統預設按主鍵排序。Nested 索引不支援預排序。

索引欄位

indexSchema.fieldSchemas[] 中每個元素的類型為 FieldSchema，包含以下參數。

名稱	類型	說明
fieldName（必選）	`String`	索引欄位名稱，可以對應主鍵列或屬性列。
fieldType（必選）	`FieldType`	索引欄位的資料類型。多層邏輯關係使用 Nested 類型，JSON 格式資料可以使用 JSON 類型，也可以按字串寫入後結合數組或 Nested 類型查詢；地理位置資料使用 Geo-point 類型。
index（可選）	`boolean`	是否為欄位建立倒排索引或空間索引，預設值為 `true`。設定為 `false` 時不為該欄位建立索引。
enableHighlighting（可選）	`boolean`	是否啟用摘要與高亮。僅 Text 欄位支援，預設值為 `false`。
analyzer（可選）	`String`	Text 欄位使用的分詞器。不設定時使用單字分詞。
analyzerParameter（可選）	`AnalyzerParameter`	分詞器參數。設定 `analyzer` 時必須按分詞器類型配置對應參數。
enableSortAndAgg（可選）	`boolean`	是否啟用排序與統計彙總，預設值為 `true`。Text 欄位不支援排序與統計彙總；如需對 Text 欄位進行排序或彙總，可以建立 Keyword 類型的虛擬列。
isArray（可選）	`boolean`	欄位是否為數組。數組值必須以 JSON 數組格式寫入，Nested 欄位無需設定。
subFieldSchemas（可選）	`List<FieldSchema>`	Nested 欄位的子欄位列表。Nested 欄位必須配置。
isVirtualField（可選）	`boolean`	欄位是否為虛擬列，預設值為 `false`。
sourceFieldNames（可選）	`List<String>`	虛擬列映射的資料表欄位列表。設定虛擬列時必須配置。
dateFormats（可選）	`List<String>`	Date 欄位支援的日期格式列表。Date 欄位必須配置。
vectorOptions（可選）	`VectorOptions`	Vector 欄位的向量配置，包括資料類型、維度和距離度量演算法。Vector 欄位必須配置。
jsonType（可選）	`JsonType`	JSON 欄位的索引類型，取值為 `OBJECT` 或 `NESTED`。JSON 欄位必須配置。

向量配置

indexSchema.fieldSchemas[].vectorOptions 的類型為 VectorOptions，包含以下參數。

名稱	類型	說明
dataType（必選）	`VectorDataType`	向量資料類型，當前僅支援 `FLOAT_32`。
dimension（必選）	`Integer`	向量維度，最大值為 4096。
metricType（必選）	`VectorMetricType`	距離度量演算法，取值為 `EUCLIDEAN`、`COSINE` 或 `DOT_PRODUCT`，評分越高表示向量越相似。 `EUCLIDEAN` 計算多維空間中的直線距離，Tablestore 不執行最後的平方根計算；`COSINE` 計算向量夾角的餘弦值，常用於文本相似性；`DOT_PRODUCT` 將相同維度向量的對應座標相乘後求和。更多資訊，請參見距離度量演算法。

索引設定

indexSchema.indexSetting 的類型為 IndexSetting，包含以下參數。

名稱	類型	說明
routingFields（可選）	`List<String>`	自訂路由欄位。可以指定一個或多個主鍵列，通常設定一個。設定多個路由欄位時，系統將欄位值拼接為一個值。系統根據路由欄位值計算索引資料的分布位置，值相同的記錄寫入同一資料分區。

預排序配置

indexSchema.indexSort 的類型為 Sort，包含以下參數。

名稱	類型	說明
sorters（可選）	`List<Sort.Sorter>`	預排序方式列表。`PrimaryKeySort` 按主鍵排序，`FieldSort` 按欄位值排序。用於 `FieldSort` 的欄位必須已建立索引並開啟排序與統計彙總。更多資訊，請參見排序和翻頁。

主鍵排序

indexSchema.indexSort.sorters[] 中類型為 PrimaryKeySort 的元素用於按主鍵預排序，包含以下參數。

名稱	類型	說明
order（可選）	`SortOrder`	主鍵排序次序，取值為 `SortOrder.ASC` 或 `SortOrder.DESC`，預設值為 `SortOrder.ASC`。

欄位值排序

indexSchema.indexSort.sorters[] 中類型為 FieldSort 的元素用於按欄位值預排序，包含以下參數。

名稱	類型	說明
fieldName（必選）	`String`	用於預排序的欄位名稱。
order（可選）	`SortOrder`	欄位值排序次序，取值為 `SortOrder.ASC` 或 `SortOrder.DESC`，預設值為 `SortOrder.ASC`。
mode（可選）	`SortMode`	欄位存在多個值時使用的排序方式。

情境樣本

設定索引預排序

以下樣本按 created_at 欄位升序預排序索引資料。

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("price", FieldType.LONG),
        new FieldSchema("description", FieldType.TEXT),
        new FieldSchema("created_at", FieldType.LONG)
                .setEnableSortAndAgg(true)));
indexSchema.setIndexSort(new Sort(
        Collections.<Sort.Sorter>singletonList(
                new FieldSort("created_at", SortOrder.ASC))));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);
client.createSearchIndex(request);

設定索引生命週期

以下樣本將索引生命週期設定為 7 天。請使用 5.12.0 及以上版本的 Java SDK。

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("price", FieldType.LONG)));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);
request.setTimeToLiveInDays(7);
client.createSearchIndex(request);

建立虛擬列

以下樣本將 Keyword 欄位 category 映射為 Long 虛擬列，並將 Long 欄位 price 映射為 Keyword 虛擬列。

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("category_as_long", FieldType.LONG)
                .setVirtualField(true)
                .setSourceFieldName("category"),
        new FieldSchema("price", FieldType.LONG),
        new FieldSchema("price_as_keyword", FieldType.KEYWORD)
                .setVirtualField(true)
                .setSourceFieldName("price")));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);
client.createSearchIndex(request);

啟用摘要與高亮

以下樣本為 Text 欄位 description 啟用摘要與高亮。

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("price", FieldType.LONG),
        new FieldSchema("description", FieldType.TEXT)
                .setEnableHighlighting(true)));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);
client.createSearchIndex(request);