Time Travel с Iceberg Catalog

Beta feature

Рекомендации по использованию бета-функций

Эта тема описывает функцию Time Travel в Selena для Iceberg catalogs. Эта функция поддерживается начиная с версии v1.5.2.

Обзор

Каждая Iceberg таблица поддерживает лог metadata snapshots, который представляет изменения, применённые к ней. Базы данных могут выполнять Time Travel запросы к Iceberg таблицам, обращаясь к этим историческим snapshots. Iceberg поддерживает ветвление (branching) и тегирование (tagging) snapshots для сложного управления жизненным циклом snapshots, позволяя каждой ветке (branch) или тегу (tag) поддерживать свой собственный жизненный цикл на основе настроенных политик хранения. Для получения дополнительной информации о функции branching и tagging в Iceberg см. Официальную документацию.

Интегрируя функцию snapshot branching и tagging Iceberg, Selena поддерживает создание и управление branches и tags в Iceberg catalogs, а также Time Travel запросы к таблицам внутри них.

Управление branches, tags и snapshots

Создание branch

Синтаксис CREATE BRANCH

ALTER TABLE [catalog.][database.]table_name
CREATE [OR REPLACE] BRANCH [IF NOT EXISTS] <branch_name>
[AS OF VERSION <snapshot_id>]
[RETAIN <int> { DAYS | HOURS | MINUTES }]
[WITH SNAPSHOT RETENTION
    { minSnapshotsToKeep | maxSnapshotAge | minSnapshotsToKeep maxSnapshotAge }]

minSnapshotsToKeep ::= <int> SNAPSHOTS

maxSnapshotAge ::= <int> { DAYS | HOURS | MINUTES }

Параметры

• branch_name: Имя создаваемой ветки.
• AS OF VERSION: ID snapshot (версии), на основе которого создаётся ветка.
• RETAIN: Время хранения ветки. Формат: <int> <unit>. Поддерживаемые единицы: DAYS, HOURS и MINUTES. Пример: 7 DAYS, 12 HOURS или 30 MINUTES.
• WITH SNAPSHOT RETENTION: Минимальное количество snapshots для хранения и/или максимальное время хранения snapshots.

Пример

Создать ветку test-branch на основе версии (snapshot ID) 12345 таблицы iceberg.sales.order, сохранить ветку на 7 дней и хранить минимум 2 snapshots на ветке.

ALTER TABLE iceberg.sales.order CREATE BRANCH `test-branch`
AS OF VERSION 12345
RETAIN 7 DAYS
WITH SNAPSHOT RETENTION 2 SNAPSHOTS;

Создать ветку test-branch2 на основе версии (snapshot ID) 12345 таблицы iceberg.sales.order, сохранить ветку на 7 дней и хранить snapshots на ветке максимум 2 дня.

ALTER TABLE iceberg.sales.order CREATE BRANCH `test-branch2`
AS OF VERSION 12345
RETAIN 7 DAYS
WITH SNAPSHOT RETENTION 2 DAYS;

Создать ветку test-branch3 на основе версии (snapshot ID) 12345 таблицы iceberg.sales.order, сохранить ветку на 7 дней и хранить минимум 2 snapshots на ветке, каждый максимум 2 дня.

ALTER TABLE iceberg.sales.order CREATE BRANCH `test-branch3`
AS OF VERSION 12345
RETAIN 7 DAYS
WITH SNAPSHOT RETENTION 2 SNAPSHOTS 2 DAYS;

Загрузка данных в конкретную ветку таблицы

Синтаксис VERSION AS OF

INSERT INTO [catalog.][database.]table_name
[FOR] VERSION AS OF <branch_name>
<query_statement>

Параметры

• branch_name: Имя ветки таблицы, в которую загружаются данные.
• query_statement: Запрос, результат которого будет загружен в целевую таблицу. Это может быть любой SQL запрос, поддерживаемый Selena.

Пример

Загрузить результат запроса в ветку test-branch таблицы iceberg.sales.order.

INSERT INTO iceberg.sales.order
FOR VERSION AS OF `test-branch`
SELECT c1, k1 FROM tbl;

Создание tag

Синтаксис CREATE TAG

ALTER TABLE [catalog.][database.]table_name
CREATE [OR REPLACE] TAG [IF NOT EXISTS] <tag_name>
[AS OF VERSION <snapshot_id>]
[RETAIN <int> { DAYS | HOURS | MINUTES }]

