Query time series data - Tablestore SDK for Java - Tablestore

Use Tablestore SDK for Java to query data in a time range from a time series, sort the data by time, select fields to return, and paginate the results.

Prerequisites

Install the Tablestore SDK for Java and initialize a time series client.

Description

Call getTimeseriesData to query data points from a single time series by specifying the complete time series identifiers and a time range. The time range includes the start time and excludes the end time.

public GetTimeseriesDataResponse getTimeseriesData(GetTimeseriesDataRequest request) throws TableStoreException, ClientException

Note

Data written by calling putTimeseriesData can be immediately queried by calling getTimeseriesData.

The following example queries data generated within the last hour from the cpu time series in example_timeseries_table and returns up to 20 rows in a request.

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());
}

Parameters

GetTimeseriesDataRequest contains the following parameters.

Name	Type	Description
timeseriesTableName (required)	`String`	The time series table name.
timeseriesKey (required)	`TimeseriesKey`	The complete identifiers of the time series to query. The values must be the same as those used to write the data.
beginTimeInUs (required)	`long`	The start time of the query range, in microseconds since 1970-01-01 00:00:00 UTC. The value must be greater than or equal to `0`. The query range includes this time.
endTimeInUs (required)	`long`	The end time of the query range, in microseconds. The value must be greater than `0`. The query range excludes this time.
limit (optional)	`int`	The maximum number of rows to return in a request. Default and maximum value: `5000`. The actual number of rows may be less than this value due to limits on the amount of scanned data. Use `nextToken` to retrieve the remaining data.
nextToken (optional)	`byte[]`	The pagination token. Do not specify this parameter in the first request. If `nextToken` in the response is not empty, pass it to the next request. The token is binary data. To persist or transfer it, encode it in Base64. Do not convert it by calling `new String(nextToken)`.
backward (optional)	`boolean`	Specifies whether to return data in reverse chronological order. Default: `false`, which returns data in chronological order.
fieldsToGet (optional)	`List<Pair<String, ColumnType>>`	The names and types of data fields to return. If this parameter is not specified, all data fields are returned. A field cannot be read if the specified data type differs from the actual data type.

Time series identifiers

timeseriesKey is of the TimeseriesKey type and contains the following parameters.

Name	Type	Description
measurementName (required)	`String`	The measurement name. If an empty value was used to write the data, use an empty value in the query.
dataSource (optional)	`String`	The data source identifier. If an empty value was used to write the data, use an empty value in the query.
tags (optional)	`SortedMap<String, String>`	The tags as string key-value pairs. The tag set must be the same as the set used to write the data.

Response

GetTimeseriesDataResponse contains the following operation-specific fields.

Field	Type	Description
`rows`	`List<TimeseriesRow>`	Call `getRows()` to obtain the rows returned by the current request.
`nextToken`	`byte[]`	Call `getNextToken()` to obtain the token for the next page. A value of `null` indicates that all data in the query range is returned.

Time series data rows

Each element in rows[] is of the TimeseriesRow type and contains the following fields.

Field	Type	Description
`timeseriesKey`	`TimeseriesKey`	Call `getTimeseriesKey()` to obtain the time series identifiers.
`timeInUs`	`long`	Call `getTimeInUs()` to obtain the data point timestamp in microseconds.
`fields`	`SortedMap<String, ColumnValue>`	Call `getFields()` to obtain the data fields.

Examples

Paginate all results

If a request does not return all data, repeatedly pass nextToken from the response until the returned value is 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);