All Products
Search
Document Center

Tablestore:TTL of time series data

Last Updated:Mar 29, 2024

If you want the historical data in a time series table to be automatically deleted, you can configure Time To Live (TTL) to manage time series data. This helps you save storage space and reduce storage costs. After you configure 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 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 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 TTL for data in a time series data table to 86400 (one 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.

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.

Important

The attributes of time series metadata are stored in the _attributes column. You can update the attributes of time series metadata for which the 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 (seven 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 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

  1. 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.

  2. In the lower part of the Instance Details tab, click the Time Series Tables tab.

  3. On the Time Series Tables tab, click the name of the time series table that you want to manage.

  4. In the Description section of the Basic Information tab, click the image.png icon next to Data Lifecycle.

  5. In the dialog box that appears, modify the TTL value.

    The TTL value is the retention period of the data in the time series table. Unit: seconds. The value must be -1 or a value that is greater than or equal to 86400. The value -1 indicates that the data never expires. The value 86400 indicates one day.

  6. Click Yes.

Modify the TTL of time series metadata

  1. 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.

  2. In the lower part of the Instance Details tab, click the Time Series Tables tab.

  3. On the Time Series Tables tab, click the name of the time series table that you want to manage.

  4. In the Description section of the Basic Information tab, click the image.png icon next to Timeline TTL.

  5. 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. The value -1 indicates that the metadata never expires. The value 604800 indicates seven days.

  6. 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 time series table. For more information, see the Update a time series table section of the Operations on a time series table topic.

The following sample code provides an example on how to change the TTL value specified for data in a time series table to 86400 (one 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 (three 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 (three years). 
    TimeseriesMetaOptions options = new TimeseriesMetaOptions();
    options.setMetaTimeToLive(86400 * 365 * 3);
    updateTimeseriesTableRequest.setTimeseriesMetaOptions(options);
    client.updateTimeseriesTable(updateTimeseriesTableRequest);
}

FAQ

How do I delete time series data?