You can use data versions and time to live (TTL) to manage data in an efficient manner and minimize storage usage and storage costs.

Version number

When you update a value in an attribute column, a new version is generated for the value. The version value uses a timestamp as the version number.

When you write data to an attribute column, you can specify a version number. If you do not specify a version number, Tablestore automatically generates a version number. Version numbers are timestamps in milliseconds. When you compare version numbers with TTL values or when you calculate the values of max version offset, you must divide the version numbers by 1000.

  • By default, the version number that is generated by Tablestore is the number of milliseconds that have elapsed since January 1, 1970, 00:00:00 UTC.
  • If you specify a version number, make sure that the version number of the attribute column is a 64-bit timestamp that is accurate to milliseconds and within the valid version range.
You can use version numbers to implement the following features:
  • TTL

    You can specify the TTL of attribute column values in a data table based on version numbers. When data of a specific version in an attribute column is retained for a period of time that exceeds the TTL value, Tablestore automatically deletes the data of the specific version.

    For example, the version number of the data in an attribute column is 1468944000000, which is equivalent to 00:00:00 UTC on July 20, 2016. If you set the value of TTL to 86400 seconds (one day), the data of this version expires at 00:00:00 UTC on July 21, 2016. Tablestore automatically deletes the data after the data expires.

  • Maximum number of versions or range of version numbers that you want Tablestore to read from each attribute column

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

Max versions

Max versions specifies the maximum number of versions that can be retained for the data in an attribute column. If the number of versions of data in attribute columns exceeds the value of this parameter, the system deletes the data of earlier versions.

When you create a data table, the default value 1 is used if you do not specify a value for max versions. You can also specify a max versions value for data in attribute columns. After you create a data table, you can call the UpdateTable operation to modify the max versions value for the data table.

If the number of versions exceeds the max versions value that you specify, the data of earlier versions becomes invalid and you cannot read the data even if the data has not been deleted by Tablestore.

  • When you decrease the value of max versions, Tablestore asynchronously deletes data of earlier versions if the number of data versions exceeds the most recent value of max versions.
  • When you increase the value of max versions, you can read the data of specific versions if Tablestore has not deleted the data of the versions and the versions are within the most recent valid version range.

TTL

TTL specifies the validity period of data in the Tablestore data table in seconds. When data of a specific version in an attribute column is retained for a period of time that exceeds the TTL value, Tablestore automatically deletes the data of the specific version from the attribute column. If data in all attribute columns of a row is retained for a period of time that exceeds the TTL value, Tablestore automatically deletes the row.

For example, you set the TTL of the data in a data table to 86400 seconds (one day). At 00:00:00 UTC on July 21, 2016, data whose version number is smaller than 1468944000000 expires. This version number is equivalent to 00:00:00 UTC on July 20, 2016 after the version number is divided by 1000 to convert into seconds. Tablestore automatically deletes the expired data.

When you create a data table, the default value -1 is used if you do not specify a value for TTL. The value of -1 indicates that data in the data table never expires. You can also specify a TTL value. After you create a data table, you can call the UpdateTable operation to modify the TTL value for the data in the data table.

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

  • When you decrease the TTL value, Tablestore asynchronously deletes the data that is retained for a period of time that exceeds the most recent TTL value.
  • When you increase the TTL value, you can read the data of specific versions if Tablestore has not deleted the data and data of the versions is retained for a period of time that is within the most recent TTL value.

Max version offset

If the difference between the current time and the version timestamp that you specify exceeds the TTL value that you specified for the data table, the written data immediately expires. To resolve this issue, Tablestore allows you to configure the max version offset feature.

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

When you write data to an attribute column, Tablestore checks the version number of the data. The valid version range of data in an attribute column is calculated by using the following formula: Valid version range = [max{Data written time - Max version offset, Data written time - TTL value}, Data written time + Max version offset). You can write data to the attribute column only if the version number of the data (converted into seconds by dividing by 1000) is within the valid version range.

For example, you set the max version offset of the data in each attribute column of a data table to 86400 seconds (one day). At 00:00:00 UTC on July 21, 2016, only the data whose version range is between 1468944000000 (00:00:00 UTC on July 20, 2016) and 1469116800000 (00:00:00 UTC on July 22, 2016) can be written. If you attempt to write a row of data in which the version number of data in an attribute column is 1468943999000 (23:59:59 UTC on July 19, 2016), the row fails to be written.

When you create a data table, the default value 86400 is used if you do not specify a value for max version offset. You can also specify a max version offset value for the data in the data table. After you create a data table, you can call the UpdateTable operation to modify the max version offset value for the data in the data table.