Google Cloud Lakehouseカタログフェデレーションを有効にする

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。Databricksのプレビューを管理するを参照してください。

Google Cloud レイクハウスカタログフェデレーションを使用すると、Unity Catalog はクラウドストレージから Google Cloud レイクハウスの Iceberg テーブルを直接読み取ることができます。これにより、クエリーフェデレーションよりも優れたパフォーマンスと低コストを実現できる可能性があります。

カタログフェデレーションを使用すると、Unity CatalogはGoogle Cloud Storage（GCS）内のGoogle CloudレイクハウスIcebergテーブルに直接アクセスし、クエリーは完全にDatabricksコンピュート上で実行されます。Google Cloud Lakehouseカタログ内のフォーリンテーブルは読み取り専用です。

Google Cloud Lakehouseフェデレーションでは、専用の GOOGLE_CLOUD_LAKEHOUSE 接続タイプを使用します。これは、BigQueryクエリーフェデレーションとは別の接続タイプです。

フォーリンカタログを作成する際は、Google Cloud Lakehouse warehouse のパスを指定します。Unity Catalog は、その warehouse 配下の名前空間とテーブルを検出し、それらを標準の Unity Catalog 3 レベル名前空間にマッピングします：

Google Cloud Lakehouseオブジェクト	Unity Catalog 名
ウェアハウス	`<foreign-catalog>`
名前空間	`<foreign-catalog>.<schema>`
テーブル	`<foreign-catalog>.<schema>.<table>`

たとえば、テーブル orders を含むネームスペース analytics を持つwarehouseをフェデレーションした場合、そのテーブルはUnity Catalogでは <foreign-catalog>.analytics.orders として表示されます。

始める前に

Google Cloud Lakehouse カタログフェデレーションを設定する前に、以下の要件を確認してください。

ワークスペースの要件：

Google Cloud Lakehouse フェデレーションは、Google Cloud 上の Databricks ワークスペースでのみサポートされています。
ワークスペースで Unity Catalog が有効になっている必要があります。Unity Catalog の起動を参照してください。
この機能はベータ版であるため、ワークスペース管理者が プレビュー ページから有効にする必要があります。「Databricks プレビューの管理」を参照してください。

コンピュートの要件：

Databricksコンピュートでは、Databricks Runtime 19以上を使用する必要があります。

Databricks Runtime 19は、新しいマイナーバージョンとしてではなく、日付付きの更新として機能を受け取る統合ランタイムです。「Databricks Runtime 19」を参照してください。
SQLウェアハウスはProまたはServerlessである必要があります。
専用クラスター（以前のシングルユーザークラスター）はサポートされていません。制限事項を参照してください。

ネットワークの要件:

Google Cloud で VPC Service Controls またはファイアウォールルールを適用している場合は、コントロールプレーンとデータプレーンの両方について、Databricks のエグレス IP 範囲を許可リストに登録する必要があります。レイクハウスフェデレーションのネットワーキングに関する推奨事項を参照してください。

必要な権限：

接続を作成するには、メタストア管理者か、ワークスペースに接続されているUnity Catalogメタストアの CREATE CONNECTION 権限を持つユーザーである必要があります。
フォーリンカタログを作成するには、メタストアに対する CREATE CATALOG 権限が必要です。また、接続の所有者であるか、接続に対する CREATE FOREIGN CATALOG 権限を持っている必要があります。
フォーリンカタログの承認されたパスを入力するには、それらのパスをカバーする外部ロケーションに対する CREATE FOREIGN SECURABLE 特権が必要です。外部ロケーションの所有者は、defaultでこの特権を持っています。

続く各タスクベースのセクションでは、追加のアクセス許可要件を指定しています。

ステップ 1: Google Cloud リソースを設定する

Google Cloudで以下のステップを実行します。このステップでは、Databricks側での操作は不要です。

Google Cloud Lakehouse warehouseを作成します。

warehouse を作成し、それをバックアップする GCS バケットを選択または作成します。たとえば、バケット my-warehouse によってバックアップされる warehouse の warehouseパスは gs://my-warehouse です。
warehouse内にIcebergテーブルを作成します。

