表格存储 Java SDK 查询时序数据-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 Java SDK 查询指定时间线在时间范围内的时序数据，并支持按时间排序、选择返回列和分页读取。

前提条件

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

功能说明

调用 getTimeseriesData 方法，根据完整的时间线标识和时间范围查询单条时间线中的数据点。查询范围包含起始时间，不包含结束时间。

public GetTimeseriesDataResponse getTimeseriesData(GetTimeseriesDataRequest request) throws TableStoreException, ClientException

说明

通过 putTimeseriesData 写入的数据可以立即通过 getTimeseriesData 查询。

以下示例查询 example_timeseries_table 中 cpu 时间线最近一小时的数据，并限制单次最多返回 20 行。

TimeseriesClient timeseriesClient = client.asTimeseriesClient();

Map<String, String> tags = new HashMap<>();
tags.put("region", "cn-hangzhou");
tags.put("host", "host_0");
TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "source_0", tags);

long endTimeInUs = System.currentTimeMillis() * 1000L;
long beginTimeInUs = endTimeInUs - 3600L * 1000L * 1000L;
GetTimeseriesDataRequest request =
        new GetTimeseriesDataRequest("example_timeseries_table");
request.setTimeseriesKey(timeseriesKey);
request.setTimeRange(beginTimeInUs, endTimeInUs);
request.setLimit(20);

GetTimeseriesDataResponse response = timeseriesClient.getTimeseriesData(request);
for (TimeseriesRow row : response.getRows()) {
    System.out.println(row.getTimeInUs());
    System.out.println(row.getFields());
}

参数说明

GetTimeseriesDataRequest 包含以下参数。

名称	类型	说明
timeseriesTableName（必选）	`String`	时序表名称。
timeseriesKey（必选）	`TimeseriesKey`	要查询的完整时间线标识。各组成项必须与写入数据时使用的值一致。
beginTimeInUs（必选）	`long`	查询范围的起始时间，格式为从 1970-01-01 00:00:00 UTC 开始计算的微秒时间戳，取值大于等于 `0`。查询范围包含该时间。
endTimeInUs（必选）	`long`	查询范围的结束时间，格式为微秒时间戳，取值大于 `0`。查询范围不包含该时间。
limit（可选）	`int`	单次请求的最大返回行数。默认值和最大值均为 `5000`。实际返回行数可能因扫描数据量等因素小于该值，可以通过 `nextToken` 继续读取。
nextToken（可选）	`byte[]`	分页令牌。首次请求不设置；响应中的 `nextToken` 不为空时，将其传入下一次请求。该令牌是二进制数据，如需持久化或传输，应进行 Base64 编码，不能直接使用 `new String(nextToken)` 转换。
backward（可选）	`boolean`	是否按时间倒序返回数据。默认值为 `false`，表示按时间正序返回。
fieldsToGet（可选）	`List<Pair<String, ColumnType>>`	要返回的数据字段名称和类型。不设置时返回全部数据字段。指定的数据类型与实际类型不同时，该字段无法读取。

时间线标识

timeseriesKey 的类型为 TimeseriesKey，包含以下参数。

名称	类型	说明
measurementName（必选）	`String`	度量名称。写入时设置为空时，查询也使用空值。
dataSource（可选）	`String`	数据源标识。写入时设置为空时，查询也使用空值。
tags（可选）	`SortedMap<String, String>`	标签信息，由字符串类型的键值对组成。必须与写入时的标签集合一致。

返回值

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

字段	类型	说明
`rows`	`List<TimeseriesRow>`	通过 `getRows()` 获取本次请求返回的时序数据行。
`nextToken`	`byte[]`	通过 `getNextToken()` 获取下一页令牌。值为 `null` 时，表示当前查询范围内的数据已全部返回。

时序数据行

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

字段	类型	说明
`timeseriesKey`	`TimeseriesKey`	通过 `getTimeseriesKey()` 获取时间线标识。
`timeInUs`	`long`	通过 `getTimeInUs()` 获取数据点时间，单位为微秒。
`fields`	`SortedMap<String, ColumnValue>`	通过 `getFields()` 获取数据字段。

场景示例

分页读取全部数据

当一次请求未返回全部数据时，重复传入响应中的 nextToken，直至返回值为 null。

byte[] nextToken = null;
do {
    request.setNextToken(nextToken);
    GetTimeseriesDataResponse response =
            timeseriesClient.getTimeseriesData(request);

    for (TimeseriesRow row : response.getRows()) {
        System.out.println(row.getTimeInUs());
        System.out.println(row.getFields());
    }
    nextToken = response.getNextToken();
} while (nextToken != null);