Time to Live (TTL)

• How it works
• Limitations
• • Enabling TTL for an existing table
  • Disabling TTL

YDB lets you specify a table column (TTL column), whose values set the lifetime of items. TTL automatically deletes the item from your table once the specified number of seconds passes after the time set in the TTL column.

Warning

An item with the value in the TTL column is never deleted.

The timestamp for deleting a table item is determined by the formula:

Note

TTL doesn’t guarantee that the item will be deleted exactly at expiration_time, it might happen later. If it’s important to exclude logically obsolete but not yet physically deleted items from the selection, use query-level filtering.

Data is deleted by the Background Removal Operation (BRO), consisting of two stages:

1. Checking the values in the TTL column.
2. Deleting expired data.

The BRO has the following properties:

• The concurrency unit is a table partition.
• For tables with , the delete stage is a distributed transaction.

• At every point in time, a BRO is run in no more than 1 instance per table.
• BROs are run no more than once per hour for the same shard.
• Data consistency is guaranteed. The TTL column value is re-checked during the delete stage. This means that if the TTL column value is updated between stages 1 and 2 (for example, with UPDATE) and ceases to meet the delete criteria, the row will not be deleted.

• The TTL column must be of one of the following types:
  • Datetime
  • Timestamp
  • Uint32
  • Uint64
  • DyNumber
• The value in the TTL column with a numeric type (Uint32, Uint64, DyNumber) is interpreted as a value specified in:
  • Seconds
  • Milliseconds
  • Microseconds
  • Nanoseconds
• You can’t specify multiple TTL columns.
• You can’t delete the TTL column. However, if this is required, you should first disable TTL for the table.

Currently, you can manage TTL settings using:

• .
• YDB console client.
• YDB C++ and Python .

Note

TTL setup using YQL is possible for the Date, Datetime, and Timestamp columns.

In the example below, the items of the mytable table will be deleted an hour after the time set in the created_at column:

YQL

C++

Python

$ ydb -e <endpoint> -d <database> table ttl set --column created_at --expire-after 3600 mytable

session.AlterTable(
    "mytable",
    TAlterTableSettings()
        .BeginAlterTtlSettings()
            .Set("created_at", TDuration::Hours(1))
        .EndAlterTtlSettings()
);

Tip

When setting up TTL using YQL, the Interval is created from a string literal in ISO 8601.

For a newly created table, you can pass TTL settings along with the table description:

YQL

C++

Python

session.CreateTable(
    "mytable",
    TTableBuilder()
        .AddNullableColumn("id", EPrimitiveType::Uint64)
        .AddNullableColumn("expire_at", EPrimitiveType::Timestamp)
        .SetPrimaryKeyColumn("id")
        .Build()
);

session.create_table(
    'mytable',
    ydb.TableDescription()
    .with_column(ydb.Column('id', ydb.OptionalType(ydb.DataType.Uint64)))
    .with_column(ydb.Column('expire_at', ydb.OptionalType(ydb.DataType.Timestamp)))
    .with_primary_key('id')
    .with_ttl(ydb.TtlSettings().with_date_type_column('expire_at'))
)

YQL

CLI

C++

Python

ALTER TABLE `mytable` RESET (TTL);

$ ydb -e <endpoint> -d <database> table ttl drop mytable

session.alter_table('mytable', drop_ttl_settings=True)

The current TTL settings can be obtained from the table description:

CLI

C++

Python

$ ydb -e <endpoint> -d <database> scheme describe mytable

auto desc = session.DescribeTable("mytable").GetValueSync().GetTableDescription();
auto ttl = desc.GetTtlSettings();