Spark、Flink、BigQuery SQLなど、Iceberg互換エンジンを使用します。テーブルがBigQueryから読み取り可能であることを確認します。例:
SQL
```
SELECT * FROM `PROJECT_ID.NAMESPACE.TABLE`;
```
最小権限のサービスアカウントを2つ作成します。

Google Cloud Lakehouse の ID およびアクセス管理 (IAM) ロールは biglake 名前空間を使用するため、以下の表のロールは Google Cloud コンソールの BigLake の下に表示されます。

サービスアカウント	目的	必要な IAM ロール
接続サービスアカウント	カタログメタデータを読み取ります。	`roles/biglake.viewer` プロジェクト上で。
ストレージサービスアカウント	GCS内のテーブルデータを読み取ります。	`roles/storage.objectViewer` GCS バケット上で。テーブルが BigQuery 管理対象である場合は、`roles/bigquery.dataViewer` を追加します。

サービスアカウント	目的	必要な IAM ロール
接続サービスアカウント	カタログメタデータを読み取ります。	`roles/biglake.viewer` プロジェクト上で。
ストレージサービスアカウント	GCS内のテーブルデータを読み取ります。	`roles/storage.objectViewer` GCS バケット上で。テーブルが BigQuery 管理対象である場合は、`roles/bigquery.dataViewer` を追加します。

接続サービスアカウント用のJSONキーを生成します。

Google Cloud コンソールで、接続サービスアカウント用の JSON キーを生成して download します。ステップ 2: 接続の作成で Unity Catalog 接続を作成する際に、このキーを指定します。キーを安全に格納します。

サービスアカウントの作成、IAMロールの割り当て、およびキーの生成に関する手順については、Google Cloud IAMドキュメントを参照してください。

ステップ 2: 接続を作成する

接続では、外部システムにアクセスするためのパスと認証情報を指定します。カタログエクスプローラーを使用するか、Databricksノートブックまたは Databricks SQLクエリーエディタで CREATE CONNECTION SQLコマンドを使用して、接続を作成します。

注記

Databricks REST API または Databricks CLI を使用して接続を作成することもできます。 POST /api/2.1/unity-catalog/connections および Unity Catalog コマンドを参照してください。

必要な権限： メタストア管理者またはCREATE CONNECTION権限を持つユーザー。

Catalog Explorer
SQL

Databricks ワークスペースで、 カタログ をクリックします。
カタログ ペインの上部で、追加アイコンをクリックし、メニューから 接続を作成 を選択します。
接続のセットアップ ウィザードの 接続の基本 ページで、ユーザー・フレンドリーな 接続名 を入力します。
接続の種類 で Google Cloud Lakehouse を選択し、次へをクリックします。
Authentication ページで、ステップ 1: Google Cloud リソースの設定 で作成した接続サービスアカウントの Google Cloud project ID と Service account key JSON を入力します。
（オプション）コメントを追加します。
接続の作成 をクリックします。

ノートブックまたはDatabricks SQLクエリーエディタで次のコマンドを実行します。プレースホルダーの値を置き換えます。

<connection-name>：Databricksにおける接続の名前。
<gcp-project-id>: Google Cloud Lakehouseカタログを含むGoogle CloudプロジェクトID。
<secret-scope> および <secret-key>: 接続サービスアカウントのJSONキーを格納するSecret Scopeとキー。

SQL
CREATE CONNECTION <connection-name> TYPE GOOGLE_CLOUD_LAKEHOUSE
OPTIONS (
  gcp_project_id '<gcp-project-id>',
  service_account_json secret('<secret-scope>','<secret-key>')
);

Databricks では、サービスアカウントキーなどの機密性の高い値には、プレーンテキストの文字列の代わりにシークレットを使用することをお勧めします。シークレットの設定に関する情報については、「シークレット管理」を参照してください。

ステップ3: ストレージ資格情報と外部ロケーションを作成する

Google Cloud Lakehouse テーブルを保持する GCS バケットへのアクセスを管理するために、Unity Catalog でストレージ資格情報と外部ロケーションを構成します。外部ロケーションは、ストレージ資格情報をクラウドストレージコンテナーのパスに関連付ける Unity Catalog のセキュリティ保護可能なオブジェクトです。

