Query time series

Prerequisites

A client is initialized. For more information, see Initialize a Tablestore client.

Class definition

QueryTimeseriesMetaRequest accepts the time series table name and an optional query condition. Use setCondition to filter results, setGetTotalHits to include a count of matching time series, and setLimit to control page size. Paginate through results using NextToken.

public class QueryTimeseriesMetaRequest implements Request {
    /** The name of the time series table. */
    private final String timeseriesTableName;
    /** The query conditions.*/
    private MetaQueryCondition condition;
    /** Specifies whether to return the total number of time series that meet the query conditions. */
    private boolean getTotalHits = false;
    /** The number of time series to return at a time. */
    private int limit = -1;
    /** The token that is used in the next request to query time series. */
    private byte[] nextToken;
}

The following classes implement MetaQueryCondition and define the supported query condition types.

public class CompositeMetaQueryCondition implements MetaQueryCondition {
    /** The logical operator. */
    private final MetaQueryCompositeOperator operator;
    /** The list of subconditions. */
    private List<MetaQueryCondition> subConditions = new ArrayList<MetaQueryCondition>();
}

public class MeasurementMetaQueryCondition implements MetaQueryCondition {
    /** The relational operator. */
    private final MetaQuerySingleOperator operator;
    /** The name of the metric of the time series that you want to query. */
    private final String value;
}

public class DataSourceMetaQueryCondition implements MetaQueryCondition {
    /** The relational operator. */
    private final MetaQuerySingleOperator operator;
     /** The name of the data source of the time series that you want to query. */
    private final String value;
}

public class TagMetaQueryCondition implements MetaQueryCondition {
    /** The relational operator. */
    private final MetaQuerySingleOperator operator;
    /** The tag name. */
    private final String tagName;
    /** The tag value. */
    private final String value;
}

public class AttributeMetaQueryCondition implements MetaQueryCondition {
    /** The relational operator. */
    private final MetaQuerySingleOperator operator;
    /** The attribute name. */
    private final String attributeName;
    /** The attribute value. */
    private final String value;
}

public class UpdateTimeMetaQueryCondition implements MetaQueryCondition {
    /** The relational operator. */
    private final MetaQuerySingleOperator operator;
    /** The timestamp when the time series metadata is updated. */
    private final long timeInUs;
}

Parameters

Specify timeseriesTableName and at least one condition. The table below describes each condition type.

Example

The following example queries all time series in a table where the metric name is cpu and the os tag value starts with Ubuntu. Results are retrieved in pages of up to 100 entries, stopping after 1,000 total results.

private static void queryTimeseriesMeta(TimeseriesClient client) {
    // Specify the name of the time series table. 
    String tableName = "<TIME_SERIES_TABLE>";
    QueryTimeseriesMetaRequest queryTimeseriesMetaRequest = new QueryTimeseriesMetaRequest(tableName);
    // Query all time series whose metric name is cpu and that have the os tag whose value is prefixed with Ubuntu. measurement_name="cpu" and have_prefix(os, "Ubuntu") 
    CompositeMetaQueryCondition compositeMetaQueryCondition = new CompositeMetaQueryCondition(MetaQueryCompositeOperator.OP_AND);
    compositeMetaQueryCondition.addSubCondition(new MeasurementMetaQueryCondition(MetaQuerySingleOperator.OP_EQUAL, "cpu"));
    compositeMetaQueryCondition.addSubCondition(new TagMetaQueryCondition(MetaQuerySingleOperator.OP_PREFIX, "os", "Ubuntu"));
    queryTimeseriesMetaRequest.setCondition(compositeMetaQueryCondition);
    queryTimeseriesMetaRequest.setGetTotalHits(true);
    // Specify the maximum number of time series metadata entries that can be returned for a single request. 
    queryTimeseriesMetaRequest.setLimit(100);
    // Initiate the query. 
    QueryTimeseriesMetaResponse queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
    // Display the total number of time series that meet the query conditions. 
    System.out.println(queryTimeseriesMetaResponse.getTotalHits());

    // Save the request results. 
    List<TimeseriesMeta> timeseriesMetas = new ArrayList<TimeseriesMeta>();
    timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());

    // If NextToken is included in the response, you can initiate a new request to obtain the remaining results. 
    while (queryTimeseriesMetaResponse.getNextToken() != null) {
        queryTimeseriesMetaRequest.setNextToken(queryTimeseriesMetaResponse.getNextToken());
        queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
        timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());
        // Specify the maximum number of time series that can be returned. 
        if (timeseriesMetas.size() >= 1000) {
            break;
        }
    }

    System.out.println(timeseriesMetas.size());
    for (TimeseriesMeta timeseriesMeta : timeseriesMetas) {
        System.out.println(timeseriesMeta.getTimeseriesKey().getMeasurementName());
        System.out.println(timeseriesMeta.getTimeseriesKey().getDataSource());
        System.out.println(timeseriesMeta.getTimeseriesKey().getTags());
        System.out.println(timeseriesMeta.getAttributes());
        System.out.println(timeseriesMeta.getUpdateTimeInUs());
    }
}

What's next

After querying time series, you can:

• Query data points within the matching time series. For more information, see Query time series data.

• Update the attributes stored in time series metadata. For more information, see Update time series metadata.

• Delete time series metadata that is no longer needed. For more information, see Delete time series metadata.