All Products
Search

This Product

    Tablestore:Retrieve time series

    Document Center

    Tablestore:Retrieve time series

    Last Updated:Apr 22, 2025

    You can retrieve time series that meet specific conditions by calling the QueryTimeseriesMeta operation.

    Prerequisites

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

    Parameters

    Parameter

    Description

    timeseriesTableName (required)

    The name of the time series table.

    condition (optional)

    The query condition for retrieving time series. The following combinations of conditions are supported.

    • CompositeMetaQueryCondition: the composite conditions, which consist of the following items:

      • operator: the logical operator. Valid values: OP_AND, OP_OR, and OP_NOT.

      • sub_conditions: the list of subconditions that are combined by using the operator to form complex query conditions.

    • MeasurementMetaQueryCondition: the metric name condition.

      • operator: the relational operator or prefix match condition (OP_PREFIX). The relational operator can be OP_EQUAL, OP_NOT_EQUAL, OP_GREATER_THAN, OP_GREATER_EQUAL, OP_LESS_THAN, or OP_LESS_EQUAL.

      • value: the name of the metric of the time series that you want to query. Type: String.

    • DataSourceMetaQueryCondition: the data source condition.

      • operator: the relational operator or prefix match condition (OP_PREFIX). The relational operator can be OP_EQUAL, OP_NOT_EQUAL, OP_GREATER_THAN, OP_GREATER_EQUAL, OP_LESS_THAN, or OP_LESS_EQUAL.

      • value: the name of the data source of the time series that you want to query. Type: String.

    • TagMetaQueryCondition: the tag condition.

      • operator: the relational operator or prefix match condition (OP_PREFIX). The relational operator can be OP_EQUAL, OP_NOT_EQUAL, OP_GREATER_THAN, OP_GREATER_EQUAL, OP_LESS_THAN, or OP_LESS_EQUAL.

      • tag_name: the name of the tag of the time series that you want to query. Type: String.

      • value: the value of the tag of the time series that you want to query. Type: String.

    • UpdateTimeMetaQueryCondition: the update time condition for time series metadata.

      • operator: the relational operator. Valid values: OP_EQUAL, OP_NOT_EQUAL, OP_GREATER_THAN, OP_GREATER_EQUAL, OP_LESS_THAN, OP_LESS_EQUAL.

      • time_in_us: the timestamp of the update time for time series metadata. Type: Integer. Unit: microseconds.

    • AttributeMetaQueryCondition: the attribute condition for time series metadata.

      • operator: the relational operator or prefix match condition (OP_PREFIX). The relational operator can be OP_EQUAL, OP_NOT_EQUAL, OP_GREATER_THAN, OP_GREATER_EQUAL, OP_LESS_THAN, or OP_LESS_EQUAL.

      • attribute_name: the name of the attribute. Type: String.

      • value: the value of the attribute. Type: String.

    getTotalHits (optional)

    Specifies whether to return the total number of rows that meet the specified retrieval condition. Default value: False.

    limit (optional)

    The maximum number of rows that you want to return for this request. Default value: 100. Valid values: (0,1000].

    Note

    The limit parameter limits only the maximum number of rows that you want to return. Even if the number of rows that meet the specified conditions exceeds the limit, the number of rows that are returned may be less than the value of the limit parameter due to other limits such as the maximum amount of data for a scan. In this case, you can obtain the remaining rows by using the nextToken parameter.

    nextToken (optional)

    If only some rows that meet the specified conditions are returned in a query, the response contains the nextToken parameter. You can specify the nextToken parameter in the next request to obtain the remaining rows.

    Important

    If you want to persist nextToken or transfer nextToken to the frontend page, you can use Base64 to encode nextToken into a string. nextToken itself is not a string. If you directly use str(nextToken) to encode the token as a string, the token information will be lost.

    Example

    The following sample code provides an example on how to retrieve time series that meet specified conditions in a time series table:

    try:
    # Query condition: All time series with metric name "cpu" and a tag named "os" with a prefix of "Ubuntu". 
    # This is equivalent to measurement_name="cpu" and have_prefix(os, "Ubuntu").
    measCond = MeasurementMetaQueryCondition(MetaQuerySingleOperator.OP_EQUAL, "cpu")
    tagCond = TagMetaQueryCondition(MetaQuerySingleOperator.OP_PREFIX, "os", "Ubuntu")
    condition = CompositeMetaQueryCondition(MetaQueryCompositeOperator.OP_AND, [measCond, tagCond])

    request = QueryTimeseriesMetaRequest("", condition)
    # Call the operation to retrieve time series.
    response = ots_client.query_timeseries_meta(request)
    print("query timeseries metas succeeded. ")
    for timeseriesMeta in response.timeseriesMetas:
        print("data_source: %s, measurement_name: %s, tags: %s, attributes : %s, update_time_in_us: %s." % (
        timeseriesMeta.timeseries_key.data_source, timeseriesMeta.timeseries_key.measurement_name,
        timeseriesMeta.timeseries_key.tags,
        timeseriesMeta.attributes, timeseriesMeta.update_time_in_us))
except Exception as e:
    # If an exception is thrown, the query fails. Handle the exception.
    print("query timeseries meta failed. %s" % e)