브랜칭과 태깅

브랜칭과 태깅 (Branching and Tagging)

아이스버그 테이블 메타데이터는 테이블에 적용된 변경을 나타내는 스냅샷 로그를 유지해요. 이 문서에서는 스냅샷 라이프사이클을 정교하게 관리할 수 있는 브랜치(branch)와 태그(tag)를 소개해드릴게요. 브랜치와 태그는 고유한 독립 라이프사이클을 가진 스냅샷에 대한 이름 있는 참조예요. 감사·GDPR 요구사항 처리, 실험 브랜치 운영 같은 활용 사례를 함께 살펴볼게요.

출처: 문서

본문

개요 (Overview)

아이스버그 테이블 메타데이터는 테이블에 적용된 변경을 나타내는 스냅샷 로그를 유지해요. 스냅샷은 읽기 격리와 타임 트래블 쿼리의 기반이 되기 때문에 아이스버그에서 근본적으로 중요한 개념이에요. 메타데이터 크기와 스토리지 비용을 제어하기 위해 아이스버그는 스냅샷 라이프사이클 관리 프로시저를 제공하는데, 예를 들어 expire_snapshots는 사용하지 않는 스냅샷과 더 이상 필요 없는 데이터 파일을 테이블 스냅샷 보존 속성에 따라 제거해요.

더 정교한 스냅샷 라이프사이클 관리를 위해, 아이스버그는 브랜치와 태그를 지원해요. 이 둘은 각자의 독립적인 라이프사이클을 가진 스냅샷에 대한 이름 있는 참조예요. 이 라이프사이클은 브랜치·태그 수준의 보존 정책에 의해 제어돼요. 브랜치는 스냅샷의 독립적인 계보(lineage)이고, 그 계보의 헤드(head)를 가리켜요. 브랜치와 태그는 최대 참조 수명(maximum reference age) 속성을 가지며, 이 속성은 스냅샷 자체에 대한 참조를 언제 만료해야 하는지 제어해요. 브랜치는 보존 속성을 가지는데, 브랜치에 보관할 스냅샷의 최소 개수와 브랜치에 보관할 개별 스냅샷의 최대 수명을 정의해요. 이런 속성들은 expireSnapshots 프로시저가 실행될 때 사용돼요. expireSnapshots의 알고리즘에 대한 자세한 내용은 스펙을 참고해주세요.

사용 사례 (Use Cases)

브랜칭과 태깅은 GDPR 요구사항을 처리하고 감사를 위해 중요한 과거 스냅샷을 보관하는 데 사용할 수 있어요. 브랜치는 또한 데이터 엔지니어링 워크플로우에서 새 작업을 테스트하고 검증하기 위한 실험 브랜치를 활성화하는 데 사용할 수 있어요. 브랜칭과 태깅이 이런 사용 사례를 어떻게 돕는지 몇 가지 예시를 보여드릴게요.

과거 태그 (Historical Tags)

태그는 감사 목적으로 중요한 과거 스냅샷을 보관하는 데 사용할 수 있어요.

위 다이어그램은 다음 보존 정책으로 중요한 과거 스냅샷을 보관하는 것을 보여줘요. 스파크 SQL로 정의돼요.

1. 1개월 동안 주당 스냅샷 1개 보관. 주간 스냅샷에 태그를 만들고 태그 보존을 한 달로 설정해서 달성할 수 있어요. 스냅샷은 유지되고, 브랜치 참조 자체는 1주일 동안 보관돼요. -- 첫 주말 스냅샷에 태그를 만들어요. 스냅샷을 일주일 동안 보관해요.

   ALTER TABLE prod.db.table CREATE TAG `EOW-01` AS OF VERSION 7 RETAIN 7 DAYS;
   

2. 6개월 동안 월간 스냅샷 1개 보관. 월간 스냅샷에 태그를 만들고 태그 보존을 6개월로 설정해서 달성할 수 있어요. -- 첫 월말 스냅샷에 태그를 만들어요. 스냅샷을 6개월 동안 보관해요.

   ALTER TABLE prod.db.table CREATE TAG `EOM-01` AS OF VERSION 30 RETAIN 180 DAYS;
   

3. 1년 동안 연간 스냅샷 1개를 영구 보관. 연간 스냅샷에 태그를 만들어서 달성할 수 있어요. 브랜치와 태그의 기본 보존은 영구(forever)예요. -- 연말에 태그를 만들고 영구 보관해요.

   ALTER TABLE prod.db.table CREATE TAG `EOY-2023` AS OF VERSION 365;
   

4. 7일 동안 보관되고 브랜치의 최신 스냅샷 2개가 보관되는 임시 "test-branch"를 만들어요. -- 7일 동안 보관되고 최신 스냅샷 2개가 함께 보관되는 브랜치 "test-branch"를 만들어요.

   ALTER TABLE prod.db.table CREATE BRANCH `test-branch` RETAIN 7 DAYS WITH SNAPSHOT RETENTION 2 SNAPSHOTS;
   

감사 브랜치 (Audit Branch)

