옵션 1: 스냅샷 프로시저 옵션 2: 마이그레이션 절차 에서 테이블 마이그레이션 절차 복제 AWS Glue Data Catalog 인플레이스 마이그레이션 후 Iceberg 테이블 동기화 유지 올바른 인플레이스 마이그레이션 전략 선택

인플레이스 마이그레이션

인플레이스 마이그레이션을 사용하면 모든 데이터 파일을 다시 쓸 필요가 없습니다. 대신 Iceberg 메타데이터 파일이 생성되어 기존 데이터 파일에 연결됩니다. 이 방법은 일반적으로 더 빠르고 비용 효율적이며, 특히 Parquet, Avro 및 ORC와 같은 호환되는 파일 형식이 있는 대규모 데이터 세트 또는 테이블의 경우 더욱 효과적입니다.

참고

Amazon S3 Tables로 마이그레이션할 때는 현재 위치 마이그레이션을 사용할 수 없습니다.

Iceberg는 인플레이스 마이그레이션을 구현하기 위한 두 가지 주요 옵션을 제공합니다.

스냅샷 절차를 사용하여 소스 테이블을 변경하지 않고 새 Iceberg 테이블을 생성합니다. 자세한 내용은 Iceberg 설명서의 스냅샷 테이블을 참조하세요.
마이그레이션 절차를 사용하여 소스 테이블을 대체하는 새 Iceberg 테이블을 생성합니다. 자세한 내용은 Iceberg 설명서의 테이블 마이그레이션을 참조하세요. 이 절차는 Hive 메타스토어(HMS)에서 작동하지만 현재와 호환되지 않습니다 AWS Glue Data Catalog. 이 가이드의 뒷부분에 있는 섹션의 테이블 마이그레이션 복제 절차는 AWS Glue Data Catalog 데이터 카탈로그로 유사한 결과를 달성하기 위한 해결 방법을 제공합니다.

snapshot 또는를 사용하여 현재 위치 마이그레이션을 수행한 후 migrate일부 데이터 파일은 마이그레이션되지 않은 상태로 유지될 수 있습니다. 이는 일반적으로 라이터가 마이그레이션 도중 또는 이후에 소스 테이블에 계속 쓸 때 발생합니다. 이러한 나머지 파일을 Iceberg 테이블에 통합하려면 add_files 프로시저를 사용할 수 있습니다. 자세한 내용은 Iceberg 설명서의 파일 추가를 참조하세요.

다음과 같이 Athena에서 생성되고 채워진 Parquet 기반 products 테이블이 있다고 가정해 보겠습니다.


CREATE EXTERNAL TABLE mydb.products (
    product_id INT,
    product_name STRING
)
PARTITIONED BY (category STRING)
STORED AS PARQUET
LOCATION 's3://amzn-s3-demo-bucket/products/';

INSERT INTO mydb.products
VALUES 
    (1001, 'Smartphone', 'electronics'),
    (1002, 'Laptop', 'electronics'),
    (2001, 'T-Shirt', 'clothing'),
    (2002, 'Jeans', 'clothing');

다음 섹션에서는이 테이블에서 snapshot 및 migrate 프로시저를 사용하는 방법을 설명합니다.

옵션 1: 스냅샷 프로시저

이 snapshot 절차에서는 이름이 다른 새 Iceberg 테이블을 생성하지만 소스 테이블의 스키마와 파티셔닝을 복제합니다. 이 작업은 작업 중과 작업 후에 소스 테이블을 완전히 변경하지 않습니다. 테이블의 경량 복사본을 효과적으로 생성하므로 원래 데이터 소스를 수정하지 않고도 시나리오 또는 데이터 탐색을 테스트하는 데 특히 유용합니다. 이 접근 방식을 사용하면 원래 테이블과 Iceberg 테이블을 모두 사용할 수 있는 전환 기간이 활성화됩니다(이 섹션의 끝에 있는 참고 사항 참조). 테스트가 완료되면 모든 라이터와 리더를 새 테이블로 전환하여 새 Iceberg 테이블을 프로덕션 테이블로 이동할 수 있습니다.

