Подключиться
Yandex Database

Time to Live (TTL)

Статья создана

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

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

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

Важно

Строка с NULL в TTL-колонке никогда не будет удалена.

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

expiration_time = valueof(ttl_column) + expire_after_seconds

Примечание

Не гарантируется, что удаление произойдет именно в expiration_time — оно может случиться позже. Если важно исключить из выборки логически устаревшие, но пока ещё физически неудалённые строки, нужно использовать фильтрацию уровня запроса.

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

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

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

  • Единицей параллельности является шард таблицы.
  • Для таблиц без вторичных индексов осуществляется "слепое" удаление. То есть, если между стадиями 1 и 2 значение в TTL-колонке модифицируется (например, запросом UPDATE), изменившееся значение не будет проверено повторно.
  • Для таблиц со вторичными индексами стадия удаления является распределённой транзакцией.

Гарантии

  • В каждый момент времени BRO запущен не более, чем в 1 экземпляре на таблицу.
  • BRO запускается не чаще одного раза в час для одного и того же шарда.
  • Для таблиц со вторичными индексами гарантируется согласованность данных.

Ограничения

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

Настройка

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

Включение 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 с использованием YQL, Interval создаётся из строкового литерала в формате ISO 8601.

Включение 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
В этой статье: