UniForm을 사용하여 Iceberg 클라이언트에서 델타 테이블 읽기

아티클
10/02/2024

Delta Lake Universal Format(UniForm)을 사용하면 Iceberg 판독기 클라이언트를 사용하여 델타 테이블을 읽을 수 있습니다. 이 기능을 사용하려면 Databricks Runtime 14.3 LTS 이상이 필요합니다.

Important

레거시 UniForm IcebergCompatV1 테이블 기능에 대한 설명서는 레거시 UniForm IcebergCompatV1을 참조하세요.

Unity 카탈로그가 Iceberg 카탈로그로 작동하도록 외부 연결을 구성할 수 있습니다. Unity 카탈로그 Iceberg 카탈로그 엔드포인트를 사용하여 읽기를 참조하세요.

UniForm Iceberg는 기본 Parquet 데이터 파일의 압축 코덱으로 Snappy 대신 Zstandard를 사용합니다.

참고 항목

UniForm 메타데이터 생성은 델타 테이블에 데이터를 쓰는 데 사용되는 컴퓨팅에서 비동기적으로 실행되어 드라이버 리소스 사용량이 증가할 수 있습니다.

UniForm의 작동 방식

UniForm은 Delta Lake와 Iceberg가 Parquet 데이터 파일과 메타데이터 계층으로 구성되어 있다는 사실을 활용합니다. UniForm은 데이터를 다시 작성하지 않고도 자동으로 Iceberg 메타데이터를 비동기적으로 생성하므로 Iceberg 클라이언트는 델타 테이블을 읽을 수 있습니다. 데이터 파일의 단일 복사본은 여러 형식을 제공합니다.

요구 사항

UniForm Iceberg를 사용하도록 설정하려면 다음 요구 사항을 충족해야 합니다.

Unity 카탈로그에 델타 테이블을 등록해야 합니다. 관리 테이블과 외부 테이블이 모두 지원됩니다.
테이블에 열 매핑을 사용하도록 설정해야 합니다. Delta Lake 열 매핑을 사용하여 열 이름 바꾸기 및 삭제를 참조하세요.
델타 테이블에는 minReaderVersion>= 2 및 minWriterVersion>= 7이 있어야 합니다. Azure Databricks에서 Delta Lake 기능 호환성을 관리하는 방법을 참조하세요.
테이블에 대한 쓰기는 Databricks Runtime 14.3 LTS 이상을 사용해야 합니다.

참고 항목

UniForm Iceberg를 사용하도록 설정된 테이블에서 삭제 벡터를 사용하도록 설정할 수 없습니다.

삭제 벡터를 사용하도록 설정된 기존 테이블에서 UniForm Iceberg를 사용하도록 설정하는 동안 REORG를 사용하여 삭제 벡터를 비활성화하고 제거합니다. REORG를 사용하여 사용 또는 업그레이드를 참조하세요.

UniForm Iceberg 사용

Important

Delta UniForm을 사용하도록 설정하면 쓰기 프로토콜 기능인 델타 테이블 기능 IcebergCompatV2이 설정됩니다. 이 테이블 기능을 지원하는 클라이언트만 UniForm 지원 테이블에 쓸 수 있습니다. 이 기능을 사용하도록 설정된 델타 테이블에 쓰려면 Databricks Runtime 14.3 LTS 이상을 사용해야 합니다.

delta.universalFormat.enabledFormats 테이블 속성을 설정 해제하여 UniForm을 비활성화할 수 있습니다. Delta Lake 판독기 및 기록기 프로토콜 버전으로의 업그레이드는 취소할 수 없습니다.

UniForm Iceberg를 사용하도록 설정하려면 다음 테이블 속성을 설정해야 합니다.

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg'

UniForm을 처음 사용하도록 설정하는 경우 비동기 메타데이터 생성이 시작됩니다. 외부 클라이언트가 Iceberg를 사용하여 테이블을 쿼리하려면 먼저 이 작업을 완료해야 합니다. Iceberg 메타데이터 생성 상태 확인을 참조하세요.

제한 목록을 보려면 제한을 참조하세요.

테이블을 만드는 동안 활성화

UniForm Iceberg를 사용하려면 열 매핑을 사용하도록 설정해야 합니다. 다음 예제와 같이 테이블을 만드는 동안 UniForm Iceberg를 사용하도록 설정하면 자동으로 설정됩니다.

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

기존 테이블 변경을 통한 활성화

