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 стадий:
- Проверка значений в TTL-колонке.
- Удаление устаревших данных.
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 в настоящий момент возможно с использованием:
- YQL.
- Консольного клиента YDB.
- YDB C++, Go и 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.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