Using Time to Live

Time to Live (TTL) is a mechanism that allows you to automatically expire table rows. TTL is expressed as the amount of time data is allowed to live in the store. Data which has reached its expiration timeout value can no longer be retrieved, and will not appear in any store statistics. Whether the data is physically removed from the store is determined by an internal mechanism that is not user-controllable.

TTL represents a minimum guaranteed time to live. Data expires on hour or day boundaries. This means that with a one hour TTL, there can be as much as two hours worth of unexpired data. For example (using a time format of hour:minute:second), given a one hour TTL, data written between 00:00:00.000 and 00:59:59.999 will expire at 02:00:00.000 because the data is guaranteed to expire no less than one hour from when it is written.

In case of MR Tables with TTL value defined, the rows replicated to other regions carry the expiration time when the row was written. This can be either the default table level TTL value or a row level override that is set by your application. Therefore, this row will expire in all the regions at the same time, irrespective of when they were replicated.

Expired data is invisible to queries and store statistics, but even so it is using disk space until it has been purged. Here, store statistics refer to the statistics related to your store's performance and availability. See Monitoring the Store. The expired data is purged from disk at some point in time after its expiration date. The exact time when the data is purged is driven by internal mechanisms and the workload on your store.

The TTL value for a table row can be updated at any time before the expiration value has been reached. Data that has expired can no longer be modified, and this includes its TTL value.

TTL is more efficient than manual user-deletion of the row because it avoids the overhead of writing a database log entry for the data deletion. The deletion also does not appear in the replication stream.

Specifying a TTL Value

TTL values are specified on a row by row basis using Row.setTTL(). This method accepts a TimeToLive class instance, which allows you to identify the number of days or hours the row will live in the store before expiring. A duration interval specified in days is recommended because this results in the least amount of storage consumed in the store. However, if you want a TTL value that is not an even multiple of days, then specify the TTL value in hours.

The code example from Writing Rows to a Table in the Store can be extended to specify a TTL value of 5 days like this:

package kvstore.basicExample;

import oracle.kv.KVStore;
import oracle.kv.table.Row;
import oracle.kv.table.Table;
import oracle.kv.table.TimeToLive;
import oracle.kv.table.TableAPI;

...

// KVStore handle creation is omitted for brevity

...

TableAPI tableH = kvstore.getTableAPI();
Table myTable = tableH.getTable("myTable");

// Get a Row instance
Row row = myTable.createRow();


// Add a TTL value to the row
row.setTTL(TimeToLive.ofDays(5));

// Now put all of the cells in the row.
row.put("item", "Bolts");
row.put("description", "Hex head, stainless");
row.put("count", 5);
row.put("percentage", 0.2173913);

// Now write the table to the store.
tableH.put(row, null, null);

Updating a TTL Value

To update the expiration time for a table row, you write the row as normal, and at the same time specify the new expiration time. However, you must also indicate that the expiration time is to be updated. By default, you can modify the row data and the expiration time will not be modified, even if you specify a new TTL value for the row.

To indicate that the the expiration time is to be updated, specify true to the WriteOptions.setUpdateTTL() method. For example, using the previous example, to change the TTL value to 10 days, do the following:

package kvstore.basicExample;

import oracle.kv.KVStore;
import oracle.kv.table.Row;
import oracle.kv.table.Table;
import oracle.kv.table.Table.TimeToLive;
import oracle.kv.table.TableAPI;
import oracle.kv.table.WriteOptions;

...

// KVStore handle creation is omitted for brevity

...

TableAPI tableH = kvstore.getTableAPI();
Table myTable = tableH.getTable("myTable");

// Get a Row instance
Row row = myTable.createRow();

// Change the TTL value for the row from 5 days to 10.
row.setTTL(TimeToLive.ofDays(10));

// Now put all of the cells in the row.
row.put("item", "Bolts");
row.put("description", "Hex head, stainless");
row.put("count", 5);
row.put("percentage", 0.2173913);

// Now write the table to the store.
tableH.put(row, null, new WriteOptions().setUpdateTTL(true));

Deleting TTL Expiration

If you have set a TTL value for a row and you later decide you do not want it to ever automatically expire, you can turn off TTL by setting a TTL value of TimeToLive.DO_NOT_EXPIRE:

package kvstore.basicExample;

import oracle.kv.KVStore;
import oracle.kv.table.Row;
import oracle.kv.table.Table;
import oracle.kv.table.Table.TimeToLive;
import oracle.kv.table.TableAPI;
import oracle.kv.table.WriteOptions;

...

// KVStore handle creation is omitted for brevity

...

TableAPI tableH = kvstore.getTableAPI();
Table myTable = tableH.getTable("myTable");

// Get a Row instance
Row row = myTable.createRow();


// Modify the row's TTL so that it will never expire
row.setTTL(TimeToLive.DO_NOT_EXPIRE);

// Now put all of the cells in the row.
row.put("item", "Bolts");
row.put("description", "Hex head, stainless");
row.put("count", 5);
row.put("percentage", 0.2173913);

// Now write the table to the store.
tableH.put(row, null, new WriteOptions().setUpdateTTL(true));

Setting Default Table TTL Values

You can set a default TTL value for the table when you define the table using the USING TTL DDL statement. It may be optionally applied when a table is created using CREATE TABLE or when a table is modified using one of the ALTER TABLE statements. See USING TTL for details on this statement.

For example:

CREATE TABLE myTable (
  item STRING,
  description STRING,
  count INTEGER,
  percentage DOUBLE,
  PRIMARY KEY (item) // Every table must have a primary key
) USING TTL 5 days

At program run time, you can examine the default TTL value for a table using the Table.getDefaultTTL() method.