델타 클라이언트에서 Databricks 테이블에 액세스

이 페이지에서는 Unity REST API를 사용하여 외부 델타 클라이언트에서 Unity 카탈로그 관리 및 외부 테이블을 만들고 읽고 쓰는 방법을 설명합니다. 지원되는 통합의 전체 목록은 Unity 카탈로그 통합을 참조하세요.

Unity REST API를 사용하여 만들기, 읽기 및 쓰기

Unity REST API는 외부 클라이언트가 Unity 카탈로그에 등록된 테이블에 대한 만들기, 읽기 및 쓰기 권한을 제공합니다. 작업 영역 URL을 엔드포인트로 사용하여 액세스를 구성합니다. 다음 표 형식에 액세스할 수 있습니다.

* 카탈로그 커밋이 있는 관리되는 델타 테이블에 대해 지원됩니다.

요구 사항

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

또한 Unity REST API를 사용하여 델타 클라이언트의 테이블에 대한 액세스를 구성하려면 다음 구성 단계를 완료해야 합니다.

• 메타스토어에 외부 데이터 액세스 사용하도록 설정합니다. 메타스토어에서 외부 데이터 액세스 사용을 참조하세요.
• 외부적으로 데이터에 액세스하는 주체에게 개체가 EXTERNAL USE SCHEMA 포함된 스키마에 대한 권한을 부여합니다. 주체에 Unity 카탈로그 권한 부여하기를 참조하세요.
• 경로를 통해 액세스하는 외부 테이블의 경우: 테이블 경로가 포함된 외부 위치에 대해 EXTERNAL USE LOCATION 주체에게 권한을 부여합니다. 주체에 Unity 카탈로그 권한 부여하기를 참조하세요.
• 주체에 적절한 권한이 있는지 확인합니다.
  • SELECT 테이블에서의 읽기 작업
  • MODIFY 쓰기를 위한 테이블에
  • CREATE 테이블 생성용 스키마에서
  • 관리되는 델타 테이블에 대한 외부 쓰기의 경우 작성되는 테이블에 카탈로그 커밋 이 사용하도록 설정되어 있는지 확인합니다.
• 다음 방법 중 하나를 사용하여 인증합니다.
  • PAT(개인용 액세스 토큰): Azure Databricks 리소스에 대한 액세스 권한 부여 참조하세요.
  • OAuth M2M(컴퓨터 간) 인증: 장기 실행 Spark 작업(>1시간)에 대해 자동 자격 증명 및 토큰 새로 고침을 지원합니다. OAuth 사용하여 Azure Databricks 대한 서비스 주체 액세스 권한 인증을 참조하세요.

제한점

• IcebergCompatV3를 사용하여 UniForm 테이블에 대한 외부 액세스는 현재 지원되지 않습니다. 외부에서 UniForm 테이블에 쓴 후 Databricks에서 실행 MSCK REPAIR TABLE 하여 Iceberg 메타데이터를 생성해야 합니다.
• 스키마 변경(예: ALTER TABLE테이블 속성 업데이트 및 테이블 기능 변경)은 현재 외부 클라이언트의 관리되는 테이블에서 지원되지 않습니다.
• 외부 클라이언트는 관리되는 델타 테이블에서 테이블 유지 관리 작업(예: OPTIMIZE, VACUUM및 ANALYZE)을 수행할 수 없습니다.
• 외부 클라이언트는 단순 클론을 만들 수 없습니다.
• 외부 클라이언트는 생성된 열, 기본 열 또는 제약 조건 열이 있는 테이블을 만들 수 없습니다.
• 외부 테이블을 만들 때 Azure Databricks Apache Spark를 사용하여 열 정의가 Apache Spark와 호환되는 형식인지 확인하는 것이 좋습니다. API는 열 사양의 정확성을 확인하지 않습니다. 사양이 Apache Spark와 호환되지 않는 경우 Databricks 런타임이 테이블을 읽을 수 없을 수 있습니다.

PAT 인증을 사용하여 Apache Spark를 사용하여 델타 테이블에 액세스

PAT 인증을 사용하여 Apache Spark를 사용하여 Unity 카탈로그 관리 및 외부 델타 테이블을 읽거나 쓰려면 다음 구성이 필요합니다.

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

다음 변수를 대체합니다.

• <uc-catalog-name>: 테이블을 포함하는 Unity 카탈로그의 이름입니다.
• <token>: 통합을 구성하는 보안 주체를 위한 개인용 액세스 토큰(PAT)입니다.

• <workspace-url>: 작업 영역 ID를 포함한 Azure Databricks workspace URL입니다. 예: adb-1234567890123456.12.azuredatabricks.net.

클라우드 개체 스토리지용 Apache Spark를 구성하는 방법에 대한 자세한 내용은 Unity 카탈로그 OSS 설명서를 참조하세요.