Параметры

• tag_name: Имя создаваемого тега.
• AS OF VERSION: ID snapshot (версии), на основе которого создаётся тег.
• RETAIN: Время хранения тега. Формат: <int> <unit>. Поддерживаемые единицы: DAYS, HOURS и MINUTES. Пример: 7 DAYS, 12 HOURS или 30 MINUTES.

Пример

Создать тег test-tag на основе версии (snapshot ID) 12345 таблицы iceberg.sales.order и сохранить тег на 7 дней.

ALTER TABLE iceberg.sales.order CREATE TAG `test-tag`
AS OF VERSION 12345
RETAIN 7 DAYS;

Ускоренное перемещение одной ветки к другой (Fast forward)

Синтаксис fast_forward

ALTER TABLE [catalog.][database.]table_name
EXECUTE fast_forward('<from_branch>', '<to_branch>')

Параметры

• from_branch: Ветка, которую вы хотите переместить (fast forward). Оберните имя ветки в кавычки.
• to_branch: Ветка, к которой вы хотите переместить from_branch. Оберните имя ветки в кавычки.

Пример

Переместить ветку main к ветке test-branch.

ALTER TABLE iceberg.sales.order
EXECUTE fast_forward('main', 'test-branch');

Cherry pick snapshot

Вы можете выбрать (cherry pick) конкретный snapshot и применить его к текущему состоянию таблицы. Эта операция создаст новый snapshot на основе существующего snapshot, и оригинальный snapshot не будет затронут.

Синтаксис cherrypick_snapshot

ALTER TABLE [catalog.][database.]table_name
EXECUTE cherrypick_snapshot(<snapshot_id>)

Параметр

snapshot_id: ID snapshot, который вы хотите выбрать (cherry pick).

Пример

ALTER TABLE iceberg.sales.order
EXECUTE cherrypick_snapshot(54321);

Истечение срока snapshots (Expire snapshots)

Вы можете установить истечение срока для snapshots раньше определённого момента времени. Эта операция удалит файлы данных истёкших snapshots.

Синтаксис expire_snapshots

ALTER TABLE [catalog.][database.]table_name
EXECUTE expire_snapshots('<datetime>')

Пример

ALTER TABLE iceberg.sales.order
EXECUTE expire_snapshots('2023-12-17 00:14:38')

Удаление branch или tag

Синтаксис DROP BRANCH, DROP TAG

ALTER TABLE [catalog.][database.]table_name
DROP { BRANCH <branch_name> | TAG <tag_name> }

Пример

ALTER TABLE iceberg.sales.order
DROP BRANCH `test-branch`;

ALTER TABLE iceberg.sales.order
DROP TAG `test-tag`;

Запросы с Time Travel

Time Travel к конкретной ветке или тегу

Синтаксис VERSION AS OF

[FOR] VERSION AS OF '<branch_or_tag>'

Параметр

tag_or_branch: Имя ветки или тега, к которому вы хотите выполнить Time Travel. Если указано имя ветки, запрос выполнит Time Travel к head snapshot ветки. Если указано имя тега, запрос выполнит Time Travel к snapshot, на который ссылается тег.

Пример

-- Time Travel к head snapshot ветки.
SELECT * FROM iceberg.sales.order VERSION AS OF 'test-branch';
-- Time Travel к snapshot, на который ссылается тег.
SELECT * FROM iceberg.sales.order VERSION AS OF 'test-tag';

Time Travel к конкретному snapshot

Синтаксис VERSION AS OF

[FOR] VERSION AS OF '<snapshot_id>'

Параметр

snapshot_id: ID snapshot, к которому вы хотите выполнить Time Travel.

Пример

SELECT * FROM iceberg.sales.order VERSION AS OF 12345;

Time Travel к конкретной дате и времени или дате

Синтаксис TIMESTAMP AS OF

[FOR] TIMESTAMP AS OF { '<datetime>' | '<date>' | date_and_time_function }

Параметр

date_and_time_function: Любые функции даты и времени, поддерживаемые Selena.

Пример

SELECT * FROM iceberg.sales.order TIMESTAMP AS OF '1986-10-26 01:21:00';
SELECT * FROM iceberg.sales.order TIMESTAMP AS OF '1986-10-26';
SELECT * FROM iceberg.sales.order TIMESTAMP AS OF now();