Query time series metadata - Tablestore SDK for Java - Tablestore

Use Tablestore SDK for Java to query time series metadata by measurement name, data source, tag, attribute, or update time, combine conditions, and paginate the results.

Prerequisites

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

Description

Call queryTimeseriesMeta to query time series metadata in a time series table. If you do not specify a condition, all time series metadata is returned. If you specify a condition, metadata is filtered by one or more time series characteristics.

public QueryTimeseriesMetaResponse queryTimeseriesMeta(QueryTimeseriesMetaRequest request) throws TableStoreException, ClientException

Note

The server asynchronously builds metadata indexes for new time series. After you write a new time series, wait for the index to be built before you query its metadata.

The following example queries metadata of time series whose measurement name is cpu and whose os tag value starts with Ubuntu in example_timeseries_table.

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

Parameters

QueryTimeseriesMetaRequest contains the following parameters.

Name	Type	Description
timeseriesTableName (required)	`String`	The time series table name.
condition (optional)	`MetaQueryCondition`	The condition used to query time series metadata. If this parameter is not specified, all time series metadata is returned.
getTotalHits (optional)	`boolean`	Specifies whether to return the total number of matching time series metadata entries. Default: `false`.
limit (optional)	`int`	The maximum number of time series metadata entries to return in a request. Only positive values take effect. The actual number of entries returned may be less than this value.
nextToken (optional)	`byte[]`	The pagination token. Do not specify this parameter in the first request. If `nextToken` in the response is not `null`, pass it to the next request. Do not determine that the query is complete based on an empty page or a page that contains fewer entries than `limit`. To persist or transfer the binary token, encode it in Base64.

condition can be set to one of the following condition types. String conditions support OP_EQUAL, OP_GREATER_THAN, OP_GREATER_EQUAL, OP_LESS_THAN, OP_LESS_EQUAL, and OP_PREFIX. Update-time conditions do not support OP_PREFIX.

Composite condition

If condition is of the CompositeMetaQueryCondition type, it contains the following parameters.

Name	Type	Description
operator (required)	`MetaQueryCompositeOperator`	The logical operator. Valid values: `OP_AND`, `OP_OR`, and `OP_NOT`.
subConditions (required)	`List<MetaQueryCondition>`	The non-empty list of conditions to combine. A subcondition can also be a composite condition.

Measurement-name condition

If condition is of the MeasurementMetaQueryCondition type, it contains the following parameters.

Name	Type	Description
operator (required)	`MetaQuerySingleOperator`	The query operator.
value (required)	`String`	The measurement name to match.

Data-source condition

If condition is of the DataSourceMetaQueryCondition type, it contains the following parameters.

Name	Type	Description
operator (required)	`MetaQuerySingleOperator`	The query operator.
value (required)	`String`	The data source identifier to match.

Tag condition

If condition is of the TagMetaQueryCondition type, it contains the following parameters.

Name	Type	Description
operator (required)	`MetaQuerySingleOperator`	The query operator.
tagName (required)	`String`	The non-empty tag name to match.
value (required)	`String`	The tag value to match.

Attribute condition

If condition is of the AttributeMetaQueryCondition type, it contains the following parameters.

Name	Type	Description
operator (required)	`MetaQuerySingleOperator`	The query operator.
attributeName (required)	`String`	The non-empty attribute name to match.
value (required)	`String`	The attribute value to match.

Update-time condition

If condition is of the UpdateTimeMetaQueryCondition type, it contains the following parameters.

Name	Type	Description
operator (required)	`MetaQuerySingleOperator`	The query operator. Valid values: `OP_EQUAL`, `OP_GREATER_THAN`, `OP_GREATER_EQUAL`, `OP_LESS_THAN`, and `OP_LESS_EQUAL`.
timeInUs (required)	`long`	The last update time of the metadata, in microseconds since 1970-01-01 00:00:00 UTC.

Response

QueryTimeseriesMetaResponse contains the following operation-specific fields.

Field	Type	Description
`timeseriesMetas`	`List<TimeseriesMeta>`	Call `getTimeseriesMetas()` to obtain the time series metadata returned by the current request.
`totalHits`	`long`	Call `getTotalHits()` to obtain the total number of matching time series metadata entries. The field is valid only if `getTotalHits` is set to `true` in the request. Otherwise, the value is `-1`.
`nextToken`	`byte[]`	Call `getNextToken()` to obtain the token for the next page. A value of `null` indicates that all results are returned.

Time series metadata

Each element in timeseriesMetas[] is of the TimeseriesMeta type and contains the following fields.

Field	Type	Description
`timeseriesKey`	`TimeseriesKey`	Call `getTimeseriesKey()` to obtain the time series identifiers.
`attributes`	`SortedMap<String, String>`	Call `getAttributes()` to obtain the metadata attributes.
`updateTimeInUs`	`long`	Call `getUpdateTimeInUs()` to obtain the last update time of the metadata in microseconds.

Time series identifiers

timeseriesMetas[].timeseriesKey is of the TimeseriesKey type and contains the following fields.

Field	Type	Description
`measurementName`	`String`	Call `getMeasurementName()` to obtain the measurement name.
`dataSource`	`String`	Call `getDataSource()` to obtain the data source identifier.
`tags`	`SortedMap<String, String>`	Call `getTags()` to obtain the tags.

Examples

Paginate all metadata

If nextToken in the response is not null, repeatedly pass the token until all results are returned.

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