通过SDK使用多元索引查询与分析数据 - 表格存储

如果实际业务中要用到非主键列查询、多条件组合查询等多种查询功能，您可以通过控制台为数据表创建多元索引，然后使用多元索引查询与分析数据。

前提条件

已创建数据表，且数据表的最大版本数（max Versions）必须为1，数据生命周期（Time to Live）必须满足如下条件中的任意一个。具体操作，请参见数据表操作。
- 数据表的数据生命周期为-1（数据永不过期）。
- 数据表的数据生命周期不为-1时，数据表为禁止更新状态（即是否允许更新为否）。
已初始化Client。具体操作，请参见初始化OTSClient。

注意事项

创建多元索引时，多元索引中字段的数据类型必须与数据表中字段的数据类型相匹配。更多信息，请参见数据类型映射。
如果要修改为指定数据生命周期（即取值不为-1），则您必须禁用数据表的UpdateRow更新写入功能。同时多元索引的TTL值必须小于或等于数据表的TTL值。更多信息，请参见生命周期管理。

使用SDK

您可以使用如下语言的SDK实现时序模型功能。本文以Java SDK为例介绍多元索引的使用。

步骤一：创建多元索引

创建多元索引用于加速数据查询。创建多元索引时，您需要将要查询的字段添加到多元索引中，您还可以配置多元索引的数据生命周期、预排序等高级选项。

创建多元索引时使用默认配置

以下示例用于创建一个多元索引，多元索引包含Col_Keyword和Col_Long两列，类型分别设置为字符串（String）和整型（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_Long", FieldType.LONG)));
    request.setIndexSchema(indexSchema);
    //调用client创建多元索引。
    client.createSearchIndex(request); 
}

创建多元索引时指定预排序

以下示例用于创建一个多元索引，多元索引包含Col_Keyword、Col_Long、Col_Text和Timestamp四列，类型分别设置为字符串（String）、整型（Long）、分词字符串（TEXT）和整型（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);
}

创建多元索引时配置生命周期

重要

多元索引数据生命周期功能与数据表的UpdateRow操作互斥。使用多元索引数据生命周期前，请确保已设置数据表的是否允许更新为否。

以下示例用于创建一个多元索引，多元索引包含Col_Keyword和Col_Long两列，类型分别设置为字符串（String）和整型（Long）。同时指定多元索引生命周期为7天。

// 请使用5.12.0及以上版本的Java SDK。
public static void createIndexWithTTL(SyncClient client) {
    int days = 7;
    CreateSearchIndexRequest createRequest = new CreateSearchIndexRequest();
    //设置数据表名称。
    createRequest.setTableName("<TABLE_NAME>");
    //设置多元索引名称。
    createRequest.setIndexName("<SEARCH_INDEX_NAME>");
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
            //设置字段名和类型。
            new FieldSchema("Col_Keyword", FieldType.KEYWORD), 
            new FieldSchema("Col_Long", FieldType.LONG)));
    createRequest.setIndexSchema(indexSchema);
    //设置多元索引TTL。
    createRequest.setTimeToLiveInDays(days);
    //调用client创建多元索引。
    client.createSearchIndex(createRequest);
}

步骤二：使用多元索引查询数据

使用多元索引查询数据时，请根据实际查询场景选择合适的查询类型。查询数据时支持配置要返回的列以及返回数据的排序方式。

多元索引支持通过SDK使用的查询类型包括全匹配查询、精确查询、范围查询、前缀查询、匹配查询、通配符查询、短语匹配查询、列存在性查询、多词精确查询、多条件组合查询、地理位置查询（只能对地理位置字段使用）和嵌套类型查询（只能对嵌套类型字段使用）。其中地理位置查询包括地理距离查询、地理长方形范围查询和地理多边形范围查询三种方式。