Databricks Runtime 15.4 LTS 이상에서는 다음 구문을 사용하여 기존 테이블에서 UniForm Iceberg를 사용하거나 업그레이드할 수 있습니다.

ALTER TABLE table_name SET TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

`REORG`를 사용하여 활성화 또는 업그레이드

다음 예제와 같이 REORG를 사용하여 UniForm Iceberg를 사용하도록 설정하고 기본 데이터 파일을 다시 작성할 수 있습니다.

REORG TABLE table_name APPLY (UPGRADE UNIFORM(ICEBERG_COMPAT_VERSION=2));

다음 중 어느 것이 true인 경우 REORG를 사용합니다.

테이블에 삭제 벡터가 활성화되어 있습니다.
이전에 UniForm Iceberg의 IcebergCompatV1 버전을 사용하도록 설정했습니다.
Athena 또는 Redshift와 같은 Hive 스타일의 Parquet 파일을 지원하지 않는 Iceberg 엔진에서 읽어야 합니다.

UniForm은 언제 Iceberg 메타데이터를 생성하나요?

Azure Databricks는 Delta Lake 쓰기 트랜잭션이 완료된 후 메타데이터 생성을 비동기적으로 트리거합니다. 이 메타데이터 생성 프로세스는 델타 트랜잭션을 완료한 것과 동일한 컴퓨팅을 사용합니다.

참고 항목

Iceberg 메타데이터 생성을 수동으로 트리거할 수도 있습니다. 수동으로 Iceberg 메타데이터 변환 트리거를 참조하세요.

메타데이터 생성과 관련된 쓰기 대기 시간을 방지하기 위해 자주 커밋된 델타 테이블은 여러 델타 커밋을 Iceberg 메타데이터에 대한 단일 커밋으로 그룹화할 수 있습니다.

Delta Lake는 지정된 컴퓨팅 리소스에서 언제든지 하나의 메타데이터 생성 프로세스만 진행되게 합니다. 두 번째 동시 메타데이터 생성 프로세스를 트리거하는 커밋은 Delta에 성공적으로 커밋되지만 비동기 Iceberg 메타데이터 생성을 트리거하지는 않습니다. 이렇게 하면 커밋이 자주 발생하는(커밋 간 간격이 몇 초~몇 분) 워크로드에 대한 메타데이터 생성 시 연속 대기 시간이 방지됩니다.

Delta 및 Iceberg 테이블 버전을 참조하세요.

Delta 및 Iceberg 테이블 버전

Delta Lake와 Iceberg는 테이블 메타데이터에 저장된 테이블 버전 또는 타임스탬프를 사용하여 시간 이동 쿼리를 허용합니다.

일반적으로 델타 테이블 버전은 커밋 타임스탬프 또는 버전 ID로 Iceberg 버전에 따라 정렬되지 않습니다. 지정된 버전의 Iceberg 테이블에 해당하는 델타 테이블의 버전을 확인하려면 해당 테이블 속성을 사용할 수 있습니다. Iceberg 메타데이터 생성 상태 확인을 참조하세요.

Iceberg 메타데이터 생성 상태 확인

UniForm은 다음 필드를 Unity 카탈로그 및 Iceberg 테이블 메타데이터에 추가하여 메타데이터 생성 상태를 추적합니다.

메타데이터 필드	설명
`converted_delta_version`	Iceberg 메타데이터가 성공적으로 생성된 델타 테이블의 최신 버전입니다.
`converted_delta_timestamp`	Iceberg 메타데이터가 성공적으로 생성된 최신 델타 커밋의 타임스탬프입니다.

Azure Databricks에서 다음 중 하나를 수행하여 이러한 메타데이터 필드를 검토할 수 있습니다.

DESCRIBE EXTENDED table_name에서 반환한 Delta Uniform Iceberg 섹션을 검토합니다.
카탈로그 탐색기를 사용하여 테이블 메타데이터를 검토합니다.
REST API를 사용하여 테이블을 가져옵니다.

Azure Databricks 외부에서 테이블 속성을 검토하는 방법은 Iceberg 판독기 클라이언트 설명서를 참조하세요. OSS Apache Spark의 경우 다음 구문을 사용하여 이러한 속성을 볼 수 있습니다.

SHOW TBLPROPERTIES <table-name>;

수동으로 Iceberg 메타데이터 변환 트리거