모든 Amazon EMR 배포 모델(예: Amazon EMR on EC2, Amazon EMR on EKS, EMR Serverless) 및에서 Spark를 사용하여 snapshot 프로시저를 실행할 수 있습니다 AWS Glue.

snapshot Spark 절차를 사용하여 인플레이스 마이그레이션을 테스트하려면 다음 단계를 따르세요.

Spark 애플리케이션을 시작하고 다음 설정으로 Spark 세션을 구성합니다.
- "spark.sql.extensions":"org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"
- "spark.sql.catalog.spark_catalog":"org.apache.iceberg.spark.SparkSessionCatalog"
- "spark.sql.catalog.spark_catalog.type":"glue"
- "spark.hadoop.hive.metastore.client.factory.class":"com.amazonaws.glue.catalog.metastore.AWSGlueDataCatalogHiveClientFactory"
프로시저를snapshot 실행하여 원래 테이블 데이터 파일을 가리키는 새 Iceberg 테이블을 생성합니다.
```
spark.sql(f"""
CALL system.snapshot(
source_table => 'mydb.products', 
table => 'mydb.products_iceberg',
location => 's3://amzn-s3-demo-bucket/products_iceberg/'
)
"""
).show(truncate=False)
```
출력 데이터 프레임에는 imported_files_count (추가된 파일 수)가 포함됩니다.

쿼리를 통해 새 테이블을 검증합니다.


spark.sql(f"""
SELECT * FROM mydb.products_iceberg LIMIT 10
"""
).show(truncate=False)

Notes

프로시저를 실행한 후 소스 테이블에서 데이터 파일을 수정하면 생성된 테이블이 동기화되지 않습니다. 추가하는 새 파일은 Iceberg 테이블에 표시되지 않으며 제거한 파일은 Iceberg 테이블의 쿼리 기능에 영향을 미칩니다. 동기화 문제를 방지하려면:
- 새 Iceberg 테이블이 프로덕션용인 경우 원본 테이블에 쓰는 모든 프로세스를 중지하고 새 테이블로 리디렉션합니다.
- 전환 기간이 필요하거나 새 Iceberg 테이블이 테스트용인 경우 테이블 동기화 유지에 대한 지침은이 섹션 뒷부분의 인플레이스 마이그레이션 후 Iceberg 테이블 동기화 유지를 참조하세요.
snapshot 프로시저를 사용하면 생성된 Iceberg 테이블의 테이블 gc.enabled 속성true에서 속성이 로 설정됩니다. 이 설정은 데이터 파일을 물리적으로 삭제하는 PURGE 옵션을 DROP TABLE 사용하여 remove_orphan_files또는 expire_snapshots와 같은 작업을 금지합니다. 소스 파일에 직접적인 영향을 주지 않는 Iceberg 삭제 또는 병합 작업은 여전히 허용됩니다.
데이터 파일을 물리적으로 삭제하는 작업에 대한 제한 없이 새 Iceberg 테이블이 완전히 작동하도록 하려면 gc.enabled 테이블 속성을 로 변경할 수 있습니다false. 그러나이 설정은 원본 테이블에 대한 액세스를 손상시킬 수 있는 소스 데이터 파일에 영향을 미치는 작업을 허용합니다. 따라서 원래 테이블의 기능을 더 이상 유지할 필요가 없는 경우에만 gc.enabled 속성을 변경합니다. 예:
```
spark.sql(f"""
ALTER TABLE mydb.products_iceberg
SET TBLPROPERTIES ('gc.enabled' = 'false');
""")
```

옵션 2: 마이그레이션 절차

이 migrate 절차에서는 소스 테이블과 이름, 스키마 및 파티셔닝이 동일한 새 Iceberg 테이블을 생성합니다. 이 프로시저가 실행되면 소스 테이블을 잠그고 이름을 <table_name>_BACKUP_ (또는 backup_table_name 프로시저 파라미터로 지정된 사용자 지정 이름)으로 바꿉니다.

참고

drop_backup 프로시저 파라미터를 로 설정하면 true원래 테이블이 백업으로 유지되지 않습니다.

