All Products
Search
Document Center

Tablestore:Specify the TTL of a search index

Last Updated:Aug 23, 2024

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

Prerequisites

Usage notes

  • Before you specify the TTL of a search index, you must disable the UpdateRow operation on the data table for which the search index is created. Otherwise, semantic issues may occur.

    The specified TTL of a data table takes effect on attribute columns, and the specified TTL of a search index takes effect on the entire rows. If a data table is updated by calling the UpdateRow operation, the values of some fields are deleted and the values of some fields are retained in the data table when Tablestore clears data 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, the data in the data table and search index is inconsistent.

    If the data table must be updated, check whether you can call the PutRow operation instead of the UpdateRow operation.

  • The TTL of a search index can be set to -1 or a positive int32. Unit: seconds. A value of -1 indicates that the data in the search index never expires. The maximum int32 value is equivalent to approximately 68 years.

  • The TTL of a search index is independent of and must be no greater than that of the data table for which the search index is created. If you need to decrease the TTL of a search index and the data table for which the search index is created, you must change the TTL of the search index before you change the TTL of the data table.

  • Tablestore automatically deletes expired data from search indexes every day. You can still query expired data in search indexes before the expired data is deleted. Tablestore automatically deletes the expired data in the next cycle.

  • After you change the TTL of data tables and search indexes, Tablestore automatically deletes the historical expired data from the data tables and search indexes in the next cycle.

Procedure

  1. Disable the UpdateRow operation on a data table.

    The following sample code shows how to disable the UpdateRow operation on a data table:

    func disableTableUpdate(client *tablestore.TableStoreClient) {
        request := &tablestore.UpdateTableRequest{
           TableName: "TableName",
           TableOption: &tablestore.TableOption{
              TimeToAlive:               -1,    // Use the default value for the TTL of a data table. The default value is -1. 
              MaxVersion:                1,     // Use the default value for max versions. The default value is 1. 
              DeviationCellVersionInSec: 86400, // Use the default value for max version offset. The default value is 86400. Unit: seconds. 
              // Disable the UpdateRow operation on a data table to ensure business continuity. If a TTL is configured for the search index of a data table, you cannot allow updates to 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 of a search index.

    After the UpdateRow operation is disabled on a data table, you can specify the TTL of a search index when you create the search index, or change the TTL of an existing search index.

    Specify the TTL when you create a search index

    The following sample code shows how to create a search index. In this example, the search index consists of two columns: the col1 column of the String type and the col2 column of the Long type. The TTL of the search index is seven days.

    func createIndexWithTTL(client *tablestore.TableStoreClient) {
        request := &tablestore.CreateSearchIndexRequest{}
        request.TableName = "<TABLE_NAME>"
        request.IndexName = "<SEARCH_INDEX_NAME>"
        schemas := []*tablestore.FieldSchema{}
        field1 := &tablestore.FieldSchema{
            FieldName:        proto.String("col1"), // Specify the column name by calling the proto.String method. This method is used to request a string pointer. 
            FieldType:        tablestore.FieldType_KEYWORD, // Specify the column type. 
            Index:            proto.Bool(true),             // Enable indexing for the column. 
            EnableSortAndAgg: proto.Bool(true),             // Enable sorting and aggregation. 
        }
        field2 := &tablestore.FieldSchema{
            FieldName:        proto.String("col2"),
            FieldType:        tablestore.FieldType_LONG,
            Index:            proto.Bool(true),
            EnableSortAndAgg: proto.Bool(true),
        }
        schemas = append(schemas, field1, field2)
        request.IndexSchema = &tablestore.IndexSchema{
            FieldSchemas: schemas, // Specify the columns that are included in the search index. 
        }
        request.TimeToLive = proto.Int32(3600 * 24 * 7) // Set the TTL of the search index to seven days. 
        resp, err := client.CreateSearchIndex(request)
        if err != nil {
           fmt.Println("error :", err)
           return
       }
        fmt.Println("createIndexWithTTL finished, requestId:", resp.ResponseInfo.RequestId)
    }

    Change the TTL of an existing search index

    The following sample code shows how to set the TTL of an existing search index to seven days:

    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 seven 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 search index is independent of that of the data table for which the search index is created. If you want to use the TTL feature for a data table, specify the TTL of the data table.

    The following sample code shows how to set the TTL of a data table to seven days:

    // Set the TTL of the data table to seven 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 seven days. 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,             // Use the default value for max versions. The default value is 1. 
                DeviationCellVersionInSec: 86400,         // Use the default value for max version offset. The default value is 86400. Unit: seconds. 
                // Disable the UpdateRow operation on a data table to ensure business continuity. If a TTL is configured for the search index of a data table, you cannot allow updates to 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)
    }

FAQ

What do I do if the [table ttl] must be bigger than or equal search index ttl error message is returned when I modify the TTL of a data table?

References

  • You can call the ListSearchIndex operation to query all search indexes that are created for a data table. For more information, see List search indexes.

  • You can call the DescribeSearchIndex operation to query the description of a search index. For example, you can query the field information and search index configurations. For more information, see Query the description of a search index.

  • You can dynamically modify the schema of a search index to add, update, or remove index columns in the search index. For more information, see Dynamically modify the schema of a search index.

  • You can delete a search index that you no longer need. For more information, see Delete search indexes.