Manage time series data by configuring TTL - Tablestore - Alibaba Cloud Documentation Center

If you want the historical data in a time series table to be automatically deleted, you can configure the time to live (TTL) to manage time series data. This helps you save storage space and reduce storage costs. After you configure the TTL for time series data, you can modify the TTL to extend the data retention period.

Usage notes

The data cannot be recovered after it is deleted. Proceed with caution.
If you need to back up historical data before you configure the TTL to automatically delete the data, you can use the Data Integration service of DataWorks to export time series data to Object Storage Service (OSS). For more information, see Overview.
Before you modify the TTL, you can call the DescribeTimeseriesTable operation to view the TTL of time series data.

TTL

In the TimeSeries model, data consists of the time series metadata and the data of time series tables. The time series metadata is stored in time series metadata tables and the data of time series tables is stored in time series data tables. Tablestore allows you to manage the time series metadata and the data of time series tables by configuring the TTL for the data.

TTL of data in a time series table

As an attribute of a time series data table, the TTL indicates the retention period of data in the time series table. The TTL of data is specified in seconds. When data in the time series table is retained for a period of time that exceeds the specified TTL value, Tablestore automatically deletes the data in asynchronous mode.

For example, you set the TTL for data in a time series data table to 86400 (1 day). At 00:00:00 UTC+8 on July 21, 2016, the data that was written to the table before 00:00:00 UTC+8 on July 20, 2016 expires. Tablestore automatically deletes the expired data in asynchronous mode.

If you do not specify a TTL value when you create a time series table, the default value -1 is used, which indicates that the data in the time series table never expires. You can also specify a custom TTL value. After a time series table is created, you can call the UpdateTimeseriesTable operation to modify the TTL of data.

If data is retained for a period of time that exceeds the TTL value, the data becomes invalid and you cannot query the data even if the data is not deleted by Tablestore.

When you decrease the TTL value, the retention period of some data in the time series table may exceed the new TTL value. Tablestore asynchronously deletes the expired data.
When you increase the TTL value, you can query the data in the time series table if Tablestore does not delete the data in the table and the data is retained for a period of time that is within the new TTL value.

TTL of time series metadata

As an attribute of a time series metadata table, the TTL indicates the retention period of time series metadata. The TTL of the metadata is specified in seconds. When time series metadata is retained for a period of time that exceeds the specified TTL value, Tablestore automatically deletes the metadata in asynchronous mode. The data in time series tables is not deleted.

Important

If the metadata of a time series expires and the data of the time series does not expire, you can call the GetTimeseriesData operation to query the data in the time series table by specifying the time series identifier.

Important

The attributes of time series metadata are stored in the _attributes column. You can update the attributes of time series metadata whose TTL is set to -1. The value -1 indicates that the metadata never expires.

If you want to change the TTL of time series metadata from -1 to a value that is greater than or equal to 604800 (7 days), make sure that you do not need to update the attributes of the time series metadata. In addition, you need to set Whether to Update Attributes of Time Series Metadata to No.

If you set Whether to Update Attributes of Time Series Metadata to Yes, you must set TTL of Time Series Metadata to -1.

If time series metadata is retained for a period of time that exceeds the TTL value, the metadata becomes invalid and you cannot query the metadata even if the metadata is not deleted by Tablestore.

When you decrease the TTL value, the retention period of some time series metadata in the time series metadata table may exceed the new TTL value. Tablestore asynchronously deletes the expired metadata.
When you increase the TTL value, you can query the time series metadata if Tablestore does not delete the metadata and the metadata is retained for a period of time that is within the new TTL value.

Methods

When you create a time series table, you can configure the TTL for the data in the table. You can also modify the TTL after you create a time series table. This topic provides an example on how to modify the TTL after you create a time series table. You can modify the TTL by using the Tablestore console, CLI, or SDKs.

Note

For more information about how to configure TTL when you create a data table, see Operations on a time series table.
The features that are supported vary based on the method that you use to modify the TTL.

Use the Tablestore console

You can use the Tablestore console to modify the TTL of time series metadata or data in a time series table.

Modify the TTL of data in a time series table

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.
In the Description section of the Basic Information tab, click the icon next to Data Lifecycle.
In the dialog box that appears, modify the TTL value.
The TTL value is the retention period of data in the time series table. Unit: seconds. The value must be -1 or a value that is greater than or equal to 86400. A value of -1 specifies that the data never expires. A value of 86400 specifies 1 day.
Click Yes.

Modify the TTL of 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.
In the Description section of the Basic Information tab, click the icon next to Data Lifecycle.
In the dialog box that appears, modify the TTL value.
The TTL value is the retention period of the time series metadata in the time series metadata table. Unit: seconds. The value must be -1 or a value that is greater than or equal to 604800. A value of -1 specifies that the metadata never expires. A value of 604800 specifies 7 days.
Click Yes.

Use the Tablestore CLI

You can use the Tablestore CLI to modify the TTL of data in a time series table.

Run the alter command to update the configurations of a table. For more information, see Update a time series table.

The following sample code provides an example on how to change the TTL of data in the time series table to 86400 (1 day):

alter --ttl 86400 --ts

Use Tablestore SDKs

You can use Tablestore SDKs to modify the TTL of time series metadata or data in a time series table.

Modify the TTL of data in a time series table

The following sample code provides an example on how to change the TTL of the data in a time series table to three years.

private static void updateTimeseriesTable(TimeseriesClient client) {
    // Specify the name of the time series table. 
    String tableName = "<TIMESERIES_TABLE>";
    UpdateTimeseriesTableRequest updateTimeseriesTableRequest = new UpdateTimeseriesTableRequest(tableName);
    // Change the TTL to three years. 
    updateTimeseriesTableRequest.setTimeseriesTableOptions(new TimeseriesTableOptions(86400 * 365 * 3)); 
    client.updateTimeseriesTable(updateTimeseriesTableRequest);

    DescribeTimeseriesTableResponse describeTimeseriesTableResponse = client.describeTimeseriesTable(new DescribeTimeseriesTableRequest(tableName));
    TimeseriesTableMeta tableMeta = describeTimeseriesTableResponse.getTimeseriesTableMeta();
    // View the modified TTL. 
    System.out.println(tableMeta.getTimeseriesTableOptions().getTimeToLive()); 
}

Modify the TTL of time series metadata

The following sample code provides an example on how to change the TTL value specified for time series metadata in a time series table to 94608000 (3 years):

private static void updateTimeseriesMetaTableTTL(TimeseriesClient client) {
    // Specify the name of the time series table. 
    String tableName = "<TIMESERIES_TABLE>";
    UpdateTimeseriesTableRequest updateTimeseriesTableRequest = new UpdateTimeseriesTableRequest(tableName);
    // Change the TTL value to 94608000 (3 years). 
    TimeseriesMetaOptions options = new TimeseriesMetaOptions();
    options.setMetaTimeToLive(86400 * 365 * 3);
    updateTimeseriesTableRequest.setTimeseriesMetaOptions(options);
    client.updateTimeseriesTable(updateTimeseriesTableRequest);
}

FAQ

How do I delete time series data?