카탈로그 커밋을 사용하여 관리되는 델타 테이블을 만들려면 다음 SQL을 사용합니다.

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported') USING delta;

외부 델타 테이블을 만들려면 다음 SQL을 사용합니다.

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
USING delta
LOCATION <path>;

OAuth 인증을 사용하여 Apache Spark를 사용하여 델타 테이블에 액세스

Azure Databricks OAuth M2M(컴퓨터 대 컴퓨터) 인증도 지원합니다. OAuth는 Unity 카탈로그 인증에 대한 토큰 및 자격 증명 갱신을 자동으로 처리합니다.

외부 Spark 클라이언트에 대한 OAuth 인증에는 다음이 필요합니다.

• Unity Catalog Spark 클라이언트 버전 0.4.1 이상(io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 이상
• Delta Spark 4.2.0 이상
• 적절한 권한이 있는 OAuth M2M 서비스 주체입니다. OAuth 사용하여 Azure Databricks 대한 서비스 주체 액세스 권한 인증을 참조하세요.

OAuth 인증을 사용하여 Apache Spark를 사용하여 Unity 카탈로그 관리 테이블 및 외부 델타 테이블을 만들거나 읽거나 쓰려면 다음 구성이 필요합니다.

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.auth.type": "oauth",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.uri": "<oauth-token-endpoint>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientId": "<oauth-client-id>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientSecret": "<oauth-client-secret>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

다음 변수를 대체합니다.

• <uc-catalog-name>: 테이블을 포함하는 Unity 카탈로그의 이름입니다.
• <oauth-token-endpoint>: OAuth 토큰 엔드포인트 URL입니다. 이 URL을 생성하려면 다음을 수행합니다.
  1. Azure Databricks 계정 ID를 찾습니다. 계정 ID 찾기를 참조하세요.
  2. 다음 형식을 사용합니다. https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/token
• <oauth-client-id>: 서비스 주체에 대한 OAuth 클라이언트 ID입니다. OAuth 사용하여 Azure Databricks 대한 서비스 주체 액세스 권한 인증을 참조하세요.
• <oauth-client-secret>: 서비스 주체에 대한 OAuth 클라이언트 암호입니다. OAuth 사용하여 Azure Databricks 대한 서비스 주체 액세스 권한 인증을 참조하세요.

• <workspace-url>: 작업 영역 ID를 포함한 Azure Databricks workspace URL입니다. 예: adb-1234567890123456.12.azuredatabricks.net.

API를 사용하여 델타 테이블 만들기

Unity 카탈로그 REST API를 사용하여 외부 델타 테이블을 만들려면 다음 단계를 수행합니다.

1단계: 테이블 만들기 API에 대한 POST 요청 만들기

다음 API 요청을 사용하여 Unity 카탈로그에 테이블 메타데이터를 등록합니다.

curl --location --request POST 'https://<workspace-url>/api/2.0/unity-catalog/tables/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "<table-name>",
  "catalog_name": "<uc-catalog-name>",
  "schema_name": "<schema-name>",
  "table_type": "EXTERNAL",
  "data_source_format": "DELTA",
  "storage_location": "<path>",
  "columns": [
    {
      "name": "id",
      "type_name": "LONG",
      "type_text": "bigint",
      "type_json": "\"long\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 0,
      "nullable": true
    },
    {
      "name": "name",
      "type_name": "STRING",
      "type_text": "string",
      "type_json": "\"string\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 1,
      "nullable": true
    }
  ]
}'

다음 변수를 대체합니다.

• <workspace-url>: Azure Databricks 작업 영역의 URL
• <token>: API 호출을 만드는 보안 주체에 대한 토큰
• <uc-catalog-name>: 외부 테이블을 포함할 Unity 카탈로그의 카탈로그 이름
• <schema-name>: 테이블을 만들 카탈로그 내의 스키마 이름
• <table-name>: 외부 테이블의 이름
• <path>: 테이블 데이터에 대한 정규화된 경로

2단계: 델타 테이블 위치 초기화

위의 API 호출은 :[UC]에 테이블을 등록하지만 스토리지 위치에 델타 파일을 만들지는 않습니다. 테이블 위치를 초기화하려면 Spark를 사용하여 빈 Delta 테이블을 작성합니다.

이 단계에서 사용되는 스키마는 API 요청에 제공된 열 정의와 정확히 일치해야 합니다.

from pyspark.sql.types import StructType, StructField, StringType, LongType

# Define schema matching your API call
schema = StructType([
    StructField("id", LongType(), True),
    StructField("name", StringType(), True)
])

# Create an empty DataFrame and initialize the Delta table
empty_df = spark.createDataFrame([], schema)
empty_df.write \
    .format("delta") \
    .mode("overwrite") \
    .save("<path>")