retrieve time series, update the properties in time series metadata, delete time series metadata - Tablestore

In Tablestore, you can call the QueryTimeseriesMeta operation to retrieve time series based on conditions, the UpdateTimeseriesMeta operation to update time series metadata, and the DeleteTimeseriesMeta operation to delete time series metadata. After you retrieve time series, you can manage the time series metadata based on your business requirements. For example, you can delete and update time series metadata.

Overview

Before you write time series data, you can define time series metadata. If you do not define time series metadata before you write time series data, the system automatically extracts the metadata of the time series and creates an index for the metadata.

After time series metadata is generated, you can manage the time series metadata based on your business requirements. The following table describes the features that you can use to manage time series metadata.

Feature	Description
Retrieve time series	You can call the QueryTimeseriesMeta operation to retrieve time series based on the metric name, data source, tag, update time, or property, or based on a combination of multiple conditions.
Update time series metadata	You can call the UpdateTimeseriesMeta operation to update time series metadata, such as the properties in time series metadata. The properties in time series metadata are stored in the _attributes column. You can update the properties in time series metadata for which the time to live (TTL) is set to -1. The value of -1 indicates that data never expires. Note For more information, see TTL of time series data.
Delete time series metadata	You can call the DeleteTimeseriesMeta operation to delete multiple time series metadata records at a time. Important When you delete time series metadata, the data in the time series is not deleted. You can call the GetTimeseriesData operation to query data in the time series by specifying time series identifiers.

Methods

You can manage time series metadata by using the Tablestore console, Tablestore CLI, or Tablestore SDKs.

Note

The features that are supported vary based on the method that you use to manage time series metadata.

Before you manage time series metadata, make sure that the following preparations are made:

A time series table is created and time series data is written to the time series table. For more information, see Operations on a time series table and Write time series data.
If you manage time series metadata by using Tablestore SDKs, an OTSClient instance is initialized. For more information, see Initialize an OTSClient instance.
If you manage time series metadata by using the Tablestore CLI, the Tablestore CLI is downloaded and started, and information about the instance that you want to access is configured. For more information, see Download the Tablestore CLI and Start the Tablestore CLI and configure access information.

Use the Tablestore console

You can use the Tablestore console to retrieve time series or update time series metadata.

Retrieve time series

Go to the Instance Management page.
1. Log on to the Tablestore console.
2. In the top navigation bar, select a resource group and a region.
3. On the Overview page, click the name of the instance that you want to manage or click Manage Instance in the Actions column of the instance.
In the lower part of the Instance Details tab, click the Time Series Tables tab.
On the Time Series Tables tab, click the name of the time series table that you want to manage, and then click the Query Data tab. You can also click Manage Data in the Actions column of the time series table.
On the Query Data tab, click Query Data in the upper-right corner.
In the Query Data dialog box, configure the Metric Name and Data Source parameters, and click Add in the Tag, Property, and Updated At sections to add conditions.
The following figure shows an example on how to query the time series in which the metric name is cpu and the tags contain os=Ubuntu16.10.
Click OK.
The time series that meet the conditions are displayed on the Query Data tab.

Update time series metadata

Go to the Instance Management page.
1. Log on to the Tablestore console.
2. In the top navigation bar, select a resource group and a region.
3. On the Overview page, click the name of the instance that you want to manage or click Manage Instance in the Actions column of the instance.
In the lower part of the Instance Details tab, click the Time Series Tables tab.
On the Time Series Tables tab, click the name of the time series table that you want to manage, and then click the Query Data tab. You can also click Manage Data in the Actions column of the time series table.
On the Query Data tab, find the time series that you want to manage and click Update in the Actions column.
In the Update Time Series dialog box, add, delete, or modify the properties in the time series metadata.
Click OK.

Use the Tablestore CLI

You can use the Tablestore CLI to retrieve time series or update time series metadata.

Retrieve time series

You can run the query_ts_meta (abbreviation: qtm) command to retrieve time series by specifying conditions and return all or a specific number of time series. For more information, see Retrieve time series or Scan time series.

Retrieve time series by specifying conditions
The following sample code shows how to retrieve the time series in which the metric name is cpu and the data source is localhost:
```
query_ts_meta --measurement cpu --datasource localhost --limit 10
```
Scan time series and return a specific number of time series
The following sample code shows how to scan time series and return 10 time series:
```
query_ts_meta --limit 10
```

