Java SDK 建立多元索引 -

使用 CreateSearchIndex 介面在資料表上建立一個多元索引。一個資料表支援建立多個多元索引。建立多元索引時，您需要將要查詢的欄位添加到多元索引中，您還可以配置多元索引路由鍵、預排序等進階選項。

前提條件

已初始化 Client。具體操作，請參見初始化OTSClient。
已建立資料表，並且資料表的最大版本數（max Versions）必須為1，資料生命週期（Time to Live）必須滿足如下條件中的任意一個。具體操作，請參見建立資料表。
- 資料表的資料生命週期為 -1（資料永不到期）。
- 資料表的資料生命週期不為 -1 時，資料表為禁止更新狀態（即是否允許更新為否）。
已瞭解多元索引支援的欄位類型，以及多元索引欄位類型與資料表欄位類型的映射關係。更多資訊，請參見資料類型介紹。

注意事項

建立多元索引時，多元索引中欄位的資料類型必須與資料表中欄位的資料類型相匹配。更多資訊，請參見資料類型介紹。
如果要修改多元索引為指定資料生命週期（即取值不為 -1），您必須禁用資料表的 UpdateRow 更新寫入功能。同時多元索引的 TTL 值必須小於或等於資料表的 TTL 值。更多資訊，請參見生命週期管理。

介面

public class CreateSearchIndexRequest implements Request {
    /**資料表名稱。*/
    private String tableName;
    /**多元索引名稱。*/
    private String indexName;
    /**多元索引的 schema 結構。*/
    private IndexSchema indexSchema;
    /**
     * 一般情況下，不需要設定本欄位。
     * 僅在動態修改多元索引 schema 的情境下，通過 setter 方法進行設定本欄位，作為重建索引的源索引名字。
     */
    private String sourceIndexName;
    /**索引資料的 TTL 時間，單位為秒。在多元索引建立後，該配置項可通過調用 UpdateSearchIndex 介面動態更改。*/
    private Integer timeToLive;
}

public class IndexSchema implements Jsonizable {
    /**關於某個 index 的設定。*/
    private IndexSetting indexSetting;
    /**該 index 的所有欄位的設定。*/
    private List<FieldSchema> fieldSchemas;
    /**自訂索引的預排序方式。*/
    private Sort indexSort;
}

參數

建立多元索引時，需要指定資料表名稱（tableName）、多元索引名稱（indexName）和索引的結構資訊（indexSchema），其中 indexSchema 包含 fieldSchemas（Index 所有欄位的設定）、indexSetting（索引設定）和 indexSort（索引預排序設定）。詳細參數說明請參見下表。

