This topic describes max versions and time to live (TTL) of Tablestore to help you manage data.

Version number

A new version is generated for each update of a value in an attribute column. The version value uses a timestamp as the version number. When you write data to an attribute column, you can specify that Tablestore automatically generates the version number or you can define the version number.
  • The version number is calculated based on the number of milliseconds that have elapsed since 00:00:00 UTC on January 1, 1970.
  • When you choose to specify the version number, ensure that the version number is a 64-bit timestamp accurate to the millisecond within the valid version range.

Version numbers are in milliseconds. When you compare version numbers with the TTL value and calculate the max version offset value in seconds, you must divide the version number by 1000.

Version numbers are used to implement the following features:

  • TTL

    The TTL value of data in a table is specified based on version numbers. When the written data is retained for a period of time that exceeds the TTL value, Tablestore automatically deletes the data of the corresponding version numbers.

    Example: The version number of data in an attribute column is 1468944000000, which is calculated based on the time of 00:00:00 UTC on July 20, 2016. When you set TTL to 86400 (one day), the data of that version expires at 00:00:00 UTC on July 21, 2016. Tablestore automatically deletes the data after the data expires.

  • Specify the versions of data to read from each attribute column in a row

    When Tablestore reads a row of data, you can specify the maximum number of versions or the range of version numbers to read from each attribute column.

Max versions

The max versions value indicates the maximum number of versions that can be retained for the data in an attribute column. When the number of versions of data in attribute columns exceeds the max versions value, Tablestore automatically deletes data of earlier versions.

When you create a table, you can customize the maximum number of versions that can be retained for the data in an attribute column. After the table is created, you can call the UpdateTable operation to dynamically modify the max versions value for the table.
Note If the number of actual versions exceeds the specified max versions value, data of earlier versions becomes invalid. You cannot read the data even if Tablestore has not deleted the data.
  • When you decrease the max versions value, Tablestore asynchronously deletes data of earlier versions if the number of actual data versions exceeds the latest max versions value.
  • When you increase the max versions value, you can read data of the corresponding versions if Tablestore has not deleted the data of these versions and these versions are within the latest version range.

Max version offset

Data written to a table expires when the difference between the specified timestamp and current time exceeds the TTL value specified for the table. To address this problem, Tablestore allows you to configure the max version offset feature.

Max version offset specifies the maximum difference between the specified version number and current system time in seconds. The max version offset is a positive integer that can be greater than the seconds that have elapsed since 00:00:00 UTC on January 1, 1970.

To ensure that data is written, Tablestore checks the version number of the data when the data is written to the attribute column. The valid version range of an attribute column: [Data written time - Valid version offset, Data written time + Valid version offset). The data can be written only when its version number in milliseconds is converted to seconds by dividing by 1000 and the version number in seconds is within the max version offset range.

Example: The max version offset of data in each attribute column for a table is set to 86400 seconds (one day). At 00:00:00 UTC on July 21, 2016, only data whose versions range between 1468944000000 (00:00:00 UTC on July 20, 2016) and 1469116800000 (00:00:00 UTC on July 22, 2016) can be written. When you write data whose version number is 1468943999000, which is the result converted from 23:59:59 UTC July 19, 2016, 23:59:59 UTC, the data fails to write.

When you create a table, Tablestore uses default value 86400 if you do not specify max version offset. After the table is created, you can call the UpdateTable operation to dynamically modify the max version offset value.

TTL

TTL is a table attribute measured in seconds. This attribute indicates the validity period of data. When the written data is retained for a period of time that exceeds the TTL value, Tablestore automatically deletes the data to reduce storage space and costs.

Example: The TTL of data in each attribute column for a table is set to 86400 seconds (one day). At 00:00:00 UTC on July 21, 2016, data whose version numbers are smaller than 1468944000000 (00:00:00 UTC on July 20, 2016) expires. Tablestore automatically deletes the data of the version numbers after the data expires.

When you create a table, you can set TTL to -1 if you expect that data never expires. After the table is created, you can call the UpdateTable operation to dynamically modify the TTL value.
Note When the written data is retained for a period of time that exceeds the TTL value, the data becomes invalid. You cannot read the data even if Tablestore has not deleted the data.
  • When you decrease the TTL value, Tablestore asynchronously deletes data that is retained for a period of time that exceeds the latest TTL value.
  • When you increase the TTL value, you can read data of the corresponding versions if Tablestore has not deleted the data of these versions and these versions are retained for a period of time that is within the latest TTL value.