Apache Iceberg™ 테이블 관리하기¶

예: 테이블 업데이트하기¶

INSERT 및 UPDATE 문을 사용하여 Snowflake 관리 Iceberg 테이블을 수정할 수 있습니다.

다음 예제에서는 store_sales 라는 Iceberg 테이블에 새 값을 삽입한 다음, 값이 현재 -99인 경우 cola 열을 1로 업데이트합니다.

INSERT INTO store_sales VALUES (-99);

UPDATE store_sales
  SET cola = 1
  WHERE cola = -99;

테이블 쿼리¶

업데이트, 삭제, 병합 작업에 행 수준 삭제 를 구성한 경우 Snowflake는 외부에서 관리되는 Iceberg 테이블 을 쿼리할 수 있도록 지원합니다.

행 수준 삭제를 구성하려면 Apache Iceberg 설명서에서 value 속성 을 참조하십시오.

위치 삭제 파일을 사용하여 테이블에 쓰기¶

Snowflake는 Amazon S3, Azure 또는 Google Cloud에 저장된 외부 관리형 Iceberg 테이블에 쓰기 위한 위치 행 수준 삭제를 지원합니다. copy-on-write 모드에서 DML 작업을 실행시키는 위치 삭제를 끄려면 테이블, 스키마 또는 데이터베이스 수준에서 ENABLE_ICEBERG_MERGE_ON_READ 매개 변수를 FALSE로 설정합니다.

삭제 벡터를 사용하여 테이블에 쓰기¶

행 수준 데이터 수정을 최적화하기 위해 Snowflake는 Amazon S3, Azure 또는 Google Cloud에 저장된 외부 관리 및 Snowflake 관리 Iceberg 테이블에 쓰기 위한 삭제 벡터를 지원합니다. 삭제 벡터를 통해 Snowflake는 “merge-on-read”(MOR) 작업을 수행하여 다음 DML 문에 대한 쓰기 성능을 개선합니다.

• DELETE

• UPDATE

• MERGE

Snowflake는 큰 데이터 파일을 다시 작성하는 대신 작은 벡터 파일을 작성하여 이러한 성능을 달성합니다. 자세한 내용은 Apache Iceberg 사양의 `삭제 벡터 <https://iceberg.apache.org/spec/#deletion-vectors>`_를 참조하세요.

copy-on-write 대 merge-on-read¶

Iceberg는 컴퓨팅 엔진이 외부에서 관리되는 테이블의 행 수준 작업을 처리하는 방법을 구성하는 두 가지 모드를 제공합니다. Snowflake는 이 두 가지 모드를 모두 지원합니다.

다음 테이블에서는 각 모드를 사용할 수 있는 경우에 대해 설명합니다.

Iceberg의 행 수준 변경에 대한 자세한 내용은 Apache Iceberg 설명서의 행 수준 삭제 를 참조하십시오.

고려 사항 및 제한 사항¶

Iceberg 테이블에서 행 수준 삭제를 사용할 때 다음 정보를 고려하세요.

• Snowflake는 v2 Iceberg 테이블에 대해서만 `위치 삭제 <https://iceberg.apache.org/spec/#position-delete-files>`_를 지원하며, v3 Iceberg 테이블에 대해서는 `삭제 벡터 <https://iceberg.apache.org/spec/#deletion-vectors>`_를 지원합니다.

• Snowflake는 외부 관리 Iceberg 테이블을 사용한 위치 삭제만 지원합니다.

• 행 수준 삭제를 사용할 때 최상의 읽기 성능을 얻으려면 정기적으로 압축 및 테이블 유지 관리를 수행하여 오래된 삭제 파일을 제거하십시오. 자세한 내용은 외부 카탈로그를 사용하는 테이블 관리하기 섹션을 참조하십시오.

• 과도한 위치 삭제, 특히 허상 위치 삭제는 테이블 생성 및 새로 고침 작업을 방해할 수 있습니다. 이 문제를 방지하려면 테이블 유지 관리를 수행하여 추가 위치 삭제를 제거합니다.

  사용할 테이블 유지 관리 방법은 외부 Iceberg 엔진에 따라 다릅니다. 예를 들어, delete-file-threshold 또는 rewrite-all 옵션과 함께 Spark의 rewrite_data_files 메서드를 사용할 수 있습니다. 자세한 내용은 Apache Iceberg™ 설명서의 `rewrite_data_files<https://iceberg.apache.org/docs/latest/spark-procedures/#rewrite_data_files>`_ 섹션을 참조하세요.

자동 클러스터링¶

자동 클러스터링은 자주 쿼리되는 열을 기준으로 파일 또는 파티션 내의 데이터를 재구성합니다. 대상 파일 크기를 설정하지 않는 한, Iceberg 테이블의 파일 크기는 클러스터링 구성을 기준으로 합니다. 대상 파일 크기를 설정하면 파일 크기는 사용자가 설정한 특정 크기가 됩니다. 자세한 내용은 대상 파일 크기 설정하기 섹션을 참조하십시오.