최신 버전의 델타 테이블에 대해 Iceberg 메타데이터 생성을 수동으로 트리거할 수 있습니다. 이 작업은 동기적으로 실행됩니다. 즉, 작업이 완료되면 Iceberg에서 사용할 수 있는 테이블 내용에 변환 프로세스가 시작될 때 사용할 수 있는 최신 버전의 델타 테이블이 반영됩니다.

이 작업은 정상적인 조건에서는 필요하지 않지만 다음과 같은 경우에 도움이 될 수 있습니다.

자동 메타데이터 생성이 성공하기 전에 클러스터가 종료됩니다.
오류 또는 작업 실패로 메타데이터 생성이 중단됩니다.
UniForm Iceberg 메타데이터 생성을 지원하지 않는 클라이언트는 델타 테이블에 씁니다.

다음 구문을 사용하여 Iceberg 메타데이터 생성을 수동으로 트리거합니다.

MSCK REPAIR TABLE <table-name> SYNC METADATA

REPAIR TABLE을 참조하세요.

메타데이터 JSON 경로를 사용하여 읽기

일부 Iceberg 클라이언트는 외부 Iceberg 테이블을 등록하기 위해 버전이 지정된 메타데이터 파일에 대한 경로를 제공해야 합니다. UniForm은 델타 테이블의 새 버전을 Iceberg로 변환할 때마다 새 메타데이터 JSON 파일을 만듭니다.

Iceberg를 구성하기 위해 메타데이터 JSON 경로를 사용하는 클라이언트에는 BigQuery가 포함됩니다. 구성 세부 정보는 Iceberg 판독기 클라이언트 설명서를 참조하세요.

Delta Lake는 다음 패턴을 사용하여 Iceberg 메타데이터를 테이블 디렉터리 아래에 저장합니다.

<table-path>/metadata/<version-number>-<uuid>.metadata.json

Azure Databricks에서 다음 중 하나를 수행하여 이 메타데이터 위치를 검토할 수 있습니다.

DESCRIBE EXTENDED table_name에서 반환한 Delta Uniform Iceberg 섹션을 검토합니다.
카탈로그 탐색기를 사용하여 테이블 메타데이터를 검토합니다.
REST API와 함께 다음 명령을 사용합니다.

GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

응답에는 다음과 같은 정보가 포함됩니다.

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

Important

경로 기반 Iceberg 판독기 클라이언트는 현재 테이블 버전을 읽기 위해 메타데이터 JSON 경로를 수동으로 업데이트하고 새로 고쳐야 할 수 있습니다. VACUUM을 통해 Parquet 데이터 파일을 델타 테이블에서 제거한 경우 오래된 버전을 사용하여 Iceberg 테이블을 쿼리할 때 오류가 발생할 수 있습니다.

Unity 카탈로그 Iceberg 카탈로그 엔드포인트를 사용하여 읽기

일부 Iceberg 클라이언트는 Iceberg REST 카탈로그에 연결할 수 있습니다. Unity 카탈로그는 엔드포인트 /api/2.1/unity-catalog/iceberg를 사용하여 UniForm이 활성화된 델타 테이블에 대한 Iceberg REST 카탈로그 API의 읽기 전용 구현을 제공합니다. 이 REST API 사용에 대한 자세한 내용은 Iceberg REST API 사양을 참조하세요.

Iceberg 카탈로그 API를 지원하는 것으로 알려진 클라이언트에는 Apache Spark, Flink, Trino가 포함됩니다. 구성 세부 정보는 Iceberg 판독기 클라이언트 설명서를 참조하세요.

인증 및 권한 부여

외부 서비스의 api/2.1/unity-catalog/iceberg 엔드포인트를 사용하여 Unity 카탈로그에 등록된 데이터에 액세스하기 위한 두 가지 요구 사항이 있습니다.

OAuth 또는 Databricks 개인용 액세스 토큰을 사용하여 인증합니다. Azure Databricks 리소스에 대한 액세스 인증을 참조하세요.
메타스토어에서 외부 데이터 액세스를 사용합니다. 이렇게 하면 API가 읽고 있는 스키마에 대한 EXTERNAL USE SCHEMA 권한이 있는 사용자에 대한 액세스가 제한됩니다. Unity 카탈로그의 데이터에 대한 외부 액세스 제어를 참조하세요.

Apache Spark 구성 예제

다음은 UniForm을 Iceberg로 읽도록 OSS Apache Spark를 구성하는 데 사용하는 설정의 예입니다.

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.type": "rest",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token": "<your_personal_access_token>",
"spark.sql.catalog.unity.warehouse": "<uc_catalog_name>"

