メインコンテンツまでスキップ
に最終更新

DeltaクライアントからDatabricksテーブルにアクセスする

このページでは、Unity REST API使用して、外部DeltaクライアントからUnity Catalog管理対象および外部テーブルを作成、読み取り、書き込む方法について説明します。 サポートされている統合機能の完全なリストについては、 Unity Catalog統合機能を参照してください。

Unity REST API を使用して作成、読み取り、書き込みを行います。​

備考

ベータ版

DeltaクライアントからのUnity Catalogマネージドテーブルの作成と書き込みはベータ版です。 外部クライアントへのサポートは限定的です。

Unity REST API 、外部クライアントがUnity Catalogに登録されているテーブルを作成、読み取り、書き込みアクセスできるようにします。 ワークスペースのURLをエンドポイントとして使用してアクセスを設定します。以下のテーブルタイプが利用可能です。

テーブルタイプ

読み取り

書き込み

作成

Deltaをマネージド

はい

はい*

はい*

外部Delta

はい

はい

はい

*カタログコミット付きのマネージドDeltaテーブルでサポートされます。

必要条件​

Databricks 、 Unity Catalogの一部として、テーブルへのUnity REST APIアクセスをサポートしています。 これらのエンドポイントを使用するには、ワークスペースでUnity Catalog有効にする必要があります。

Unity REST APIを使用してDeltaクライアントからテーブルへのアクセスを設定するには、以下の設定項目も完了する必要があります。

制限事項​

  • IcebergCompatV3を使用したUniFormテーブルへの外部アクセスは、現在サポートされていません。UniFormテーブルに外部から書き込んだ後は、DatabricksでMSCK REPAIR TABLE実行してIcebergメタデータを生成する必要があります。
  • マネージドテーブルでは、外部クライアントからのスキーマ変更 (例: ALTER TABLE )、テーブル プロパティの更新、およびテーブル機能の変更は現在サポートされていません。
  • 外部クライアントは、管理対象の Delta テーブルに対して、 OPTIMIZE 、 VACUUM 、 ANALYZEなどのテーブルメンテナンス操作を実行できません。
  • 外部クライアントは浅いクローンを作成することはできません。
  • 外部クライアントは、生成列、デフォルト列、または制約列を含むテーブルを作成することはできません。
  • 外部テーブルを作成する際は、列定義がApache Sparkと互換性のある形式になっていることを確認するために、DatabricksはApache Sparkを使用することを推奨しています。APIは列指定の正当性を検証しません。仕様がApache Sparkと互換性がない場合、Databricks Runtimeはテーブルを読み取れない可能性があります。

PAT認証を使用してApache SparkでDeltaテーブルにアクセスする​

Apache SparkでPAT認証を使用してUnity Catalog管理テーブルおよび外部Deltaテーブルへの読み書きを行うには、以下の設定が必要です。

"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",
"spark.jars": "/path/to/gcs-connector-3.0.2-shaded.jar"
注記

GCS コネクタ JAR ファイルを別途ダウンロードする必要があります。ダウンロードしたgcs-connector-3.0.2-shaded.jarファイルを指すようにspark.jarsパスを更新します。

次の変数を代入します。

  • <uc-catalog-name>: テーブルを含む Unity Catalog のカタログの名前。

  • <token>: 統合を構成するプリンシパル用の個人アクセスウイルス (PAT)。

  • <workspace-url>: DatabricksワークスペースのURL 。例えば、 cust-success.cloud.databricks.com 。

注記

上記に表示されているパッケージのバージョンは、このページが最後に更新された時点でのものです。より新しいバージョンが利用可能になっている可能性があります。パッケージのバージョンが、お使いのSparkのバージョンと互換性があることを確認してください。

クラウド オブジェクト ストレージ用に Apache Spark を構成する方法の詳細については、 Unity Catalog OSS ドキュメントを参照してください。

重要

カタログコミットが有効になっているテーブルの読み取り、書き込み、または作成を行うには、Databricks Runtime 16.4以降が必要です。既存のテーブルでカタログコミットを有効または無効にするには、Databricks Runtime 18.0以降が必要です。

カタログコミットを使用してマネージドDeltaテーブルを作成するには、次のSQLを使用します。

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

外部Deltaテーブルを作成するには、次のSQLを使用します。

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

OAuth認証を使用してApache SparkでDeltaテーブルにアクセスする​

Databricksは、OAuthによるマシン間（M2M）認証もサポートしています。OAuth 、 Unity Catalog認証の認証情報の更新を自動的に処理します。

外部 Spark クライアントの OAuth 認証には次のものが必要です。

OAuth認証を使用してApache SparkでUnity Catalogマネージドテーブルと外部Deltaテーブルを作成、読み取り、または書き込みするには、次の設定が必要です。

"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",
"spark.jars": "/path/to/gcs-connector-3.0.2-shaded.jar"
注記

GCS コネクタ JAR ファイルを別途ダウンロードする必要があります。ダウンロードしたgcs-connector-3.0.2-shaded.jarファイルを指すようにspark.jarsパスを更新します。

次の変数を代入します。

注記

上記に表示されているパッケージのバージョンは、このページが最後に更新された時点でのものです。より新しいバージョンが利用可能になっている可能性があります。パッケージのバージョンが、お使いのSparkのバージョンと互換性があることを確認してください。

APIを使用してDeltaテーブルを作成する​

Unity Catalog REST APIを使用して外部Deltaテーブルを作成するには、次のステップに従います。

ステップ 1: Create Table APIに POST リクエストを送信します。​

次のAPIリクエストを使用して、 Unity Catalogにテーブル メタデータを登録します。

Bash
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>： DatabricksワークスペースのURL
  • <token>API呼び出しを行うプリンシパルのトークン
  • <uc-catalog-name>: 外部テーブルを含むUnity Catalog内のカタログの名前
  • <schema-name>テーブルが作成されるカタログ内のスキーマ名
  • <table-name>: 外部テーブルの名前
  • <path>テーブルデータへの完全修飾パス

ステップ 2: Deltaテーブルの場所を初期化します​

上記のAPI呼び出しは :[UC] のテーブルを登録しますが、ストレージ場所にDeltaファイルを作成しません。 テーブルの場所を初期化するには、Sparkを使用して空のDeltaテーブルを作成します。

このステップで使用するスキーマは、APIリクエストで提供される列定義と完全に一致する必要があります。

Python

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>")
注記

外部クライアント向けのテーブル作成APIには、以下の制限事項があります。

  • 外部Deltaテーブルのみがサポートされています（ "table_type": "EXTERNAL"と"data_source_format": "DELTA" ）。

  • 以下の項目のみ入力可能です。

    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties

  • 列マスクはサポートされていません。

このページの見出し