Update time series metadata

You can run the update_ts_meta (abbreviation: utm) command to update the properties in time series metadata.

The following sample code shows how to change properties in the metadata of a specific time series to "city=nanjing" and "region=jiangning":

update_ts_meta --k '["cpu","localhost",["city=hangzhou","region=xihu"]]' --attrs '["city=nanjing","region=jiangning"]'

Use Tablestore SDKs

You can use Tablestore SDK for Java and Tablestore SDK for Go to retrieve time series, update time series metadata, and delete time series metadata. In this example, Tablestore SDK for Java is used.

Retrieve time series

The following sample code provides an example on how to query all time series whose metric name is cpu and that have the os tag whose value is prefixed with Ubuntu in a time series table.

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

Update time series metadata

The following sample code provides an example on how to update the properties of the metadata of multiple time series in a time series table:

private static void updateTimeseriesMeta(TimeseriesClient client) {
    List<TimeseriesMeta> timeseriesMetaList = new ArrayList<TimeseriesMeta>();
    for (int i = 0; i < 10; i++) {
        Map<String, String> tags = new HashMap<String, String>();
        tags.put("region", "hangzhou");
        tags.put("os", "Ubuntu16.04");
        // Construct the identifiers of the time series. 
        TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_" + i, tags);
        TimeseriesMeta meta = new TimeseriesMeta(timeseriesKey);
        // Specify the values of the properties of the time series. 
        Map<String, String> attrs = new HashMap<String, String>();
        attrs.put("status", "online");
        meta.setAttributes(attrs);
        timeseriesMetaList.add(meta);
    }
    // Specify the name of the time series table. 
    String tableName = "<TIME_SERIES_TABLE>";
    UpdateTimeseriesMetaRequest updateTimeseriesMetaRequest = new UpdateTimeseriesMetaRequest(tableName);
    updateTimeseriesMetaRequest.setMetas(timeseriesMetaList);
    UpdateTimeseriesMetaResponse updateTimeseriesMetaResponse = client.updateTimeseriesMeta(updateTimeseriesMetaRequest);
    // Check whether the properties of all time series are updated. 
    if (!updateTimeseriesMetaResponse.isAllSuccess()) {
        for (UpdateTimeseriesMetaResponse.FailedRowResult failedRowResult : updateTimeseriesMetaResponse.getFailedRows()) {
            System.out.println(failedRowResult.getIndex());
            System.out.println(failedRowResult.getError());
        }
    }
}

Delete time series metadata

The following code provides an example on how to delete the metadata of some time series in a time series table.

private static void deleteTimeseriesMeta(TimeseriesClient client) {
    List<TimeseriesKey> timeseriesKeyList = new ArrayList<TimeseriesKey>();
    for (int i = 0; i < 10; i++) {
        Map<String, String> tags = new HashMap<String, String>();
        tags.put("region", "hangzhou");
        tags.put("os", "Ubuntu16.04");
        // Construct a time series identifier. 
        TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_" + i, tags);
        timeseriesKeyList.add(timeseriesKey);
    }
    // Specify the name of the time series table. 
    String tableName = "<TIME_SERIES_TABLE>";
    DeleteTimeseriesMetaRequest deleteTimeseriesMetaRequest = new DeleteTimeseriesMetaRequest(tableName);
    deleteTimeseriesMetaRequest.setTimeseriesKeys(timeseriesKeyList);
    DeleteTimeseriesMetaResponse deleteTimeseriesMetaResponse = client.deleteTimeseriesMeta(deleteTimeseriesMetaRequest);
    // Check whether the metadata of the time series is deleted. 
    if (!deleteTimeseriesMetaResponse.isAllSuccess()) {
        for (DeleteTimeseriesMetaResponse.FailedRowResult failedRowResult : deleteTimeseriesMetaResponse.getFailedRows()) {
            System.out.println(failedRowResult.getIndex());
            System.out.println(failedRowResult.getError());
        }
    }
}

FAQ

How do I delete time series data?

References

After you retrieve time series, you can query time series data that meets specific conditions in the time series. For more information, see Query time series data.
If you want to automatically delete time series metadata that you no longer need or extend the retention period of time series metadata, you can configure the TTL for time series metadata. For more information, see TTL of time series data.