少なくとも以下を作成する必要があります。

カタログのメタデータストレージルートをカバーする1つの資格情報と外部ロケーション。この場所にはカタログ内のIcebergテーブルのメタデータが保存されるため、Databricksマネージドサービスアカウントには読み取り/書き込みアクセス権が必要です。これは任意のGCSバケットでかまいません。テーブルバケットに関連している必要はありません。フォーリンカタログを作成する際に、この場所をstorage_rootオプションとして指定します。
テーブルのストレージロケーションをカバーする、1つ以上の資格情報と外部ロケーション。これらは読み取り専用にすることができます。

ストレージ資格情報と外部ロケーションを作成するには、カタログエクスプローラーまたはSQLを使用します。たとえば、SQLを使用して外部ロケーションを作成するには、次のようにします。

SQL
CREATE EXTERNAL LOCATION <name>
URL 'gs://<bucket-path>'
WITH (STORAGE CREDENTIAL <gcp-storage-credential>);

詳細な手順については、Google Cloud Storage (GCS) 外部ロケーションへの接続を参照してください。

ステップ4: フォーリンカタログを作成する

Google Cloud レイクハウスカタログをミラーリングするフォーリンカタログを使用すると、Databricks および Unity Catalog を使用して、そのテーブルのクエリーやアクセス管理を行うことができます。フォーリンカタログを作成するには、ステップ 2: 接続の作成で作成した接続を使用します。

カタログエクスプローラーを使用するか、DatabricksノートブックまたはDatabricks SQLクエリーエディターで CREATE FOREIGN CATALOG SQLコマンドを使用して、フォーリンカタログを作成します。

必要な権限： メタストアの CREATE CATALOG 権限、接続の所有権または接続の CREATE FOREIGN CATALOG 権限。

Catalog Explorer
SQL

Databricks ワークスペースで、[カタログ]をクリックして カタログエクスプローラー を開きます。
カタログ ペインの上部で、追加アイコンをクリックし、メニューから[ カタログを追加 ]を選択します。
カタログ名 を入力し、カタログの タイプ で外部を選択します。
ドロップダウンメニューから、ステップ 2: 接続の作成で作成した Connection を選択します。
warehouse に、フェデレーションする Google Cloud Lakehouse warehouse のパスを入力します。クラウド Storage warehouse には gs:// パスを、BigQuery warehouse には bq:// パスを使用します。
承認されたパス に、カタログからアクセス可能なクラウドストレージパスを入力します。これらのパス配下のテーブルのみ、フォーリンカタログ経由でクエリーできます。パスは外部ロケーションでカバーされている必要があります。「許可されたパスとは」を参照してください。

カタログの作成後に、承認パスを編集できます。
Storage location フィールドで、このカタログ内の Iceberg テーブルのメタデータを保存する書き込み可能な GCS の場所を指定します。
[ カタログを作成 ] をクリックします。
プロンプトに従って、ワークスペースへのアクセス権、所有者、および権限を割り当てます。

ノートブックまたはDatabricks SQLクエリーエディタで次のコマンドを実行します。括弧内の項目はオプションです。プレースホルダーの値を置き換えます。

<catalog-name>：Databricksのカタログの名前。
<connection-name>：ステップ 2: 接続を作成するで作成した接続の名前。
<warehouse-path>：Google Cloud Lakehouse warehouse のパス。クラウド Storage warehouse の場合は gs:// パスを、BigQuery warehouse の場合は bq:// パスを使用します。
<path1>,<path2>：カタログを介してアクセス可能なクラウドストレージパス。パスは外部ロケーションでカバーされている必要があります。「許可されたパスとは」を参照してください。
<storage-location>: カタログメタデータが保存される書き込み可能なGCSの場所。

SQL
CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name>
USING CONNECTION <connection-name>
OPTIONS (
  warehouse '<warehouse-path>',
  authorized_paths '<path1>,<path2>',
  storage_root '<storage-location>'
);

Unity Catalogは、カタログ配下のすべての名前空間とテーブルを検出します。