따라서 migrate 테이블 절차를 수행하려면 작업을 수행하기 전에 소스 테이블에 영향을 미치는 모든 수정 사항을 중지해야 합니다. migrate 프로시저를 실행하기 전에:

소스 테이블과 상호 작용하는 모든 라이터를 중지합니다.
기본적으로 Iceberg를 지원하지 않는 리더와 라이터를 수정하여 Iceberg 지원을 활성화합니다.

예:

Athena는 수정 없이 계속 작동합니다.
Spark에는 다음이 필요합니다.
- 클래스 경로에 포함될 Iceberg Java Archive(JAR) 파일(이 가이드 앞부분의 섹션에서 Amazon EMR에서 Iceberg 작업 및 Iceberg 작업 AWS Glue 참조).
- 다음 Spark 세션 카탈로그 구성(Iceberg가 아닌 테이블에 대한 기본 제공 카탈로그 기능을 유지하면서 Iceberg 지원을 추가하는 SparkSessionCatalog 데 사용):
  - "spark.sql.extensions":"org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"
  - "spark.sql.catalog.spark_catalog":"org.apache.iceberg.spark.SparkSessionCatalog"
  - "spark.sql.catalog.spark_catalog.type":"glue"
  - "spark.hadoop.hive.metastore.client.factory.class":"com.amazonaws.glue.catalog.metastore.AWSGlueDataCatalogHiveClientFactory"

프로시저를 실행한 후 새 Iceberg 구성으로 라이터를 다시 시작할 수 있습니다.

현재는 데이터 카탈로그가 RENAME 작업을 지원하지 AWS Glue Data Catalog않으므로 migrate 프로시저가와 호환되지 않습니다. 따라서 Hive 메타스토어로 작업하는 경우에만이 절차를 사용하는 것이 좋습니다. 데이터 카탈로그를 사용하는 경우 대체 접근 방식은 다음 섹션을 참조하세요.

모든 Amazon EMR 배포 모델(EC2의 Amazon EMR, EKS의 Amazon EMR, EMR Serverless) 및에서 migrate 프로시저를 실행할 수 AWS Glue있지만 Hive 메타스토어에 대해 구성된 연결이 필요합니다. Amazon EMR on EC2는 설정 복잡성을 최소화하는 기본 제공 Hive 메타스토어 구성을 제공하므로 권장되는 선택입니다.

Hive 메타스토어로 구성된 EC2 클러스터의 Amazon EMR에서 migrate Spark 절차를 사용하여 인플레이스 마이그레이션을 테스트하려면 다음 단계를 따르세요.

Spark 애플리케이션을 시작하고 Iceberg Hive 카탈로그 구현을 사용하도록 Spark 세션을 구성합니다. 예를 들어 CLI를 사용하는 경우pyspark:


pyspark --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions --conf spark.sql.catalog.spark_catalog=org.apache.iceberg.spark.SparkSessionCatalog --conf spark.sql.catalog.spark_catalog.type=hive

Hive 메타스토어에서 products 테이블을 생성합니다. 일반적인 마이그레이션에 이미 존재하는 소스 테이블입니다.
1. Hive 메타스토어에서 products 외부 Hive 테이블을 생성하여 Amazon S3의 기존 데이터를 가리킵니다.
```
spark.sql(f"""
CREATE EXTERNAL TABLE products (
    product_id INT,
    product_name STRING
)
PARTITIONED BY (category STRING)
STORED AS PARQUET
LOCATION 's3://amzn-s3-demo-bucket/products/';
"""
)
```
2. MSCK REPAIR TABLE 명령을 사용하여 기존 파티션을 추가합니다.
```
spark.sql(f"""
MSCK REPAIR TABLE products
"""
)
```
3. SELECT 쿼리를 실행하여 테이블에 데이터가 포함되어 있는지 확인합니다.
```
spark.sql(f"""
SELECT * FROM products
"""
).show(truncate=False)
```
  샘플 출력:
