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 обладает следующими свойствами:

Гарантии

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

Ограничения

  • TTL-колонка должна быть одного из следующих типов:

    • Date;
    • Datetime;
    • Timestamp;
    • Uint32;
    • Uint64;
    • DyNumber.

  • Значение TTL-колонки с числовым типом (Uint32, Uint64, DyNumber) интерпретируется как величина от Unix-эпохи. Поддерживаемые единицы измерения (задаются в настройках TTL):

    • секунды;
    • миллисекунды;
    • микросекунды;
    • наносекунды.

  • Нельзя указать несколько 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.AlterTable(
    "mytable",
    TAlterTableSettings()
        .BeginAlterTtlSettings()
            .Set("created_at", TDuration::Hours(1))
        .EndAlterTtlSettings()
);

err := session.AlterTable(ctx, "mytable",
  options.WithSetTimeToLiveSettings(
    options.NewTTLSettings().ColumnDateType("created_at").ExpireAfter(time.Hour),
  ),
)

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

Совет

При настройке TTL с использованием YQL, Interval создается из строкового литерала в формате ISO 8601 с некоторыми ограничениями.

Следующий пример демонстрирует использование колонки modified_at с числовым типом (Uint32) в качестве TTL-колонки. Значение колонки интерпретируется как секунды от Unix-эпохи:

ALTER TABLE `mytable` SET (TTL = Interval("PT1H") ON modified_at AS SECONDS);

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

session.AlterTable(
    "mytable",
    TAlterTableSettings()
        .BeginAlterTtlSettings()
            .Set("modified_at", TTtlSettings::EUnit::Seconds, TDuration::Hours(1))
        .EndAlterTtlSettings()
);

err := session.AlterTable(ctx, "mytable",
  options.WithSetTimeToLiveSettings(
    options.NewTTLSettings().ColumnSeconds("modified_at").ExpireAfter(time.Hour),
  ),
)

session.alter_table('mytable', set_ttl_settings=ydb.TtlSettings().with_value_since_unix_epoch('modified_at', UNIT_SECONDS, 3600))

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

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

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

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

err := session.CreateTable(ctx, "mytable",
  options.WithColumn("id", types.Optional(types.TypeUint64)),
  options.WithColumn("expire_at", types.Optional(types.TypeTimestamp)),
  options.WithTimeToLiveSettings(
    options.NewTTLSettings().ColumnDateType("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 reset mytable

session.AlterTable(
    "mytable",
    TAlterTableSettings()
        .BeginAlterTtlSettings()
            .Drop()
        .EndAlterTtlSettings()
);

err := session.AlterTable(ctx, "mytable",
  options.WithDropTimeToLive(),
)

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

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

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

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

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

desc, err := session.DescribeTable(ctx, "mytable")
if err != nil {
  // process error
}
ttl := desc.TimeToLiveSettings

desc = session.describe_table('mytable')
ttl = desc.ttl_settings
Предыдущая
Change Data Capture (CDC)
Следующая
Скан запросы