文档

通过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); 
}

常见问题

相关文档

  • 您还可以通过控制台和命令行工具使用多元索引。具体操作,请参见通过控制台使用多元索引通过命令行工具使用多元索引

  • 当通过Search接口查询数据时,如果要对结果集进行排序或者翻页,您可以使用排序和翻页功能来实现。具体操作,请参见排序和翻页

  • 当通过Search接口查询数据时,如果要按照某一列对结果集做折叠,使对应类型的数据在结果展示中只出现一次,您可以使用折叠(去重)功能来实现。具体操作,请参见折叠(去重)

  • 如果要进行全文检索,您可以对可分词类型的字段进行分词后再选择合适的查询方式来实现。具体操作,请参见分词

  • 如果要进行多层逻辑关系的数据存储和查询,您可以使用嵌套类型存储数据后再选择嵌套查询来实现。具体操作,请参见嵌套类型嵌套类型查询

  • 如果要系统自动清理多元索引中超过保存时间的数据,您可以使用多元索引生命周期功能。具体操作,请参见生命周期管理

  • 如果要在多元索引中新增、更新或者删除索引列,您可以使用动态修改schema功能实现。具体操作,请参见动态修改schema

  • 如果要在不修改数据表的存储结构和数据的情况下,对新字段新数据类型的查询,您可以使用虚拟列功能实现。具体操作,请参见虚拟列

  • 本页导读 (1)