表格存储 Java SDK 检索时间线元数据-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 Java SDK 按度量名称、数据源、标签、属性或更新时间检索时间线元数据，并支持组合条件和分页读取。

前提条件

安装Tablestore Java SDK并初始化时序模型客户端。

功能说明

调用 queryTimeseriesMeta 方法检索时序表中的时间线元数据。不设置查询条件时返回全部时间线元数据；设置查询条件时，可以按一个或多个时间线特征筛选。

public QueryTimeseriesMetaResponse queryTimeseriesMeta(QueryTimeseriesMetaRequest request) throws TableStoreException, ClientException

说明

服务端会为新时间线异步构建元数据索引。写入新的时间线后，需等待索引构建完成才能检索到对应元数据。

以下示例检索 example_timeseries_table 中度量名称为 cpu、且 os 标签值以 Ubuntu 开头的时间线元数据。

CompositeMetaQueryCondition condition =
        new CompositeMetaQueryCondition(MetaQueryCompositeOperator.OP_AND);
condition.addSubCondition(new MeasurementMetaQueryCondition(
        MetaQuerySingleOperator.OP_EQUAL, "cpu"));
condition.addSubCondition(new TagMetaQueryCondition(
        MetaQuerySingleOperator.OP_PREFIX, "os", "Ubuntu"));

QueryTimeseriesMetaRequest request =
        new QueryTimeseriesMetaRequest("example_timeseries_table");
request.setCondition(condition);
request.setGetTotalHits(true);
request.setLimit(100);

QueryTimeseriesMetaResponse response =
        timeseriesClient.queryTimeseriesMeta(request);
System.out.println(response.getTotalHits());
for (TimeseriesMeta meta : response.getTimeseriesMetas()) {
    System.out.println(meta);
}

参数说明

QueryTimeseriesMetaRequest 包含以下参数。

名称	类型	说明
timeseriesTableName（必选）	`String`	时序表名称。
condition（可选）	`MetaQueryCondition`	时间线元数据检索条件。不设置时返回全部时间线元数据。
getTotalHits（可选）	`boolean`	是否返回符合条件的时间线元数据总数。默认值为 `false`。
limit（可选）	`int`	单次请求最多返回的时间线元数据条数。仅正值生效；实际返回条数可能小于该值。
nextToken（可选）	`byte[]`	分页令牌。首次请求不设置；响应中的 `nextToken` 不为 `null` 时，将其传入下一次请求。不能根据当前页为空或返回条数小于 `limit` 判断检索结束。该令牌是二进制数据，如需持久化或传输，应进行 Base64 编码。

condition 可以使用以下查询条件类型。字符串查询条件支持 OP_EQUAL、OP_GREATER_THAN、OP_GREATER_EQUAL、OP_LESS_THAN、OP_LESS_EQUAL 和 OP_PREFIX；更新时间查询条件不支持 OP_PREFIX。

组合查询条件

condition 的类型为 CompositeMetaQueryCondition 时，包含以下参数。

名称	类型	说明
operator（必选）	`MetaQueryCompositeOperator`	逻辑运算符，取值为 `OP_AND`、`OP_OR` 或 `OP_NOT`。
subConditions（必选）	`List<MetaQueryCondition>`	要组合的子条件列表，不能为空。子条件也可以是组合查询条件。

度量名称查询条件

condition 的类型为 MeasurementMetaQueryCondition 时，包含以下参数。

名称	类型	说明
operator（必选）	`MetaQuerySingleOperator`	查询运算符。
value（必选）	`String`	要匹配的度量名称。

数据源查询条件

condition 的类型为 DataSourceMetaQueryCondition 时，包含以下参数。

名称	类型	说明
operator（必选）	`MetaQuerySingleOperator`	查询运算符。
value（必选）	`String`	要匹配的数据源标识。

标签查询条件

condition 的类型为 TagMetaQueryCondition 时，包含以下参数。

名称	类型	说明
operator（必选）	`MetaQuerySingleOperator`	查询运算符。
tagName（必选）	`String`	要匹配的标签名称，不能为空。
value（必选）	`String`	要匹配的标签值。

属性查询条件

condition 的类型为 AttributeMetaQueryCondition 时，包含以下参数。

名称	类型	说明
operator（必选）	`MetaQuerySingleOperator`	查询运算符。
attributeName（必选）	`String`	要匹配的属性名称，不能为空。
value（必选）	`String`	要匹配的属性值。

更新时间查询条件

condition 的类型为 UpdateTimeMetaQueryCondition 时，包含以下参数。

名称	类型	说明
operator（必选）	`MetaQuerySingleOperator`	查询运算符，取值为 `OP_EQUAL`、`OP_GREATER_THAN`、`OP_GREATER_EQUAL`、`OP_LESS_THAN` 或 `OP_LESS_EQUAL`。
timeInUs（必选）	`long`	时间线元数据的最后更新时间，格式为从 1970-01-01 00:00:00 UTC 开始计算的微秒时间戳。

返回值

QueryTimeseriesMetaResponse 包含以下业务返回字段。

字段	类型	说明
`timeseriesMetas`	`List<TimeseriesMeta>`	通过 `getTimeseriesMetas()` 获取本次请求返回的时间线元数据。
`totalHits`	`long`	通过 `getTotalHits()` 获取符合条件的时间线元数据总数。仅当请求将 `getTotalHits` 设置为 `true` 时有效，否则为 `-1`。
`nextToken`	`byte[]`	通过 `getNextToken()` 获取下一页令牌。值为 `null` 时，表示结果已全部返回。

时间线元数据

timeseriesMetas[] 中每个元素的类型为 TimeseriesMeta，包含以下字段。

字段	类型	说明
`timeseriesKey`	`TimeseriesKey`	通过 `getTimeseriesKey()` 获取时间线标识。
`attributes`	`SortedMap<String, String>`	通过 `getAttributes()` 获取时间线元数据属性。
`updateTimeInUs`	`long`	通过 `getUpdateTimeInUs()` 获取元数据最后更新时间，单位为微秒。

时间线标识

timeseriesMetas[].timeseriesKey 的类型为 TimeseriesKey，包含以下字段。

字段	类型	说明
`measurementName`	`String`	通过 `getMeasurementName()` 获取度量名称。
`dataSource`	`String`	通过 `getDataSource()` 获取数据源标识。
`tags`	`SortedMap<String, String>`	通过 `getTags()` 获取标签信息。

场景示例

分页读取全部元数据

当响应中的 nextToken 不为 null 时，重复传入该令牌，直至全部结果返回。

List<TimeseriesMeta> allMetas = new ArrayList<>();
byte[] nextToken = null;
do {
    request.setNextToken(nextToken);
    QueryTimeseriesMetaResponse response =
            timeseriesClient.queryTimeseriesMeta(request);

    allMetas.addAll(response.getTimeseriesMetas());
    nextToken = response.getNextToken();
} while (nextToken != null);