參數	說明
tableName	資料表名稱。
indexName	多元索引名稱。
fieldSchemas	索引欄位列表，每個 fieldSchema 包含如下內容： fieldName（必選）：建立多元索引的欄位名，即列名，類型為 String。多元索引中的欄位可以是主鍵列或屬性列。 fieldType（必選）：欄位類型，類型為 FieldType.XXX。更多資訊，請參見資料類型介紹。說明如果要進行多層邏輯關係的資料存放區和查詢，您可以使用巢狀型別儲存資料。更多資訊，請參見數組和巢狀型別。如果要儲存和查詢 JSON 格式資料，您可以在資料表中使用字串方式儲存 JSON 資料，然後通過多元索引中的數組和巢狀型別實現 JSON 資料的靈活查詢。更多資訊，請參見數組和巢狀型別。如果應用中需要地理位置相關查詢，您可以使用 Geo-point 欄位類型儲存資料。 Index（可選）：是否開啟索引，類型為 Boolean。預設為 true，表示對該列構建倒排索引或者空間索引；如果設定為 false，則不會對該列構建索引。 enableHighlighting（可選）：是否開啟查詢高亮功能，類型為 Boolean。預設值為 false，表示不開啟查詢高亮。如果要使用查詢高亮，請設定此參數為 true。僅 Text 類型欄位支援查詢高亮功能。關於查詢高亮的更多資訊，請參見摘要與高亮。 analyzer（可選）：分詞器類型。當欄位類型為 Text 時，可以設定此參數；如果不設定，則預設分詞器類型為單字分詞。關於分詞的更多資訊，請參見分詞。 analyzerParameter（可選）：分詞參數配置，請根據不同分詞器類型設定相應參數。當為欄位配置了 analyzer 時，必須設定此參數。更多資訊，請參見分詞。 enableSortAndAgg（可選）：是否開啟排序與統計彙總功能，類型為 Boolean。預設值為 true，表示開啟排序與統計彙總。只有 enableSortAndAgg 設定為 true 的欄位才能進行排序。關於排序的更多資訊，請參見排序和翻頁。重要 Text 類型的欄位不支援排序和統計彙總。如果 Text 類型的欄位同時需要進行排序或統計彙總，可以通過虛擬列為 Keyword 類型實現。具體操作，請參見虛擬列。 isArray（可選）：是否為數組，類型為 Boolean。如果設定為 true，則表示該列是一個數組，在寫入時，必須按照 JSON 數組格式寫入，例如`["a","b","c"]`。由於 Nested 類型是一個數組，當 fieldType 為 Nested 類型時，無需設定此參數。 subFieldSchemas：當欄位類型為 Nested 類型時，需要通過此參數設定巢狀型別欄位中子列的索引類型，類型為 FieldSchema 的列表。 isVirtualField（可選）：該欄位是否為虛擬列，類型為 Boolean，預設值為 false。如果要使用虛擬列，請設定此參數為 true。關於虛擬列的更多資訊，請參見虛擬列。 sourceFieldName（可選）：資料表中的欄位名稱，類型為 String。當設定 isVirtualField 為 true 時，必須設定此參數。 dateFormats（可選）：日期的格式，類型為 String。當欄位類型為 Date 時，必須設定此參數。更多資訊，請參見日期時間類型。 vectorOptions（可選）：向量欄位類型的屬性參數。當欄位類型為 Vector 時，必須設定此參數。包括如下內容： dataType：向量資料類型。當前僅支援 float32。如果有其他類型需求，請提交工單聯絡我們。 dimension：向量維度。關於維度限制說明請參見多元索引限制。 metricType：向量之間距離度量的演算法，支援歐氏距離（euclidean）、餘弦相似性（cosine）、點積（dot_product）。歐氏距離（euclidean）：多維空間中兩個向量之間的直線距離。出於效能考慮，Table Store中的歐氏距離演算法未進行最後的平方根計算。歐氏距離的評分越大表示兩個向量的相似性越大。餘弦相似性（cosine）：向量空間中兩個向量間夾角的餘弦值。餘弦相似性的評分越高表示兩個向量的相似性越大。常用於文本資料的相似性計算。點積（dot_product）：維度相同的兩個向量的對應座標相乘，然後將結果相加。點積的評分越高標識兩個向量的相似性越大。關於如何選用距離度量演算法的更多資訊，請參見附錄：距離度量演算法說明。
indexSetting	索引設定，包含 routingFields 設定。 routingFields（可選）：自訂路由欄位。可以選擇部分主鍵列作為路由欄位，在進行索引資料寫入時，會根據路由欄位的值計算索引資料的分布位置，路由欄位的值相同的記錄會被索引到相同的資料分區中。
indexSort	索引預排序設定，包含 sorters 設定。如果不設定，則預設按照主鍵排序。說明含有 Nested 類型的索引不支援 indexSort，沒有預排序。 sorters（可選）：索引預排序方式的列表，支援按照主鍵排序和欄位值排序。關於排序的更多資訊，請參見排序和翻頁。 PrimaryKeySort 表示按照主鍵排序，包含如下設定： order：排序的順序，可按升序或者降序排序，預設為升序（SortOrder.ASC）。 FieldSort 表示按照欄位值排序，只有建立索引且開啟排序與統計彙總功能的欄位才能進行預排序。包含如下設定： fieldName：排序的欄位名。 order：排序的順序，可按照升序或者降序排序，預設為升序（SortOrder.ASC）。 mode：當欄位存在多個值時的排序方式。
sourceIndexName	選擇性參數。一般情況下，不需要設定本欄位。僅在動態修改多元索引 schema 的情境下，通過 setter 方法設定本欄位，作為重建索引的源索引名字。
timeToLive	選擇性參數。資料生命週期（TTL），即資料的儲存時間，單位為秒。預設值為 -1，表示資料永不到期。資料生命週期的取值最低為 86400 秒（一天），也可設定為 -1（永不到期）。當資料的儲存時間超過設定的資料生命週期時，系統會自動清理超過資料生命週期的資料。關於多元索引生命週期的使用方式，請參見生命週期管理。

樣本

建立多元索引時使用預設配置

以下樣本用於建立一個多元索引。該多元索引包含 Col_Keyword（KEYWORD 類型）、Col_Long（LONG 類型）和 Col_Vector（VECTOR 類型）三列，按照資料表主鍵進行預排序且資料永不到期。

private static void createSearchIndex(SyncClient client) {
    CreateSearchIndexRequest request = new CreateSearchIndexRequest();
    //設定資料表名稱。
    request.setTableName("<TABLE_NAME>"); 
    //設定多元索引名稱。
    request.setIndexName("<SEARCH_INDEX_NAME>"); 
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
            //設定欄位名和類型。
            new FieldSchema("Col_Keyword", FieldType.KEYWORD), 
            new FieldSchema("Col_Long", FieldType.LONG),
            // 設定向量類型。
            new FieldSchema("Col_Vector", FieldType.VECTOR).setIndex(true)
                    // 向量維度為 4，相似性演算法為點積。
                    .setVectorOptions(new VectorOptions(VectorDataType.FLOAT_32, 4, VectorMetricType.DOT_PRODUCT))
    ));
    request.setIndexSchema(indexSchema);
    //調用 client 建立多元索引。
    client.createSearchIndex(request); 
}

建立多元索引時指定IndexSort

