The time to live (TTL) can be configured for search indexes. TTL is an attribute of search indexes that specifies the retention period of data in search indexes. When data in a search index is retained for a period of time that exceeds the TTL value, Tablestore automatically deletes the data to free up storage space and reduce costs.

Prerequisites

  • A TableStoreClient instance is initialized. For more information, see Initialization.
  • A data table is created.

Usage notes

  • To use the TTL feature of a search index, you must prohibit the UpdateRow operation on the data table for which the search index is created due to the following reasons:

    The TTL feature of data tables takes effect on attribute columns, and the TTL feature of search indexes takes effect on the entire rows. If the UpdateRow operation is performed on a data table, when the system clears data in the data table, the values of some fields are deleted and the values of some fields are retained in the data table. However, the entire rows in the search index that is created for the data table are not deleted. As a result, data in the data table and search index is inconsistent.

    If the UpdateRow operation is required, check whether the UpdateRow operation can be changed to the PutRow operation.

  • The TTL value of search indexes can be -1 or a positive int32 in seconds. The value of -1 indicates that data in the search index never expires and the maximum int32 value is equivalent to approximately 68 years.
  • The TTL value of a search index is independent of and must be smaller than or equal to the TTL value of the data table for which the search index is created. If you need to change TTL values of search indexes and data tables for which the search indexes are created to smaller values, you must change the TTL values of the search indexes before you change the TTL values of the data tables.
  • Tablestore automatically deletes expired data from search indexes every day. In some cases, you can still query expired data in search indexes. Tablestore automatically deletes the expired data in the next cycle.
  • After you change the TTL values of data tables and search indexes, the system automatically deletes legacy expired data from the data tables and search indexes in the next cycle.

Procedure

  1. Prohibit the UpdateRow operation on a data table. 
    func disableTableUpdate(client *tablestore.TableStoreClient) {
    request := &tablestore.UpdateTableRequest{
       TableName: "TableName",
       TableOption: &tablestore.TableOption{
          TimeToAlive:               -1,    // Retain the default value of TTL for the data table. The default value is -1. 
          MaxVersion:                1,     // Retain the default value of max versions. The default value is 1. 
          DeviationCellVersionInSec: 86400, // Retain the default value of max version offset. The default value is 86400. Unit: seconds. 
          // Prohibit the UpdateRow operation on the data table to prevent impacts on your business. You cannot allow the UpdateRow operation on a data table if TTL is configured for the search index that is created for the data table. 
          AllowUpdate: proto.Bool(false),
      },
   }
    resp, err := client.UpdateTable(request)
    if err != nil {
       fmt.Println("error :", err)
       return
   }
    fmt.Println("UpdateTable finished, requestId:", resp.ResponseInfo.RequestId)
}
  2. Specify the TTL for search indexes.

    After the UpdateRow operation on a data table is prohibited, you can specify the TTL of a search index when you create the search index or modify the TTL of existing search indexes.

    • Specify the TTL when you create a search index
      func createIndexWithTTL(client *tablestore.TableStoreClient) {
    request := &tablestore.CreateSearchIndexRequest{}
    request.TableName = "TableName"
    request.IndexName = "IndexName"
    // In this example, other parameters are not configured. Configure other parameters based on your business requirements. 
    request.TimeToLive = proto.Int32(3600 * 24 * 7) // Set the TTL of the search index to 7 days. 
    resp, err := client.CreateSearchIndex(request)
    if err != nil {
       fmt.Println("error :", err)
       return
   }
    fmt.Println("createIndexWithTTL finished, requestId:", resp.ResponseInfo.RequestId)
}
    • Modify the TTL for an existing search index
      func updateIndexWithTTL(client *tablestore.TableStoreClient) {
    request := &tablestore.UpdateSearchIndexRequest{}
    request.TableName = "TableName"
    request.IndexName = "IndexName"
    request.TimeToLive = proto.Int32(3600 * 24 * 7) // Set the TTL of the search index to 7 days. 
    resp, err := client.UpdateSearchIndex(request)
    if err != nil {
       fmt.Println("error :", err)
       return
   }
    fmt.Println("updateIndexWithTTL finished, requestId:", resp.ResponseInfo.RequestId)
}
  3. The TTL of a data table is independent of the TTL of the search index that is created for the data table. If you want to use the TTL of a data table, configure the TTL for the data table. 
    // Set the TTL of the data table to 7 days. 
func updateTableTTL(client *tablestore.TableStoreClient) {
    request := &tablestore.UpdateTableRequest{
        TableName: "TableName",
        TableOption: &tablestore.TableOption{
            TimeToAlive:               3600 * 24 * 7, // Set the TTL of the data table to 7 days and make sure that the TTL of the data table is greater than or equal to the TTL of the search index that is created for the data table. 
            MaxVersion:                1,     // Retain the default value of max versions. The default value is 1. 
            DeviationCellVersionInSec: 86400, // Retain the default value of max version offset. The default value is 86400. Unit: seconds. 
            // Prohibit the UpdateRow operation on the data table to prevent impacts on your business. You cannot allow the UpdateRow operation on a data table if TTL is configured for the search index that is created for the data table. 
            AllowUpdate: proto.Bool(false),
        },
    }
    resp, err := client.UpdateTable(request)
    if err != nil {
        fmt.Println("error :", err)
        return
    }
    fmt.Println("UpdateTable finished, requestId:", resp.ResponseInfo.RequestId)
}