Google Cloud Lakehouseの名前空間は、Unity Catalogのスキーマになります。
Google Cloud Lakehouse Iceberg テーブルは、Unity Catalog のフォーリンテーブルになります。

権限を付与し、カタログをクエリーする

カタログフェデレーションを設定した後、ユーザーがフェデレーションテーブルにアクセスするには、適切な Unity Catalog の権限が必要です：

すべてのユーザーは、カタログおよびスキーマに対して、それぞれ USE CATALOG 権限と USE SCHEMA 権限が必要です。
フェデレーテッドテーブルから読み取るには、ユーザーに SELECT 権限が必要です。

Unity Catalog の権限とそれらの付与方法の情報については、「Unity Catalog での権限の管理」を参照してください。

権限を付与した後、ユーザーは Databricks からフォーリンテーブルをクエリーできます：

SQL
SELECT * FROM <catalog-name>.<schema>.<table>;

属性ベースおよびきめ細かなアクセス制御

フォーリンテーブルは、属性ベースのアクセス制御（ABAC）およびきめ細かなアクセス制御（FGAC）をサポートしています。カタログエクスプローラーまたは ALTER TABLE ... SET TAGS コマンドを使用してタグを追加します。Unity Catalog のセキュリティ保護可能なオブジェクトへのタグの適用を参照してください。

制限事項

Google Cloud Lakehouseカタログフェデレーションには、以下の制限があります。

スキーマ名とテーブル名は、標準の Unity Catalog の命名制限に従います。Databricks では、ピリオド (.)、スペース ()、またはスラッシュ (/) を含む名前はサポートされていません。
Google Cloud Lakehouseカタログ内のフォーリンテーブルは読み取り専用です。
TIMEタイプの列を含むテーブルはサポートされていません。
GCS バケットはシングルリージョンである必要があります。マルチリージョンおよびデュアルリージョンのバケットはサポートされていません。
専用クラスター (以前のシングルユーザークラスター) はサポートされていません。

Iceberg 関連の制限事項については、「制限事項」を参照してください。

トラブルシューティング

次のセクションでは、一般的なエラーとその解決策について説明します。

`Catalog not found` または `Failed to load catalog`

一般的な原因：

warehouse オプションは、Google Cloud プロジェクト内の Google Cloud Lakehouse warehouseパスと一致しません。
接続サービスアカウントには、プロジェクトに対する roles/biglake.viewer ロールが不足しています。

テーブルデータの読み取り時の `403 Forbidden`

一般的な原因：

ストレージサービスアカウントには、GCS バケットに対する roles/storage.objectViewer ロールが不足しています。
テーブルが BigQuery 管理の場合、ストレージサービスアカウントにも roles/bigquery.dataViewer ロールが不足しています。

`DBR version not supported`

コンピュートの Databricks Runtime バージョンが、サポートされている最小バージョンを下回っています。Databricks Runtime 19以降を使用してください。「開始する前に」を参照してください。

スキーマは表示されるがテーブルが表示されない

外部ロケーションがテーブルの存在するストレージパスをカバーしていること、およびauthorized_pathsオプションがテーブルが実際に使用するすべてのバケットパスをカバーしていることを確認してください。「ステップ3：ストレージ資格情報と外部ロケーションの作成」を参照してください。

接続を作成する際の`Authentication failed`

サービスアカウントキーのJSONが無効であるか期限切れであるか、またはサービスアカウントにroles/biglake.viewerロールが不足しています。Google Cloudコンソールでキーを再生成し、サービスアカウントのロールを確認してください。ステップ 1: Google Cloudリソースを設定するを参照してください。

始める前に​

ステップ 1: Google Cloud リソースを設定する​

ステップ 2: 接続を作成する​

ステップ3: ストレージ資格情報と外部ロケーションを作成する​

ステップ4: フォーリンカタログを作成する​

権限を付与し、カタログをクエリーする​

属性ベースおよびきめ細かなアクセス制御​

制限事項​

トラブルシューティング​

Catalog not found または Failed to load catalog​

テーブルデータの読み取り時の 403 Forbidden​

DBR version not supported​

スキーマは表示されるがテーブルが表示されない​

接続を作成する際のAuthentication failed​