次の方法で共有

外部クライアントから外部差分テーブルを作成する

Von Bedeutung

この機能は パブリック プレビュー段階です。

このページでは、外部クライアントとシステムから Delta Lake によってサポートされる Unity カタログ外部テーブルを作成する方法について説明します。

注

Databricks では、Apache Spark を使用して外部テーブルを作成し、列定義が Apache Spark と互換性のある形式であることを確認することをお勧めします。 API では、列の指定の正確性は検証されません。 仕様が Apache Spark と互換性がない場合、Databricks Runtime がテーブルを読み取ることができない可能性があります。

要求事項

  • メタストア 外部データ アクセス を有効にします。 メタストアで外部データ アクセスを有効にする を参照してください。

  • 統合を構成するプリンシパルに特権を付与する

    • EXTERNAL USE SCHEMA オブジェクトを含むスキーマに対する特権。
    • EXTERNAL USE LOCATION パスを含む外部の場所に対する特権。 プリンシパル Unity カタログ権限の付与を参照してください。
    • CREATE TABLE アクセス許可、外部の場所に CREATE EXTERNAL TABLE 、親カタログに USE CATALOG 、親スキーマに USE SCHEMA 。

    プリンシパル Unity カタログ権限の付与を参照してください。

Apache Spark、Unity カタログ API、またはその他の外部クライアントを使用して外部テーブルを作成できます。

Apache Spark を使用してデルタ テーブルを作成する

Unity カタログの外部 Delta テーブルを作成するように Apache Spark を構成する設定の例を次に示します。

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.hadoop.fs.s3.impl": "org.apache.hadoop.fs.s3a.S3AFileSystem",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",

次の変数に置き換える:

  • <uc-catalog-name>: テーブルを含む Unity カタログ内のカタログの名前。
  • <workspace-url>: Azure Databricks ワークスペースの URL。
  • <token>: 統合を構成するプリンシパルの OAuth トークン。

Apache Spark と Delta Lake を Unity カタログと連携させるには、少なくとも Apache Spark 3.5.3 と Delta Lake 3.2.1 が必要です。

Apache Spark を起動するときに、次の依存関係を含めます。

--packages "org.apache.hadoop:hadoop-aws:3.3.4,\
io.delta:delta-spark_2.12:3.2.1,\
io.unitycatalog:unitycatalog-spark_2.12:0.2.0"

SQL を使用して外部テーブルを作成できるようになりました。

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

API を使用してデルタ テーブルを作成する

Unity カタログ REST API を使用して外部 Delta テーブルを作成するには、次の手順に従います。

手順 1: Create Table API に POST 要求を行う

Unity カタログにテーブル メタデータを登録するには、次の API 要求を使用します。

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: Delta テーブルの場所を初期化する

上記の API 呼び出しではテーブルが :[UC]に登録されますが、保存場所に Delta ファイルは作成されません。 テーブルの場所を初期化するには、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>")

注

外部クライアント用の Create Table API には、次の制限があります。

  • 外部差分テーブルのみがサポートされます ("table_type": "EXTERNAL" と "data_source_format": "DELTA")。
  • 次のフィールドのみが使用できます。
    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties
  • 列マスクはサポートされていません。
  • Last updated on