다음을 통해 공유

Apache Iceberg 클라이언트에서 Azure Databricks 테이블에 액세스

중요합니다

Unity 카탈로그 Apache Iceberg REST 카탈로그 API는 Databricks Runtime 16.4 LTS 이상에서 공개 미리 보기 로 제공됩니다.

Unity 카탈로그에는 일반적으로 사용할 수 있는 Iceberg REST 카탈로그 API의 읽기 전용 구현이 있습니다. 이 엔드포인트는 Iceberg 읽기를 사용하도록 설정된 델타 테이블을 읽는 데 권장됩니다. 자세한 내용은 Apache Iceberg 클라이언트(레거시)에서 Databricks 테이블 읽기를 참조하세요.

Apache Iceberg REST 카탈로그를 사용하면 Apache Spark, Apache Flink 및 Trino와 같은 지원되는 클라이언트가 Azure Databricks에서 Unity 카탈로그에 등록된 Iceberg 테이블에서 읽고 쓸 수 있습니다. Snowflake는 읽기 전용으로 지원됩니다.

지원되는 통합의 전체 목록은 Unity 카탈로그 통합을 참조하세요.

Unity 카탈로그 Iceberg 카탈로그 엔드포인트 사용

Unity 카탈로그는 Iceberg REST 카탈로그 API 사양의 구현을 제공합니다.

엔드포인트 /api/2.1/unity-catalog/iceberg-rest사용하여 액세스를 구성합니다. 이 REST API 사용에 대한 자세한 내용은 Iceberg REST API 사양 참조하세요.

메모

Azure Databricks는 일부 Iceberg 판독기 클라이언트에 대한 자격 증명 자동 판매기를 도입했습니다. Databricks는 자격 증명 자동 판매기를 사용하여 지원되는 시스템의 클라우드 스토리지 위치에 대한 액세스를 제어하는 것이 좋습니다. 외부 시스템 액세스을 위한 Unity 카탈로그 자격 증명 발급을 참조하세요.

클라이언트에 대해 자격 증명 자동 판매기가 지원되지 않는 경우 클라이언트에서 Delta 또는 Iceberg 테이블에 대한 파일 및 메타데이터가 포함된 스토리지 위치로의 액세스를 구성해야 합니다. 구성 세부 정보는 Iceberg 클라이언트에 대한 설명서를 참조하세요.

요구 사항

Azure Databricks는 Unity 카탈로그의 일부로 테이블에 대한 Iceberg REST 카탈로그 액세스를 지원합니다. 이러한 엔드포인트를 사용하려면 작업 영역에서 Unity 카탈로그를 사용하도록 설정해야 합니다. 다음 테이블 형식은 Iceberg REST 카탈로그를 통해 액세스할 수 있습니다.

주제 읽다 작성하다
관리되는 빙산 예 예
외국 빙산 예 아니오
관리되는 델타(Iceberg 읽기를 사용하도록 설정) 예 아니오
외부 델타(Iceberg 읽기 활성화됨) 예 아니오

외부 아이스버그 테이블은 Iceberg REST 카탈로그 API를 통해 읽을 때 자동으로 새로 고쳐지지 않습니다. 새로 고치려면 실행 REFRESH FOREIGN TABLE 하여 최신 스냅샷을 읽어야 합니다. Foreign Iceberg 테이블에서는 인증 정보 제공이 지원되지 않습니다.

메모

Iceberg REST 카탈로그 API를 통해 액세스할 수 있도록 델타 테이블을 구성해야 합니다. Iceberg 클라이언트를 사용하여 델타 테이블 읽기를참조하세요.

Iceberg REST 카탈로그를 사용하여 Iceberg 클라이언트에서 Azure Databricks 테이블을 읽거나 쓰기 위한 액세스를 구성하려면 다음 구성 단계를 완료해야 합니다.

Apache Spark에서 Iceberg 테이블 사용

다음은 OAuth 인증을 사용하여 Iceberg REST 카탈로그 API를 통해 Azure Databricks 테이블에 액세스하도록 Apache Spark를 구성하는 방법의 예입니다.

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing Uniform tables in Unity Catalog
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg-rest",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential":"<oauth_client_id>:<oauth_client_secret>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"

다음 변수를 바꿉니다.

  • <uc-catalog-name>: 테이블을 포함하는 Unity 카탈로그의 이름입니다.
  • <spark-catalog-name>: Spark 세션에서 카탈로그를 할당하려는 이름입니다.
  • <workspace-url>: Azure Databricks 작업 영역의 URL입니다.
  • <oauth_client_id>: 인증 주체에 대한 OAuth 클라이언트 ID입니다.
  • <oauth_client_secret>: 인증 주체에 대한 OAuth 클라이언트 암호입니다.

이러한 구성을 사용하면 Apache Spark를 사용하여 Unity 카탈로그의 테이블을 쿼리할 수 있습니다. 여러 카탈로그의 테이블에 액세스하려면 각 카탈로그를 별도로 구성해야 합니다.

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

  • "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"실행하는 경우에만 이 필요합니다.

  • Azure Databricks는 모든 테이블에 클라우드 개체 스토리지를 사용합니다. iceberg-spark-runtime JAR을 Spark 패키지로 추가해야 합니다.

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • 하늘빛: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    자세한 내용은 SparkIceberg AWS 통합에 대한 설명서 참조하세요.

    메모

    이러한 구성은 Azure Databricks에서 Iceberg 테이블에 액세스할 때 필요하지 않습니다. 외부 Iceberg JAR을 Azure Databricks 클러스터에 로드하는 것은 지원되지 않습니다.

Snowflake를 사용하여 Azure Databricks 테이블 읽기

다음은 Snowflake가 Unity 카탈로그의 Iceberg REST 카탈로그에 연결하여 Azure Databricks 테이블을 읽을 수 있도록 하는 권장 구성 설정의 예입니다.

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
    WAREHOUSE = '<uc-catalog-name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

다음 변수를 바꿉니다.

  • <catalog-integration-name>: Snowflake에 등록된 카탈로그를 할당하려는 이름입니다.
  • <uc-schema-name>: 액세스해야 하는 Unity 카탈로그의 스키마 이름입니다.
  • <uc-catalog-name>: 액세스해야 하는 Unity 카탈로그의 카탈로그 이름입니다.
  • <workspace-url>: Azure Databricks 작업 영역의 URL입니다.
  • <token>: 통합을 구성하는 주체의 PAT 토큰입니다.

PyIceberg에서 Azure Databricks 테이블 사용

다음은 PyIceberg가 Unity 카탈로그의 Iceberg REST 카탈로그에 연결하여 Azure Databricks 테이블에 액세스할 수 있도록 하는 구성 설정의 예입니다.

catalog:
  unity_catalog:
    uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
    warehouse: <uc-catalog-name>
    token: <token>

다음 변수를 바꿉니다.

  • <workspace-url>: Azure Databricks 작업 영역의 URL입니다.
  • <uc-catalog-name>: 액세스해야 하는 Unity 카탈로그의 카탈로그 이름입니다.
  • <token>: 통합을 구성하는 주체의 PAT 토큰입니다.

PyIceberg REST 카탈로그 구성에 대한 설명서를 참조하세요.

REST API curl 예제

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

curl -X GET -H "Authorization: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg-rest/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시간입니다. 성능을 향상시키려면 클라이언트가 새 자격 증명을 요청하기 전에 만료 시간까지 자격 증명을 캐시합니다.