Oracle でフェデレーション クエリを実行する

このページでは、Azure Databricks によって管理されていない Oracle データに対してフェデレーション クエリを実行するように Lakehouse Federation を設定する方法について説明します。 Lakehouse フェデレーションの詳細については、「外部データベースとカタログへの接続」を参照してください。

Lakehouse Federation を使用して Oracle データベースに接続するには、Azure Databricks Unity カタログ メタストアで次を作成する必要があります (2023 年 11 月 9 日以降に作成されたワークスペースには、Unity カタログ メタストアが自動的にプロビジョニングされています)。

• Oracle データベースへの接続。
• Unity カタログのクエリ構文とデータ ガバナンス ツールを使用してデータベースへの Azure Databricks ユーザー アクセスを管理できるように、Unity カタログ内の Oracle データベースをミラーリングする 外部カタログ。

Requirements

開始する前に、このセクションの要件を満たしていることを確認します。

Databricks の要件

ワークスペースの要件:

• Unity カタログで有効になっているワークスペース。 2023 年 11 月 9 日以降に作成されたワークスペースは、自動メタストア プロビジョニングを含め、Unity カタログに対して自動的に有効になります。 ワークスペースが自動有効化の前にあり、Unity カタログに対して有効になっていない場合を除き、メタストアを手動で作成する必要はありません。 Unity カタログについて始めに知っておくべきことを参照してください

コンピューティング要件:

• コンピューティング リソースからターゲット データベース システムへのネットワーク接続。 「Lakehouse Federation 向けネットワーク推奨事項」を参照してください。
• Azure Databricks コンピューティングでは、Databricks Runtime 16.1 以降と Standard または Dedicated アクセス モードを使用する必要があります。
• SQL ウェアハウスはプロまたはサーバーレスである必要があり、2024.50 以降を使用する必要があります。

必要なアクセス許可:

• 接続を作成するには、メタストア管理者であるか、ワークスペースにアタッチされている Unity カタログメタストアに対する CREATE CONNECTION 権限を持つユーザーである必要があります。 Unity カタログが自動的に有効になっているワークスペースでは、ワークスペース管理者は既定で CREATE CONNECTION 特権を持っています。
• 外部カタログを作成するには、メタストアに対する CREATE CATALOG 権限を持ち、接続の所有者であるか、接続に対する CREATE FOREIGN CATALOG 特権を持っている必要があります。 Unity カタログが自動的に有効になっているワークスペースでは、ワークスペース管理者は既定で CREATE CATALOG 特権を持っています。

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

Oracle の要件

Native Network Encryption を使用する接続の場合は、サーバー側の NNE (ACCEPTED レベル以上) を有効にする必要があります。 Oracle ドキュメント ネットワーク データ暗号化 の構成を参照してください。 これはTLSを使用する接続には当てはまりません。

Azure Databricks 接続を作成する

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

必要なアクセス許可: メタストア管理者、または CREATE CONNECTION 権限が付与されたユーザー。

カタログ エクスプローラー