Iceberg migrate 절차를 사용합니다.
```
df_res=spark.sql(f"""
CALL system.migrate(
table => 'default.products'
)
"""
)

df_res.show()
```
출력 데이터 프레임에는 migrated_files_count( Iceberg 테이블에 추가된 파일 수)가 포함됩니다.
백업 테이블이 생성되었는지 확인합니다.
```
spark.sql("show tables").show()
```
샘플 출력:

Iceberg 테이블을 쿼리하여 작업을 검증합니다.


spark.sql(f"""
SELECT * FROM products
"""
).show(truncate=False)

Notes

절차를 실행한 후 Iceberg 지원으로 제대로 구성되지 않은 경우 소스 테이블에 쿼리하거나 쓰는 모든 현재 프로세스에 영향을 미칩니다. 따라서 다음 단계를 따르는 것이 좋습니다.
1. 마이그레이션하기 전에 소스 테이블을 사용하여 모든 프로세스를 중지합니다.
2. 마이그레이션을 수행합니다.
3. 적절한 Iceberg 설정을 사용하여 프로세스를 다시 활성화합니다.
마이그레이션 프로세스 중에 데이터 파일 수정이 발생하면(새 파일이 추가되거나 파일이 제거됨) 생성된 테이블이 동기화되지 않습니다. 동기화 옵션은이 섹션 뒷부분의 인플레이스 마이그레이션 후 Iceberg 테이블 동기화 유지를 참조하세요.

에서 테이블 마이그레이션 절차 복제 AWS Glue Data Catalog

다음 단계에 따라 마이그레이션 절차의 결과를에 복제할 수 있습니다 AWS Glue Data Catalog (원본 테이블 백업 및 Iceberg 테이블로 교체).

스냅샷 절차를 사용하여 원본 테이블의 데이터 파일을 가리키는 새 Iceberg 테이블을 생성합니다.
데이터 카탈로그에서 원본 테이블 메타데이터를 백업합니다.
1. GetTable API를 사용하여 소스 테이블 정의를 검색합니다.
2. GetPartitions API를 사용하여 소스 테이블 파티션 정의를 검색합니다.
3. CreateTable API를 사용하여 데이터 카탈로그에 백업 테이블을 생성합니다.
4. CreatePartition 또는 BatchCreatePartition API를 사용하여 데이터 카탈로그의 백업 테이블에 파티션을 등록합니다.
gc.enabled Iceberg 테이블 속성을 로 변경false하여 전체 테이블 작업을 활성화합니다.
원본 테이블을 삭제합니다.
테이블 루트 위치의 메타데이터 폴더에서 Iceberg 테이블 메타데이터 JSON 파일을 찾습니다.
register_table 프로시저를 원래 테이블 이름과 snapshot 프로시저로 생성된 metadata.json 파일의 위치와 함께 사용하여 데이터 카탈로그에 새 테이블을 등록합니다.
```
spark.sql(f"""
CALL system.register_table(
    table => 'mydb.products', 
    metadata_file => '{iceberg_metadata_file}'
)
"""
).show(truncate=False)
```

인플레이스 마이그레이션 후 Iceberg 테이블 동기화 유지

이 add_files 절차는 기존 데이터를 Iceberg 테이블에 통합하는 유연한 방법을 제공합니다. 특히 Iceberg의 메타데이터 계층에서 절대 경로를 참조하여 기존 데이터 파일(예: Parquet 파일)을 등록합니다. 기본적으로 프로시저는 모든 테이블 파티션의 파일을 Iceberg 테이블에 추가하지만 특정 파티션의 파일을 선택적으로 추가할 수 있습니다. 이 선택적 접근 방식은 여러 시나리오에서 특히 유용합니다.

초기 마이그레이션 후 새 파티션이 소스 테이블에 추가되는 경우.
초기 마이그레이션 후 데이터 파일이 기존 파티션에 추가되거나 기존 파티션에서 제거되는 경우. 그러나 수정된 파티션을 다시 추가하려면 먼저 파티션을 삭제해야 합니다. 이에 대한 자세한 내용은이 섹션의 뒷부분에 나와 있습니다.