以下樣本用於建立一個多元索引，該多元索引包含 Col_Keyword（KEYWORD 類型）、Col_Long（LONG 類型）、Col_Text（TEXT 類型）和 Timestamp（LONG 類型）四列，同時配置按照 Timestamp 列進行預排序。

private static void createSearchIndexWithIndexSort(SyncClient client) {
    CreateSearchIndexRequest request = new CreateSearchIndexRequest();
    //設定資料表名稱。
    request.setTableName("<TABLE_NAME>"); 
    //設定多元索引名稱。
    request.setIndexName("<SEARCH_INDEX_NAME>"); 
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
            new FieldSchema("Col_Keyword", FieldType.KEYWORD),
            new FieldSchema("Col_Long", FieldType.LONG),
            new FieldSchema("Col_Text", FieldType.TEXT),
            new FieldSchema("Timestamp", FieldType.LONG)
                    .setEnableSortAndAgg(true)));
    //設定按照 Timestamp 列進行預排序。
    indexSchema.setIndexSort(new Sort(
            Arrays.<Sort.Sorter>asList(new FieldSort("Timestamp", SortOrder.ASC))));
    request.setIndexSchema(indexSchema);
    //調用 client 建立多元索引。
    client.createSearchIndex(request);
}

建立多元索引時設定生命週期

重要

請確保資料表的更新狀態為禁止。

以下樣本用於建立一個多元索引，該多元索引包含 Col_Keyword（KEYWORD 類型）和 Col_Long（LONG 類型）兩列，同時指定多元索引生命週期為 7 天。

// 請使用 5.12.0 及以上版本的 Java SDK。
public static void createIndexWithTTL(SyncClient client) {
    int days = 7;
    CreateSearchIndexRequest request = new CreateSearchIndexRequest();
    //設定資料表名稱。
    request.setTableName("<TABLE_NAME>");
    //設定多元索引名稱。
    request.setIndexName("<SEARCH_INDEX_NAME>");
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
            //設定欄位名和類型。
            new FieldSchema("Col_Keyword", FieldType.KEYWORD), 
            new FieldSchema("Col_Long", FieldType.LONG)));
    request.setIndexSchema(indexSchema);
    //設定多元索引 TTL。
    request.setTimeToLiveInDays(days);
    //調用 client 建立多元索引。
    client.createSearchIndex(request);
}

建立多元索引時指定虛擬列

以下樣本用於建立一個多元索引，該多元索引包含 Col_Keyword（KEYWORD 類型）和 Col_Long（LONG 類型）兩列，同時建立虛擬列 Col_Keyword_Virtual_Long（LONG 類型）和 Col_Long_Virtual_Keyword（KEYWORD 類型）。Col_Keyword_Virtual_Long 映射為資料表中 Col_Keyword 列，虛擬列 Col_Long_Virtual_Keyword 映射為資料表中 Col_Long 列。

private static void createSearchIndex(SyncClient client) {
    CreateSearchIndexRequest request = new CreateSearchIndexRequest();
    //設定資料表名稱。
    request.setTableName("<TABLE_NAME>"); 
    //設定多元索引名稱。
    request.setIndexName("<SEARCH_INDEX_NAME>"); 
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
        //設定欄位名和類型。
        new FieldSchema("Col_Keyword", FieldType.KEYWORD), 
        //設定欄位名和類型。
        new FieldSchema("Col_Keyword_Virtual_Long", FieldType.LONG) 
             //設定欄位是否為虛擬列。
            .setVirtualField(true) 
             //虛擬列對應的資料表中欄位。
            .setSourceFieldName("Col_Keyword"), 
        new FieldSchema("Col_Long", FieldType.LONG),
        new FieldSchema("Col_Long_Virtual_Keyword", FieldType.KEYWORD)
            .setVirtualField(true)
            .setSourceFieldName("Col_Long")));
    request.setIndexSchema(indexSchema);
    //調用 client 建立多元索引。
    client.createSearchIndex(request); 
}

建立多元索引時開啟查詢高亮

以下樣本用於建立一個多元索引，該多元索引包含Col_Keyword（KEYWORD 類型）、Col_Long（LONG 類型）和 Col_Text（TEXT 類型）三列，同時為 Col_Text 列開啟查詢高亮功能。

private static void createSearchIndexwithHighlighting(SyncClient client) {
    CreateSearchIndexRequest request = new CreateSearchIndexRequest();
    //設定資料表名稱。
    request.setTableName("<TABLE_NAME>"); 
    //設定多元索引名稱。
    request.setIndexName("<SEARCH_INDEX_NAME>"); 
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
            //設定欄位名和類型。
            new FieldSchema("Col_Keyword", FieldType.KEYWORD), 
            new FieldSchema("Col_Long", FieldType.LONG),
            //為欄位開啟查詢高亮功能。
            new FieldSchema("Col_Text", FieldType.TEXT).setIndex(true).setEnableHighlighting(true)
    ));
    request.setIndexSchema(indexSchema);
    //調用 client 建立多元索引。
    client.createSearchIndex(request); 
}

：建立多元索引