1. Azure Databricks ワークスペースで、[データ] アイコンをクリック カタログ。
2. [ [接続] をクリックし、[ 接続] をクリックします。
3. [ 接続の作成 ] ボタンをクリックします。
4. 接続 のセットアップ ウィザードの [接続の基本] ページで、わかりやすい 接続名入力します。
5. Oracle の [接続の種類] を選択します。
6. (省略可能)コメントを追加します。
7. [次へ] をクリックします。
8. 認証 ページで、Oracle インスタンスに対して次のように入力します。
   • ホスト: たとえば、oracle-demo.123456.rds.amazonaws.com
   • ポート: たとえば、1521
   • ユーザー: たとえば、oracle_user
   • パスワード: たとえば、password123
   • 暗号化プロトコル: Native Network Encryption (既定) または Transport Layer Security
   • ユーザー指定のサーバー証明書: 省略可能。 TLSハンドシェイク中にサーバーの本人確認に使われる、OracleインスタンスのPEMエンコードされたパブリック証明書です。 サーバーがデフォルトの信頼ストアにないプライベートまたは内部の証明書発行機関からの証明書を提示した際に提供してください。 ユーザーが提供するサーバー証明書には、Transport Layer Security の暗号化プロトコルが必要です。 ホスト名の検証はTLSハンドシェイクの一部として行われます。 証明書上のホスト名が要求されたホスト名と一致しない場合、接続は失敗します。
   • 地域としてのタイムゾーン:任意。 既定で有効になっています。 接続がセッションタイムゾーンをOracleに名前付きリージョン（有効）として報告するか、固定UTCオフセットとして報告するか（無効）を制御します。 timezone region not foundエラーの回避策としてのみ無効にしてください。 ORA-01882: タイムゾーン地域が見つかりませんを参照してください。
9. [接続の作成] をクリックします。
10. カタログの基本 ページで、外部カタログの名前を入力します。 外部カタログは、外部データ システム内のデータベースをミラー化して、Azure Databricks と Unity Catalog を使用してそのデータベース内のデータへのアクセスを照会および管理できるようにします。
11. (省略可能) テスト接続をクリックして、正常に動作することを確認します。
12. カタログを作成 をクリックします。
13. [Access] ページで、作成したカタログにユーザーがアクセスできるワークスペースを選択します。 [すべてのワークスペースにアクセス権を持たせる] を選択するか、[ワークスペースへの割り当て] をクリックしてワークスペースを選択し、[割り当て] をクリックします。
14. カタログ内のすべてのオブジェクトへのアクセスを管理できる 所有者 を変更します。 テキストボックスに主要項目を入力し、表示された結果からその項目をクリックします。
15. カタログに関する権限 を付与します。 許可をクリックします。
    1. カタログ内のオブジェクトにアクセスできる プリンシパル を指定します。 テキストボックスに主要項目を入力し、表示された結果からその項目をクリックします。
    2. 各プリンシパルに付与する 特権プリセット を選択します。 既定では、すべてのアカウント ユーザーに BROWSE が付与されます。
       • ドロップダウン メニューから [データ 閲覧者 を選択して、カタログ内のオブジェクトに対する read 権限を付与します。
       • ドロップダウン メニュー データ エディター を選択して、カタログ内のオブジェクトに対する read 権限と modify 権限を付与します。
       • 付与する特権を手動で選択します。
    3. [許可] をクリックします。
16. [次へ] をクリックします。
17. [メタデータ] ページで、タグのキーと値のペアを指定します。 詳細については、「Unity カタログのセキュリティ保護可能なオブジェクトにタグを適用する」を参照してください。
18. (省略可能)コメントを追加します。
19. [保存] をクリックします。

SQL

ノートブックまたは Databricks SQL クエリ エディターで次のコマンドを実行します。

CREATE CONNECTION <connection-name> TYPE oracle
OPTIONS (
  host '<hostname>',
  port '<port>',
  user '<user>',
  password '<password>',
  encryption_protocol '<protocol>', -- optional
  timezone_as_region '<true-or-false>' -- optional
);

timezone_as_region 接続がセッションタイムゾーンをOracleに報告する際に、 America/Los_Angeles (true、デフォルト)などの指定リージョンとして報告するか、 -08:00 (false)のような固定UTCオフセットとして報告するかを制御します。 false に設定して、timezone region not found エラーを回避してください。 ORA-01882: タイムゾーン地域が見つかりませんを参照してください。

Databricks では、資格情報などの機密性の高い値にプレーンテキスト文字列ではなく、azure Databricks シークレット 使用することをお勧めします。 例えば次が挙げられます。

CREATE CONNECTION <connection-name> TYPE oracle
OPTIONS (
  host '<hostname>',
  port '<port>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>'),
  encryption_protocol '<protocol>' -- optional
)

TLSハンドシェイク中にサーバーの本人確認を行う場合(例えば、Oracleサーバーがデフォルトの信頼ストアにないプライベートまたは内部証明書機関からの証明書を提示した場合)、 userProvidedServerCertificate オプションでサーバーのPEMでエンコードされた証明書を渡します。 ユーザー提供のサーバー証明書では、encryption_protocol を TLS に設定する必要があります。

CREATE CONNECTION <connection-name> TYPE oracle
OPTIONS (
  host '<hostname>',
  port '<port>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>'),
  encryption_protocol 'TLS',
  userProvidedServerCertificate '<pem-encoded-certificate>'
)

ノートブック SQL コマンドでプレーンテキスト文字列を使用する必要がある場合は、$で \ などの特殊文字をエスケープして文字列を切り捨てないようにします。 例: \$.

シークレットの設定については、「シークレット管理を参照してください。

外部カタログを作成する

外部カタログは、外部データ システム内のデータベースをミラー化して、Azure Databricks と Unity Catalog を使用してそのデータベース内のデータへのアクセスを照会および管理できるようにします。 外部カタログを作成するには、既に定義されているデータ ソースへの接続を使用します。