다음은 새 Iceberg 테이블을 소스 데이터 파일과 동기화된 상태로 유지하기 위해 인플레이스 마이그레이션(snapshot 또는 migrate)을 수행한 후 add_file 절차를 사용할 때 고려해야 할 몇 가지 사항입니다.

소스 테이블의 새 파티션에 새 데이터가 추가되면 옵션과 함께 add_files 프로시저를partition_filter 사용하여 이러한 추가 사항을 Iceberg 테이블에 선택적으로 통합합니다.


spark.sql(f"""
CALL system.add_files(
source_table => 'mydb.products', 
table => 'mydb.products_iceberg',
partition_filter => map('category', 'electronics')
).show(truncate=False)

또는:


spark.sql(f"""
CALL system.add_files(
source_table => '`parquet`.`s3://amzn-s3-demo-bucket/products/`', 
table => 'mydb.products_iceberg',
partition_filter => map('category', 'electronics')
).show(truncate=False)

이 add_files 프로시저는 partition_filter 옵션을 지정할 때 전체 소스 테이블 또는 특정 파티션의 파일을 스캔하고 찾은 모든 파일을 Iceberg 테이블에 추가하려고 시도합니다. 기본적으로 check_duplicate_files 프로시저 속성은 로 설정true되므로 Iceberg 테이블에 파일이 이미 있는 경우 프로시저가 실행되지 않습니다. 이는 이전에 추가한 파일을 건너뛰는 기본 제공 옵션이 없으며 비활성화check_duplicate_files하면 파일이 두 번 추가되어 중복이 생성되므로 중요합니다. 소스 테이블에 새 파일이 추가되면 다음 단계를 따릅니다.
1. 새 파티션의 경우와 add_files 함께 partition_filter를 사용하여 새 파티션에서 파일만 가져옵니다.
2. 기존 파티션의 경우 먼저 Iceberg 테이블에서 파티션을 삭제한 다음를 지정하여 해당 파티션에 add_files 대해 다시 실행합니다partition_filter. 예:
```
# We initially perform in-place migration with snapshot
spark.sql(f"""
CALL system.snapshot(
source_table => 'mydb.products', 
table => 'mydb.products_iceberg',
location => 's3://amzn-s3-demo-bucket/products_iceberg/'
)
"""
).show(truncate=False)

# Then on the source table, some new files were generated under the category='electronics' partition. Example:
spark.sql("""
INSERT INTO mydb.products
VALUES (1003, 'Tablet', 'electronics')
""")

# We delete the modified partition from the Iceberg table. Note this is a metadata operation only
spark.sql("""
DELETE FROM mydb.products_iceberg WHERE category = 'electronics'
""")

# We add_files from the modified partition
spark.sql("""
CALL system.add_files(
  source_table => 'mydb.products', 
  table => 'mydb.products_iceberg',
  partition_filter => map('category', 'electronics')
)
""").show(truncate=False)
```

참고

모든 add_files 작업은 추가된 데이터가 포함된 새 Iceberg 테이블 스냅샷을 생성합니다.

올바른 인플레이스 마이그레이션 전략 선택

최상의 인플레이스 마이그레이션 전략을 선택하려면 다음 표의 질문을 고려하세요.

질문	권장 사항	설명
테스트 또는 점진적 전환을 위해 Hive 테이블과 Iceberg 테이블 모두에 액세스할 수 있도록 유지하면서 데이터를 다시 작성하지 않고 빠르게 마이그레이션하고 싶으신가요?	`snapshot` 프로시저 다음에 `add_files` 프로시저	`snapshot` 절차를 사용하여 소스 테이블을 수정하지 않고 스키마를 복제하고 데이터 파일을 참조하여 새 Iceberg 테이블을 생성합니다. `add_files` 절차를 사용하여 마이그레이션 후 추가되거나 수정된 파티션을 통합합니다. 수정된 파티션을 다시 추가하려면 먼저 파티션 삭제가 필요합니다.
Hive 메타스토어를 사용 중이며 데이터를 다시 작성하지 않고 Hive 테이블을 즉시 Iceberg 테이블로 바꾸고 싶으신가요?	`migrate` 프로시저 다음에 `add_files` 프로시저	`migrate` 절차를 사용하여 Iceberg 테이블을 생성하고, 소스 테이블을 백업하고, 원래 테이블을 Iceberg 버전으로 바꿉니다. 참고:이 옵션은 Hive 메타스토어와 호환되지만 와는 호환되지 않습니다 AWS Glue Data Catalog. `add_files` 절차를 사용하여 마이그레이션 후 추가되거나 수정된 파티션을 통합합니다. 수정된 파티션을 다시 추가하려면 먼저 파티션 삭제가 필요합니다.
를 사용 중이며 데이터를 다시 작성하지 않고 Hive 테이블을 즉시 Iceberg 테이블로 바꾸고 싶으 AWS Glue Data Catalog 신가요?	`migrate` 프로시저 조정 후 `add_files` 프로시저	복제 `migrate` 프로시저 동작: `snapshot`를 사용하여 Iceberg 테이블을 생성합니다. API를 사용하여 AWS Glue 원래 테이블 메타데이터를 백업합니다. APIs Iceberg 테이블 속성`gc.enabled`에서를 활성화합니다. 원본 테이블을 삭제합니다. `register_table`를 사용하여 원래 이름으로 새 테이블 항목을 생성합니다. 참고: 이 옵션을 사용하려면 메타데이터 백업을 위한 AWS Glue API 직접 호출을 수동으로 처리해야 합니다. `add_files` 절차를 사용하여 마이그레이션 후 추가되거나 수정된 파티션을 통합합니다. 수정된 파티션을 다시 추가하려면 먼저 파티션 삭제가 필요합니다.

질문

권장 사항

설명

테스트 또는 점진적 전환을 위해 Hive 테이블과 Iceberg 테이블 모두에 액세스할 수 있도록 유지하면서 데이터를 다시 작성하지 않고 빠르게 마이그레이션하고 싶으신가요?

snapshot 프로시저 다음에 add_files 프로시저

snapshot 절차를 사용하여 소스 테이블을 수정하지 않고 스키마를 복제하고 데이터 파일을 참조하여 새 Iceberg 테이블을 생성합니다. add_files 절차를 사용하여 마이그레이션 후 추가되거나 수정된 파티션을 통합합니다. 수정된 파티션을 다시 추가하려면 먼저 파티션 삭제가 필요합니다.

Hive 메타스토어를 사용 중이며 데이터를 다시 작성하지 않고 Hive 테이블을 즉시 Iceberg 테이블로 바꾸고 싶으신가요?

migrate 프로시저 다음에 add_files 프로시저

migrate 절차를 사용하여 Iceberg 테이블을 생성하고, 소스 테이블을 백업하고, 원래 테이블을 Iceberg 버전으로 바꿉니다.

참고:이 옵션은 Hive 메타스토어와 호환되지만 와는 호환되지 않습니다 AWS Glue Data Catalog.

add_files 절차를 사용하여 마이그레이션 후 추가되거나 수정된 파티션을 통합합니다. 수정된 파티션을 다시 추가하려면 먼저 파티션 삭제가 필요합니다.

를 사용 중이며 데이터를 다시 작성하지 않고 Hive 테이블을 즉시 Iceberg 테이블로 바꾸고 싶으 AWS Glue Data Catalog 신가요?

migrate 프로시저 조정 후 add_files 프로시저

복제 migrate 프로시저 동작:

snapshot를 사용하여 Iceberg 테이블을 생성합니다.
API를 사용하여 AWS Glue 원래 테이블 메타데이터를 백업합니다. APIs
Iceberg 테이블 속성gc.enabled에서를 활성화합니다.
원본 테이블을 삭제합니다.
register_table를 사용하여 원래 이름으로 새 테이블 항목을 생성합니다.

참고: 이 옵션을 사용하려면 메타데이터 백업을 위한 AWS Glue API 직접 호출을 수동으로 처리해야 합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

기존 테이블을 Iceberg로 마이그레이션

전체 데이터 마이그레이션