자동 클러스터링을 설정하려면 Snowflake 관리 Iceberg 테이블을 생성하거나 기존 테이블을 수정할 때 CLUSTER BY 매개 변수를 지정합니다. 자세한 내용은 다음을 참조하십시오.

• CREATE ICEBERG TABLE(Iceberg 카탈로그로서의 Snowflake)

• ALTER ICEBERG TABLE

자동 클러스터링에 대한 자세한 내용은 자동 클러스터링 섹션을 참조하세요.

데이터 압축¶

데이터 압축은 작은 파일을 더 크고 효율적인 파일로 결합하여 저장소를 관리하고, 최적의 파일 크기를 유지하고, 쿼리 성능을 개선합니다.

대부분의 경우 데이터 압축은 컴퓨팅 비용에 큰 영향을 미치지 않지만, 이러한 비용이 우려되는 경우 압축을 비활성화할 수 있습니다. 예를 들어, 테이블을 거의 쿼리하지 않는 경우 테이블에서 압축을 비활성화할 수 있습니다. 데이터 압축을 비활성화하거나 활성화하려면 데이터 압축 설정 섹션을 참조하세요.

매니페스트 압축¶

매니페스트 압축은 더 작은 매니페스트 파일을 재구성하고 결합하여 메타데이터 계층을 최적화합니다. 이 압축은 메타데이터 오버헤드를 줄이고 쿼리 성능을 개선합니다.

이 기능은 자동으로 활성화되며 비활성화할 수 없습니다.

스냅샷 만료¶

스냅샷 만료는 테이블의 기록에서 오래된 스냅샷과 해당 고유 데이터 및 메타데이터 파일을 체계적으로 삭제합니다. 이 삭제는 미리 정의된 보존 정책을 기준으로 합니다.

이 기능은 자동으로 활성화되며 비활성화할 수 없습니다.

테이블의 메타데이터 새로 고치기¶

다음 예제에서는 외부 카탈로그(예: AWS Glue 또는 Delta)를 사용하는 테이블의 메타데이터를 수동으로 새로 고칩니다. 테이블을 새로 고치면 원격 카탈로그에서 발생한 모든 변경 사항과 테이블이 동기화됩니다.

이러한 유형의 Iceberg 테이블을 사용할 경우 명령에 메타데이터 파일 경로를 지정하지 않습니다.

ALTER ICEBERG TABLE my_iceberg_table REFRESH;

테이블을 자동으로 업데이트하려면 자동 새로 고침 을 설정할 수 있습니다. ALTER ICEBERG TABLE 명령을 사용합니다.

예:

ALTER ICEBERG TABLE my_iceberg_table SET AUTO_REFRESH = TRUE;

Iceberg 파일에서 생성된 테이블의 메타데이터 새로 고치기¶

다음 예제에서는 외부 클라우드 저장소에 있는 Iceberg 메타데이터 파일 에서 생성된 테이블을 수동으로 새로 고치며, 선행 슬래시(/) 없이 메타데이터 파일의 상대 경로를 지정합니다. 메타데이터 파일은 새로 고친 후 테이블의 데이터를 정의합니다.

ALTER ICEBERG TABLE my_iceberg_table REFRESH 'metadata/v1.metadata.json';

예: 기본값으로 테이블 생성¶

기본값으로 Iceberg 테이블을 생성하려면 CREATE ICEBERG TABLE 명령을 사용합니다.

다음 예제에서는 Snowflake 관리 Iceberg 테이블을 생성할 때 먼저 열의 기본값을 설정합니다. 다음으로, 기본값이 있는 열의 값을 지정하지 않고 테이블에 레코드를 삽입합니다.

1. user_events 테이블을 생성하고, 해당 테이블에 기본값이 2``인 ``event_version 열을 포함합니다.

   CREATE ICEBERG TABLE user_events (
       event_id INT,
       user_id INT,
       event_type STRING,
       event_time TIMESTAMP,
       event_version INT DEFAULT 2
     )
     CATALOG = 'SNOWFLAKE'
     EXTERNAL_VOLUME = 'my_external_volume'
     BASE_LOCATION = 'database/schema/user_event'
     ICEBERG_VERSION = 3;
   

   Copy

   테이블 정의에서 기본값을 설정하면 초기 기본값과 쓰기 기본값이 설정됩니다. 열에는 쓰기 기본값이 있으므로 ``event_version``이 쓰기 중에 지정되지 않은 경우 ``2``는 새 레코드에 사용됩니다.

2. ``event_version``이 지정된 로그인 이벤트를 추가합니다.

   INSERT INTO user_events VALUES
     (1, 101, 'login', '2025-11-01 10:00:00', 1);
   

   Copy

3. 구매 이벤트를 추가하되 ``event_version``을 지정하지 않습니다.

   INSERT INTO user_events VALUES
   (1, 101, 'purchase', '2025-11-01 10:01:00');
   

   Copy

   결과적으로, Snowflake는 ``event_version``의 값을 테이블에 ``2``로 입력합니다.

