Time to Live (TTL)

В разделе описан принцип работы TTL, его ограничения, а также приведены примеры команд и фрагменты кода, с помощью которых можно включить, настроить и выключить TTL.

Принцип работы

YDB позволяет указать для таблицы колонку (TTL-колонка), значения которой будут использоваться для определения времени жизни строк. TTL автоматически удаляет из таблицы строки, когда проходит указанное количество секунд от времени, записанного в TTL-колонку.

Момент времени, когда строка таблицы может быть удалена, определяется по следующей формуле:

expiration_time = valueof(ttl_column) + expire_after_seconds

Непосредственно удалением данных занимается фоновая операция удаления — Background Removal Operation (BRO), состоящая из 2 стадий:

1. Проверка значений в TTL-колонке.
2. Удаление устаревших данных.

BRO обладает следующими свойствами:

• Единицей параллельности является партиция таблицы.
• Для таблиц со вторичными индексами стадия удаления является распределенной транзакцией.

Гарантии

• В каждый момент времени BRO запущен не более, чем в 1 экземпляре на таблицу.
• BRO запускается не чаще одного раза в час для одной и той же партиции.
• Гарантируется согласованность данных. Значение в TTL-колонке повторно проверяется во время стадии удаления. Таким образом, если между стадиями 1 и 2 значение в TTL-колонке модифицируется (например, запросом UPDATE) и перестает соответствовать критерию удаления, такая строка не будет удалена.

Ограничения

• TTL-колонка должна быть одного из следующих типов:
  • Date;
  • Datetime;
  • Timestamp;
  • Uint32;
  • Uint64;
  • DyNumber.
• Значение TTL-колонки с числовым типом (Uint32, Uint64, DyNumber) интерпретируется как величина от Unix-эпохи заданная в:
  • секундах;
  • миллисекундах;
  • микросекундах;
  • наносекундах.
• Нельзя указать несколько TTL-колонок.
• Нельзя удалить TTL-колонку. Если это все же требуется, сначала нужно выключить TTL на таблице.

Настройка

Управление настройками TTL в настоящий момент возможно с использованием:

• YQL.
• Консольного клиента YDB.
• YDB Python SDK.

Включение TTL для существующей таблицы

В приведенном ниже примере строки таблицы mytable будут удаляться спустя час после наступления времени, записанного в колонке created_at:

ALTER TABLE `mytable` SET (TTL = Interval("PT1H") ON created_at);

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

session.alter_table('mytable', set_ttl_settings=ydb.TtlSettings().with_date_type_column('created_at', 3600))

Включение TTL для вновь создаваемой таблицы

Для вновь создаваемой таблицы можно передать настройки TTL вместе с ее описанием:

CREATE TABLE `mytable` (
    id Uint64,
    expire_at Timestamp,
    PRIMARY KEY (id)
) WITH (
    TTL = Interval("PT0S") ON expire_at
);

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'))
)

Выключение TTL

ALTER TABLE `mytable` RESET (TTL);

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

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

Получение настроек TTL

Текущие настройки TTL можно получить из описания таблицы:

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

desc = session.describe_table('mytable')
ttl = desc.ttl_settings