레거시 UniForm IcebergCompatV1

아티클
10/02/2024

Important

이 설명서는 사용 중지되었으며 업데이트되지 않을 수 있습니다. 이 콘텐츠에 언급된 제품, 서비스 또는 기술은 더 이상 지원되지 않습니다. UniForm을 사용하여 Iceberg 클라이언트에서 델타 테이블을 읽는 방법을 참조하세요.

Important

이 기능은 Databricks Runtime 13.2 이상에서 공개 미리 보기로 제공됩니다.

Delta Universal Format(UniForm)을 사용하면 Iceberg 판독기 클라이언트를 사용하여 델타 테이블을 읽을 수 있습니다.

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

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

참고 항목

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

요구 사항

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

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

Delta UniForm 사용

Important

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

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

다음 테이블 속성은 Iceberg에 대해 UniForm을 지원할 수 있게 합니다. iceberg는 유일한 유효한 값입니다.

'delta.universalFormat.enabledFormats' = 'iceberg'

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

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

CTAS 문을 사용하여 새 테이블을 만드는 경우 다음 예제와 같이 열 매핑을 수동으로 지정해야 합니다.

CREATE TABLE T
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.universalFormat.enabledFormats' = 'iceberg')
AS
  SELECT * FROM source_table;

기존 테이블을 변경하는 경우 다음 예제와 같이 이러한 속성을 모두 지정해야 합니다.

ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

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

참고 항목

BigQuery를 Iceberg 판독기 클라이언트로 사용하려는 경우 데이터 레이아웃에 대한 BigQuery 요구 사항을 수용하려면 Azure Databricks에서spark.databricks.delta.write.dataFilesToSubdir를 true로 설정해야 합니다.

제한 사항 보기.

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

Azure Databricks는 Delta Lake 쓰기 트랜잭션이 델타 트랜잭션을 완료한 것과 동일한 컴퓨팅을 사용하여 완료된 후 Iceberg 메타데이터 생성을 비동기적으로 트리거합니다. Iceberg 메타데이터 생성을 수동으로 트리거할 수도 있습니다. 수동으로 Iceberg 메타데이터 변환 트리거를 참조하세요.

Iceberg 메타데이터 생성과 관련된 쓰기 대기 시간을 방지하기 위해 커밋이 자주 발생하는 델타 테이블은 여러 델타 커밋을 단일 Iceberg 커밋 번들로 묶을 수 있습니다.

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

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

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

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

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

Azure Databricks에서 카탈로그 탐색기를 사용하여 이러한 메타데이터 필드를 검토할 수 있습니다. 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

카탈로그 탐색기를 사용하여 이 파일의 경로를 찾을 수 있습니다. 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가 포함됩니다. UniForm이 활성화된 델타 테이블을 포함하는 기본 클라우드 개체 스토리지에 대한 액세스를 구성해야 합니다. 구성 세부 정보는 Iceberg 판독기 클라이언트 설명서를 참조하세요.

다른 서비스가 Unity 카탈로그에 연결할 수 있도록 Azure Databricks 개인용 액세스 토큰을 생성하고 구성해야 합니다. Azure Databricks 리소스에 대한 액세스 인증을 참조하세요.

다음은 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.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"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.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

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

참고 항목

이 메서드를 사용하여 Unity 카탈로그의 테이블을 쿼리할 때 개체 식별자는 다음 패턴을 사용합니다.

unity.<catalog-name>.<schema-name>.<table-name>

이 패턴은 Unity 카탈로그에 있는 동일한 3계층 네임스페이스를 사용하지만 추가 접두사 unity를 추가합니다.

Delta 및 Iceberg 테이블 버전

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

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

제한 사항

다음 제한 사항이 존재합니다.

삭제 벡터가 활성화된 테이블에서는 UniForm이 작동하지 않습니다. 삭제 벡터란?을 참조하세요.
UniForm이 활성화된 델타 테이블은 LIST, MAP, VOID 형식을 지원하지 않습니다.
Iceberg 클라이언트는 UniForm에서만 읽을 수 있습니다. 쓰기는 지원되지 않습니다.
Iceberg 판독기 클라이언트는 UniForm과 관계없이 개별 제한 사항이 있을 수 있습니다. 선택한 클라이언트에 대한 설명서를 참조하세요.
Iceberg 판독기 클라이언트 버전 1.2.0 이하는 Apache Spark에서 작성한 INT96 타임스탬프 유형을 지원하지 않습니다. 이 제한을 방지하려면 UniForm 테이블에 쓰는 Notebook에서 다음 코드를 사용합니다. spark.conf.set(“spark.sql.parquet.outputTimestampType”, “TIMESTAMP_MICROS”)
Unity 카탈로그 Iceberg 엔드포인트의 공개 미리 보기 버전은 대규모 프로덕션 워크로드를 위한 것이 아닙니다. 초당 5개의 쿼리 임계값을 초과하는 경우 속도 제한이 발생할 수 있습니다.

다음 Delta Lake 기능은 UniForm이 활성화되어 있지만 Iceberg에서 지원되지 않는 경우 델타 클라이언트에 대해 작동합니다.

데이터 피드 변경
Delta Sharing

다음을 통해 공유

레거시 UniForm IcebergCompatV1

요구 사항

Delta UniForm 사용

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

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

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

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

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

Delta 및 Iceberg 테이블 버전

제한 사항

피드백

추가 리소스