위 다이어그램은 쓰기 워크플로우를 검증하기 위해 감사 브랜치를 사용하는 예시를 보여줘요.

1. 먼저 write.wap.enabled가 설정돼 있는지 확인해요.

   ALTER TABLE db.table SET TBLPROPERTIES (
       'write.wap.enabled'='true'
   );
   

2. 스냅샷 3에서 시작하는 audit-branch를 만들어요. 이 브랜치는 쓰여지고 1주일 동안 보관돼요.

   ALTER TABLE db.table CREATE BRANCH `audit-branch` AS OF VERSION 3 RETAIN 7 DAYS;
   

3. 쓰기는 main 테이블 이력과 독립적인 별도의 audit-branch에서 수행돼요. -- WAP Branch write

   SET spark.wap.branch = audit-branch
   INSERT INTO prod.db.table VALUES (3, 'c');
   

4. 검증 워크플로우가 audit-branch의 상태를 검증해요(예: 데이터 품질).
5. 검증 후 main 브랜치를 audit-branch의 헤드로 fastForward해서 main 테이블 상태를 업데이트할 수 있어요.

   CALL catalog_name.system.fast_forward('prod.db.table', 'main', 'audit-branch');
   

6. 1주일 후 expireSnapshots가 실행되면 브랜치 참조가 제거돼요.

사용법 (Usage)

브랜치와 태그의 생성, 쿼리, 쓰기는 아이스버그 자바 라이브러리와 스파크·플링크 엔진 통합에서 지원돼요.

• 아이스버그 자바 라이브러리 (Iceberg Java Library)
• 스파크 DDL (Spark DDLs)
• 스파크 읽기 (Spark Reads)
• 스파크 브랜치 쓰기 (Spark Branch Writes)
• 플링크 읽기 (Flink Reads)
• 플링크 브랜치 쓰기 (Flink Branch Writes)

브랜치와 태그를 사용한 스키마 선택 (Schema selection with branches and tags)

테이블에 대해 추적되는 스키마가 모든 브랜치에서 유효하다는 점을 이해하는 것이 중요해요. 브랜치로 작업할 때는 테이블의 스키마가 사용돼요. 브랜치에 데이터를 쓸 때 검증되는 스키마가 바로 이 테이블 스키마이기 때문이에요. 반면 태그를 쿼리할 때는 스냅샷의 스키마를 사용해요. 스냅샷의 스키마는 그 스냅샷이 생성될 당시 가리키던 스키마 ID예요.

아래 예시들은 브랜치로 작업할 때 어떤 스키마가 사용되는지 보여줘요.

테이블을 만들고 데이터를 삽입해요:

CREATE TABLE db.table (id bigint, data string, col float);
INSERT INTO db.table VALUES (1, 'a', 1.0), (2, 'b', 2.0), (3, 'c', 3.0);
SELECT * FROM db.table;
1   a   1.0
2   b   2.0
3   c   3.0

현재 스냅샷을 가리키는 브랜치 test_branch를 만들고 브랜치에서 데이터를 읽어요:

ALTER TABLE db.table CREATE BRANCH test_branch;

SELECT * FROM db.table.branch_test_branch;
1   a   1.0
2   b   2.0
3   c   3.0

col 컬럼을 드롭하고 new_col이라는 새 컬럼을 추가해서 테이블 스키마를 수정해요:

ALTER TABLE db.table DROP COLUMN col;

ALTER TABLE db.table ADD COLUMN new_col date;

INSERT INTO db.table VALUES (4, 'd', date('2024-04-04')), (5, 'e', date('2024-05-05'));

SELECT * FROM db.table;
1   a   NULL
2   b   NULL
3   c   NULL
4   d   2024-04-04
5   e   2024-05-05

아래 문 중 하나로 브랜치의 헤드를 쿼리하면 테이블의 스키마를 사용해 데이터를 반환해요:

SELECT * FROM db.table.branch_test_branch;
1   a   NULL
2   b   NULL
3   c   NULL

SELECT * FROM db.table VERSION AS OF 'test_branch';
1   a   NULL
2   b   NULL
3   c   NULL

스냅샷 ID를 사용해 타임 트래블 쿼리를 수행하면 스냅샷의 스키마를 사용해요:

SELECT * FROM db.table.refs;
test_branch BRANCH  8109744798576441359 NULL    NULL    NULL
main        BRANCH  6910357365743665710 NULL    NULL    NULL

SELECT * FROM db.table VERSION AS OF 8109744798576441359;
1   a   1.0
2   b   2.0
3   c   3.0

브랜치에 쓸 때는 테이블의 스키마가 검증에 사용돼요:

INSERT INTO db.table.branch_test_branch VALUES (6, 'e', date('2024-06-06')), (7, 'g', date('2024-07-07'));

SELECT * FROM db.table.branch_test_branch;
6   e   2024-06-06
7   g   2024-07-07
1   a   NULL
2   b   NULL
3   c   NULL

더 알아보기 (Learn more)

• 네시 통합 (Nessie integration)
• 유지보수 (Maintenance)
• 아이스버그 스펙 (Iceberg spec)