4. 테이블을 쿼리합니다.

   SELECT * FROM user_events;
   

   Copy

   출력:

   +-----------+----------+-------------+---------------------+----------------+
   | event_id  | user_id  | event_type  | event_time          | event_version  |
   +-----------+----------+-------------+---------------------+----------------+
   | 1         | 101      | login       | 2025-11-01 10:00:00 | 1              |
   | 1         | 101      | purchase    | 2025-11-01 10:01:00 | 2              |
   +-----------+----------+-------------+---------------------+----------------+
   

예: 기존 테이블에 기본값이 있는 열 추가¶

Iceberg 테이블에 기본값이 있는 새 열을 추가하려면 ALTER ICEBERG TABLE 명령을 사용합니다.

다음 예제에서는 기본값이 2``인 ``event_version 열을 추가하여 user_events 테이블을 수정합니다.

ALTER ICEBERG TABLE user_events ADD COLUMN event_version INT DEFAULT 2;

쓰기 기본값을 설정 외에도, 기본값이 있는 열을 추가하면 열의 초기 기본값도 설정됩니다. 결과적으로, event_version 열에 대한 기존 레코드의 기본값은 ``2``입니다.

예: 열의 쓰기 기본값 변경¶

다음 예제에서는 user_events 테이블의 event_version 열에 대한 쓰기 기본값을 ``3``으로 변경합니다.

ALTER ICEBERG TABLE user_events ALTER COLUMN event_version SET WRITE DEFAULT 3;

테이블에 대해 정의된 기본값 확인¶

Snowflake 관리 또는 외부 관리 Iceberg 테이블에서 테이블 열의 기본값을 확인하려면 DESCRIBE ICEBERG TABLE 명령을 실행한 후 출력에서 DEFAULT 열 및 WRITE DEFAULT 열을 확인합니다.

• DEFAULT 열은 Apache Iceberg 사양의 initial-default 값에 매핑됩니다.

• WRITE DEFAULT 열은 Apache Iceberg 사양의 write-default 값에 매핑됩니다.

이러한 열은 테이블이 v2 Iceberg 테이블인지 또는 v3 Iceberg 테이블인지 여부에 관계없이 출력에서 반환합니다.

다음 예제에서는 user_events 테이블에 대한 열을 설명합니다. 이 테이블에는 event_version 열에 대해 지정된 초기 기본값 및 쓰기 기본값이 있습니다.

DESC ICEBERG TABLE user_events
  ->> SELECT
    "name",
    "kind",
    "default",
    "write default"
      FROM $1;

출력:

+-----------------+---------+---------+---------------+
| name            | kind    | default | write default |
+-----------------+---------+-------------------------+
| EVENT_ID        | COLUMN  |         |               |
| USER_ID         | COLUMN  |         |               |
| EVENT_TYPE      | COLUMN  |         |               |
| EVENT_TIME      | COLUMN  |         |               |
| EVENT_VERSION   | COLUMN  | 2       | 3             |
+-----------------+---------+---------+---------------+

쓰기 기본값 삭제¶

열의 쓰기 기본값을 삭제하려면 ALTER ICEBERG TABLE 명령과 DROP WRITE DEFAULT 키워드를 사용합니다.

다음 예제에서는 event_version 열에 대한 기본 쓰기 값을 삭제합니다.

ALTER ICEBERG TABLE user_events ALTER COLUMN event_version DROP WRITE DEFAULT;

기본값에 대한 고려 사항 및 제한 사항¶

Snowflake 관리 및 외부 관리 Iceberg 테이블과 함께 기본값을 사용할 때는 다음 사항을 고려하세요.

행 계보에 대한 고려 사항 및 제한 사항¶

행 계보는 다음 사항을 고려하여 스트림에서 지원됩니다.

• Append-only 스트림과 표준 스트림은 Snowflake 관리 Iceberg v3 테이블에서 지원됩니다.

• Insert-only 스트림과 표준 스트림은 외부 관리 Iceberg v3 테이블에서 지원됩니다.

  • 표준 스트림이 올바른 결과를 생성하도록 하려면 외부 엔진이 Iceberg v3 사양과 관련하여 Iceberg v3 테이블에 작성해야 합니다. 특히, 새로 삽입된 행에는 :code:`_row_id=NULL`이 있어야 합니다. copy-on-write 중에 복사된 행은 :code:`_row_id`를 유지해야 합니다.

  • MAX_DATA_EXTENSION_TIME_IN_DAYS는 외부 관리 Iceberg v3 테이블에서는 작동하지 않습니다.

• DMLs가 다중 문 트랜잭션을 통해 커밋되는 경우, Iceberg v3 테이블의 append-only 스트림은 Iceberg v2 테이블과 의미 체계가 다릅니다.

  • Iceberg v2에서 append-only 스트림의 경우 다중 문 트랜잭션에서 행이 추가된 후 삭제되면 이 행은 삽입으로 간주됩니다.

  • Iceberg v3에서 append-only 스트림의 경우 이 행은 삽입으로 처리되지 않습니다.

이러한 고려 사항과 제한 사항은 Iceberg v3의 기능인 행 계보에 적용됩니다. 모든 Iceberg v3 테이블에 적용되는 고려 사항 및 제한 사항 목록은 Iceberg v3 기능에 대한 고려 사항 및 제한 사항 섹션을 참조하세요.