外部カタログを作成するには、Azure Databricks ノートブックまたは SQL クエリ エディターでカタログ エクスプローラーまたは CREATE FOREIGN CATALOG SQL コマンドを使用できます。 Databricks REST API または Databricks CLI を使用してカタログを作成することもできます。 POST /api/2.1/unity-catalog/catalogs および unity Catalog コマンド を参照してください。

必要な権限: メタストアに対するCREATE CATALOG 権限と、接続の所有権または接続に対する CREATE FOREIGN CATALOG 特権。

カタログ エクスプローラー

1. Azure Databricks ワークスペースで、[データ] アイコンをクリック カタログ をクリックしてカタログ エクスプローラーを開きます。

2. [カタログ] ペインの上部で、[追加] をクリックし、メニューで、[カタログを追加] を選択します。

   または、[クイック アクセス] ページで、[カタログ] ボタンをクリックし、[カタログ の作成] ボタン クリックします。

3. カタログの作成で外部カタログを作成する手順に従います。

SQL

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

• <catalog-name>: Azure Databricks のカタログの名前。
• <connection-name>: データ ソース、パス、アクセス資格情報を指定する 接続オブジェクト。
• <service-name>: Azure Databricks でカタログとしてミラー化するサービス名。

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (service_name '<service-name>');

サポートされているプッシュダウン

次の表に、Oracle でサポートされるプッシュダウン操作と、それぞれに必要なコンピューティングを示します。

Pushdown	サポートされている計算処理
Aggregates	すべての計算処理
算術演算子 (+、-、*、%、/など) — ANSI が無効になっている場合はサポートされません	すべての計算処理
ブール演算子 (=、 <=>、 <、 <=、 >、 >= など)	すべての計算処理
Contains、Startswith、Endswith	すべての計算処理
Filters	すべての計算処理
Limit	すべての計算処理
算術関数 (ABS、FLOOR — 部分サポート、フィルター式のみ)	すべての計算処理
その他の関数 （たとえば Alias、Cast、SortOrder など — 部分的なサポート、フィルター式のみ）	すべての計算処理
Offset	すべての計算処理
Projections	すべての計算処理
制限付きで使用した場合の並べ替え	すべての計算処理
文字列関数 (UPPER、LOWER、CHAR_LENGTH、TRIM、RTRIM、LTRIM、CONCAT、RPAD、LPAD — 部分サポート、フィルター式のみ)	すべての計算処理
Joins	Databricks Runtime 17.2 以降と SQL Warehouse コンピューティング。 このプッシュダウンはパブリック プレビュー段階です。[プレビュー] ページで [フェデレーション クエリのプッシュダウンに参加] トグルを有効にします。
ウィンドウ関数	サポートされていません

データ型のマッピング

Oracle から Spark に読み取ると、データ型は次のようにマップされます。

* DATE TIMESTAMP場合、TimestampTypeは Spark spark.sql.timestampType = TIMESTAMP_LTZにマップされます (既定値)。 TimestampNTZType場合は、spark.sql.timestampType = TIMESTAMP_NTZにマップされます。

** NUMBER 精度を指定しない場合、Spark では純粋な浮動小数点 Decimal がサポートされていないため、DecimalType(38, 10) に変換されます。

Troubleshooting

ORA-01882:タイムゾーン地域が見つかりません

タイムゾーン値が Etc/UTCでないOracleインスタンス11.2.0.3.0以降に接続すると、エラー ORA-01882: timezone region not foundで接続が失敗することがあります。 これは、Oracleサーバーがログイン時に接続が報告する指定されたタイムゾーン地域を認識しない場合に発生します。

このエラーを解決するために、Databricksは以下の方法を順番に推奨しています:

1. Oracleサーバーのタイムゾーンファイルを更新して、地域名を認識するようにしてください。 これが望ましい、恒久的な修正です。 Oracle サポート - ORA-01882 を参照してください。
2. Oracleサーバーを更新できない場合は、 timezone_as_region 接続オプションを falseに設定してください。 接続は地域名の代わりに固定UTCオフセットを報告し、エラーを回避します。 固定オフセットは季節による時刻の変更に対応していないため、TIMESTAMP WITH LOCAL TIME ZONE の値は夏時間に合わせて調整されません。

License

Oracle ドライバーおよびその他の必要な Oracle jar は、クリックなしの FDHUT ライセンスによって管理されます。

その他のリソース

• レイクハウスフェデレーションでプッシュダウンに参加する
• Lakehouse フェデレーションのためのネットワークに関する推奨事項
• remote_query関数を使用して外部データベースにクエリを実行する