查询类型	Query	描述
全匹配查询	MatchAllQuery	常用于查询表中数据总行数，或者随机返回几条数据。
精确查询	TermQuery	采用完整精确匹配的方式查询表中的数据，类似于字符串匹配。对于分词字符串（Text）类型，当分词后的多个词只要有词可以精确匹配时，则表示行数据满足查询条件。
范围查询	RangeQuery	根据范围条件查询表中的数据。对于分词字符串（Text）类型，当分词后的多个词只要有词满足范围条件时，则表示行数据满足查询条件。
前缀查询	PrefixQuery	根据前缀条件查询表中的数据。对于分词字符串（Text）类型，当分词后的多个词只要有词满足前缀条件时，则表示行数据满足查询条件。
匹配查询	MatchQuery	采用近似匹配的方式查询表中的数据。会先对query内容按照配置好的分词器做切分，然后按照切分好后的词去查询。不同分词之间的关系是Or，当分词后的多个词只要有部分匹配时，则表示行数据满足查询条件。
通配符查询	WildcardQuery	要匹配的值可以是一个带有通配符的字符串。要匹配的值中可以用星号（“*”）代表任意字符序列，或者用问号（“?”）代表任意单个字符。
短语匹配查询	MatchPhraseQuery	类似于MatchQuery，但是只有当分词后的多个词必须在行数据中以同样的顺序和位置存在时，才表示行数据满足查询条件。
列存在性查询	ExistQuery	也叫NULL查询或者空值查询。一般用于稀疏数据中，用于判断某一行的某一列是否存在。例如查询所有数据中，address列不为空的行有哪些。只有当某一列在行数据中不存在或者为空数组（"[]"）时，则表示在行数据中该列不存在。
多词精确查询	TermsQuery	类似于TermQuery，但是可以一次指定多个词，当多个词中只要有一个词匹配，则表示行数据满足查询条件。
多条件组合查询	BoolQuery	查询条件可以包含一个或者多个子查询条件，根据子查询条件是否满足来判断一行数据是否满足查询条件。子查询条件的组合关系支持And、Or、Not等。
地理距离查询	GeoDistanceQuery	根据一个中心点和距离条件查询表中的数据，当一个地理位置点到指定的中心点的距离不超过指定的值时，则表示行数据满足查询条件。
地理长方形范围查询	GeoBoundingBoxQuery	根据一个长方形范围的地理位置边界条件查询表中的数据，当一个地理位置点落在给出的长方形范围内时，则表示行数据满足查询条件。
地理多边形范围查询	GeoPolygonQuery	根据一个多边形范围条件查询表中的数据，当一个地理位置点落在指定的多边形范围内时，则表示行数据满足查询条件。
嵌套查询	NestedQuery	查询嵌套类型中子文档的数据。

步骤三：使用多元索引分析数据

如果要进行数据分析，例如求最值、求和、统计行数、按字段值分组等，您可以使用Search接口的统计聚合功能来实现。具体操作，请参见统计聚合。

步骤四：使用多元索引导出数据

如果要快速导出数据，而不关心整个结果集的顺序时，您可以使用ParallelScan接口和ComputeSplits接口实现多并发导出数据。具体操作，请参见并发导出数据。

附录：管理多元索引

创建多元索引后，请根据需要执行相应操作。

查询多元索引描述信息

以下示例用于获取多元索引的详细信息，例如数据生命周期、创建时间、同步状态、字段信息等。

private static DescribeSearchIndexResponse describeSearchIndex(SyncClient client) {
    DescribeSearchIndexRequest request = new DescribeSearchIndexRequest();
    //设置数据表名称。
    request.setTableName("<TABLE_NAME>"); 
    //设置多元索引名称。
    request.setIndexName("<INDEX_NAME>"); 
    DescribeSearchIndexResponse response = client.describeSearchIndex(request);
    //打印response的详细信息。
    System.out.println(response.jsonize()); 
    //打印多元索引数据同步状态。
    System.out.println(response.getSyncStat().getSyncPhase().name());
    return response;
}

列出多元索引列表

以下示例用于列出指定表的多元索引列表。

private static List<SearchIndexInfo> listSearchIndex(SyncClient client) {
    ListSearchIndexRequest request = new ListSearchIndexRequest();
    //设置数据表名称。
    request.setTableName("<TABLE_NAME>"); 
    //获取数据表关联的所有多元索引。
    return client.listSearchIndex(request).getIndexInfos();
}

修改多元索引生命周期

// 请使用5.12.0及以上版本的Java SDK。
public void updateIndexWithTTL(SyncClient client) {
    int days = 7;
    UpdateSearchIndexRequest updateSearchIndexRequest = new UpdateSearchIndexRequest(tableName, indexName);
    // 更新多元索引TTL。
    updateSearchIndexRequest.setTimeToLiveInDays(days);
    client.updateSearchIndex(updateSearchIndexRequest);
}

删除多元索引

以下示例用于删除指定表下的某个多元索引。

private static void deleteSearchIndex(SyncClient client) {
    DeleteSearchIndexRequest request = new DeleteSearchIndexRequest();
    //设置数据表名称。
    request.setTableName("<TABLE_NAME>"); 
    //设置多元索引名称。
    request.setIndexName("<INDEX_NAME>"); 
    //调用client删除多元索引。
    client.deleteSearchIndex(request); 
}

表格存储：通过SDK使用多元索引