개인용 액세스 토큰을 생성한 작업 영역의 전체 URL을 <api-root>로 대체합니다.

Spark 구성을 사용하여 Unity 카탈로그의 테이블을 쿼리하는 경우 다음 사항에 유의합니다.

개체 식별자는 unity.<schema-name>.<table-name> 패턴을 사용합니다.

이 패턴은 Unity 카탈로그에서 사용되지만 카탈로그 이름이 unity로 대체된 동일한 3계층 네임스페이스를 사용합니다.
Iceberg 관련 저장 프로시저를 실행하는 경우에만 "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"이 필요합니다.
스토리지에 클라우드 공급자를 사용하는 경우 클라우드별 Iceberg 번들 jar을 Spark 패키지로 추가해야 합니다.
- AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
- Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
- GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>
자세한 내용은 Spark에 대한 Iceberg AWS 통합 설명서를 참조하세요.

REST API curl 예제

이 curl 예제의 것과 같은 REST API 호출을 사용하여 테이블을 로드할 수도 있습니다.

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

그리고 다음과 같은 응답을 받아야 합니다.

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

참고 항목

응답의 expires-at-ms 필드는 자격 증명의 만료 시간을 나타내며 기본 만료 시간은 1시간입니다. 성능을 향상시키려면 클라이언트가 새 자격 증명을 요청하기 전에 만료 시간까지 자격 증명을 캐시하게 합니다.

제한 사항

모든 UniForm 테이블에는 다음과 같은 제한 사항이 있습니다.

삭제 벡터가 활성화된 테이블에서는 UniForm이 작동하지 않습니다. 삭제 벡터란?을 참조하세요.
UniForm이 활성화된 델타 테이블은 VOID 형식을 지원하지 않습니다.
Iceberg 클라이언트는 UniForm에서만 읽을 수 있습니다. 쓰기는 지원되지 않습니다.
Iceberg 판독기 클라이언트는 UniForm과 관계없이 개별 제한 사항이 있을 수 있습니다. 선택한 클라이언트에 대한 설명서를 참조하세요.
델타 공유의 수신자는 UniForm을 사용하는 경우에도 테이블을 Delta로만 읽을 수 있습니다.
UniForm Iceberg에서 사용하는 일부 Delta Lake 테이블 기능은 일부 델타 공유 판독기 클라이언트에서 지원되지 않습니다. Delta Sharing이란?을 참조하세요.

변경 데이터 피드는 UniForm이 사용하도록 설정되어 있지만 Iceberg에서 지원되지 않는 경우 델타 클라이언트에 대해 작동합니다.

다음을 통해 공유

UniForm을 사용하여 Iceberg 클라이언트에서 델타 테이블 읽기

UniForm의 작동 방식

요구 사항

UniForm Iceberg 사용

테이블을 만드는 동안 활성화

기존 테이블 변경을 통한 활성화

`REORG`를 사용하여 활성화 또는 업그레이드

UniForm은 언제 Iceberg 메타데이터를 생성하나요?

Delta 및 Iceberg 테이블 버전

Iceberg 메타데이터 생성 상태 확인

수동으로 Iceberg 메타데이터 변환 트리거

메타데이터 JSON 경로를 사용하여 읽기

Unity 카탈로그 Iceberg 카탈로그 엔드포인트를 사용하여 읽기

인증 및 권한 부여

Apache Spark 구성 예제

REST API curl 예제

제한 사항

피드백

추가 리소스

다음을 통해 공유

UniForm을 사용하여 Iceberg 클라이언트에서 델타 테이블 읽기

UniForm의 작동 방식

요구 사항

UniForm Iceberg 사용

테이블을 만드는 동안 활성화

기존 테이블 변경을 통한 활성화

REORG를 사용하여 활성화 또는 업그레이드

UniForm은 언제 Iceberg 메타데이터를 생성하나요?

Delta 및 Iceberg 테이블 버전

Iceberg 메타데이터 생성 상태 확인

수동으로 Iceberg 메타데이터 변환 트리거

메타데이터 JSON 경로를 사용하여 읽기

Unity 카탈로그 Iceberg 카탈로그 엔드포인트를 사용하여 읽기

인증 및 권한 부여

Apache Spark 구성 예제

REST API curl 예제

제한 사항

피드백

추가 리소스

`REORG`를 사용하여 활성화 또는 업그레이드