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）：多维空间中两个向量之间的直线距离。出于性能考虑，表格存储中的欧氏距离算法未进行最后的平方根计算。欧氏距离的评分越大表示两个向量的相似度越大。余弦相似度（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); 
}

表格存储：创建多元索引