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

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

レイクハウスフェデレーションを使用して Oracle データベースに接続するには、 Databricks Unity Catalogメタストアに次のものを作成する必要があります (2024 年 3 月 6 日以降に作成されたワークスペースには、すでにUnity Catalogメタストア プロビジョニングが自動的に作成されています)。

• Oracle データベースへの接続。
• OracleUnity Catalog Unity Catalogデータベースを にミラーリングする フォーリンカタログDatabricks 。これにより、 クエリ構文とデータガバナンスツールを使用してデータベースへの ユーザーアクセスを管理できます。

要件

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

Databricks の要件

ワークスペースの要件：

• Unity Catalogのワークスペースが有効になっています。2024年3月6日以降に作成されたワークスペースは、自動メタストアのプロビジョニングを含め、Unity Catalog が自動的に有効になります。自動有効化よりも前に作成され、Unity Catalog がまだ有効になっていないワークスペースの場合を除き、メタストアを手動で作成する必要はありません。Unity Catalog の概要を参照してください。

コンピュートの要件：

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

必要な権限：

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

追加の権限要件は、以下の各タスクベースのセクションに記載しています。

Oracleの要件

ネイティブネットワーク暗号化を使用する接続では、サーバー側の NNE を有効にする必要があります（最低でも ACCEPTED レベル）。Oracle ドキュメントの「Configuring Network Data Encryption」を参照してください。これは TLS を使用する接続には適用されません。

Databricks 接続を作成する

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

注記

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

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

Catalog Explorer

1. 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 エンコードされた公開証明書。defaultのトラストストアに存在しないプライベートまたは内部認証局からの証明書をサーバーが提示する場合に指定します。ユーザー提供のサーバー証明書には、Transport Layer Securityの 暗号化プロトコル が必要です。ホスト名の検証は TLS ハンドシェイクの一部として実行されます。証明書のホスト名が要求されたホスト名と一致しない場合、接続は失敗します。
   • Timezone as region : オプション。defaultで有効になります。接続がセッションのタイムゾーンを名前付きリージョン（有効）または固定の UTC オフセット（無効）として Oracle に報告するかどうかを制御します。timezone region not found エラーに対処するためだけに無効にします。ORA-01882: timezone region not found を参照してください。

9. 接続の作成 をクリックします。

10. [カタログの基本 ] ページで、フォーリンカタログの名前を入力します。フォーリンカタログは、外部データ・システム内のデータベースをミラーリングするため、 Databricks と Unity Catalogを使用して、そのデータベース内のデータへのアクセスをクエリおよび管理できます。

11. （オプション）[ 接続をテスト ]をクリックして、動作することを確認します。

12. [ カタログを作成 ] をクリックします。

13. [ アクセス ] ページで、作成したカタログにユーザーがアクセスできるワークスペースを選択します。[ すべてのワークスペースにアクセス権がある ] を選択するか、[ ワークスペースに割り当て ] をクリックし、ワークスペースを選択して [ 割り当て] をクリックします。

14. カタログ内のすべてのオブジェクトへのアクセスを管理できる 所有者 を変更します。テキスト ボックスにプリンシパルの入力を開始し、返された結果でプリンシパルをクリックします。

15. カタログに対する 権限を付与 します。[ 許可 ] をクリックします。

    1. カタログ内のオブジェクトにアクセスできる プリンシパル を指定します。テキスト ボックスにプリンシパルの入力を開始し、返された結果でプリンシパルをクリックします。

    2. 各プリンシパルに付与する 権限プリセット を選択します。デフォルトでは、すべてのアカウントユーザーに BROWSE が付与されます。

       • ドロップダウンメニューから「 データ閲覧者 」を選択して、カタログ内のオブジェクトに対する read 権限を付与します。
       • ドロップダウンメニューから「 データエディタ 」を選択して、カタログ内のオブジェクトに対する read 権限と modify 権限を付与します。
       • 付与する権限を手動で選択します。

    3. 付与 をクリックします。

16. 次へ をクリックします。

17. [メタデータ] ページで、タグのキーと値のペアを指定します。詳細については、「Unity Catalog セキュリティ保護可能なオブジェクトにタグを適用する」を参照してください。

18. （オプション）コメントを追加します。

19. 保存 をクリックします。

SQL

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

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（defaultはtrue）など）または固定UTCオフセット（-08:00（false）など）として報告するかどうかを制御します。timezone region not foundのエラーを回避するためだけに、falseに設定します。ORA-01882: timezone region not foundを参照してください。

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

SQL

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 ハンドシェイク中にサーバーの ID を検証するには (たとえば、Oracle サーバーがdefaultのトラストストアにないプライベートまたは内部の認証局からの証明書を提示する場合など)、サーバーの PEM エンコード済み証明書を userProvidedServerCertificate オプションに渡します。ユーザー提供のサーバー証明書では、encryption_protocol が TLS に設定されている必要があります。

SQL

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 コマンドでプレーンテキスト文字列を使用する必要がある場合は、 $ を \でエスケープして文字列を切り捨てないようにしてください。 たとえば、 \$のようになります。

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

フォーリンカタログの作成

注記

UI を使用してデータソースへの接続を作成する場合は、フォーリンカタログの作成が含まれているため、この手順をスキップできます。

フォーリンカタログは、外部データシステム内のデータベースをミラーリングするため、DatabricksとUnity Catalogを使用して、そのデータベース内のデータへのアクセスを管理できます。フォーリンカタログを作成するには、すでに定義されているデータソースへの接続を使用します。

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

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

Catalog Explorer

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

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

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

3. 「カタログの作成」のフォーリンカタログの作成手順に従います。

SQL

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

• <catalog-name>：Databricksのカタログの名前。
• <connection-name>: データソース、パス、およびアクセス認証情報を指定する 接続オブジェクト 。
• <service-name>: Databricks のカタログとしてミラーリングするサービス名。

SQL

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

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

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

押し下げ	サポートされているコンピュート
集計	すべてのコンピュート
算術演算子 (たとえば、+、-、*、%、/) — ANSI が無効になっている場合はサポートされません	すべてのコンピュート
Boolean 演算子 (たとえば、=、<=>、<、<=、>、>=)	すべてのコンピュート
含む、開始、終了	すべてのコンピュート
フィルター	すべてのコンピュート
上限	すべてのコンピュート
数学関数 (ABS、FLOOR — 部分的にサポート、フィルター式のみ)	すべてのコンピュート
その他の関数 （例：Alias、Cast、SortOrder — 部分的にサポート、フィルター式のみ）	すべてのコンピュート
offset	すべてのコンピュート
予測	すべてのコンピュート
ソート、制限と併用する場合	すべてのコンピュート
文字列関数 (UPPER、LOWER、CHAR_LENGTH、TRIM、RTRIM、LTRIM、CONCAT、RPAD、LPAD — 部分的にサポート、フィルター式のみ)	すべてのコンピュート
テーブルのJOIN	Databricks Runtime 17.2以降とSQLウェアハウスコンピュートに対応しています。このプッシュダウン機能はパブリックプレビュー版です。 プレビュー ページで 「フェデレーションクエリのプッシュダウンに参加」の トグルを有効にしてください。
ウィンドウ関数	サポートされていません

押し下げ	サポートされているコンピュート
集計	すべてのコンピュート
算術演算子 (たとえば、+、-、*、%、/) — ANSI が無効になっている場合はサポートされません	すべてのコンピュート
Boolean 演算子 (たとえば、=、<=>、<、<=、>、>=)	すべてのコンピュート
含む、開始、終了	すべてのコンピュート
フィルター	すべてのコンピュート
上限	すべてのコンピュート
数学関数 (ABS、FLOOR — 部分的にサポート、フィルター式のみ)	すべてのコンピュート
その他の関数 （例：Alias、Cast、SortOrder — 部分的にサポート、フィルター式のみ）	すべてのコンピュート
offset	すべてのコンピュート
予測	すべてのコンピュート
ソート、制限と併用する場合	すべてのコンピュート
文字列関数 (UPPER、LOWER、CHAR_LENGTH、TRIM、RTRIM、LTRIM、CONCAT、RPAD、LPAD — 部分的にサポート、フィルター式のみ)	すべてのコンピュート
テーブルのJOIN	Databricks Runtime 17.2以降とSQLウェアハウスコンピュートに対応しています。このプッシュダウン機能はパブリックプレビュー版です。 プレビュー ページで 「フェデレーションクエリのプッシュダウンに参加」の トグルを有効にしてください。
ウィンドウ関数	サポートされていません

データ型マッピング

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

オラクルタイプ	Spark タイプ
TIMESTAMP WITH TIMEZONE, TIMESTAMP WITH LOCAL TIMEZONE	TimestampType
DATE, TIMESTAMP	TimestampType/ TimestampNTZType *
NUMBER, FLOAT	DecimalType**
BINARY FLOAT	FloatType
BINARY DOUBLE	DoubleType
CHAR、NCHAR、VARCHAR2、 NVARCHAR2	StringType

オラクルタイプ	Spark タイプ
TIMESTAMP WITH TIMEZONE, TIMESTAMP WITH LOCAL TIMEZONE	TimestampType
DATE, TIMESTAMP	TimestampType/ TimestampNTZType *
NUMBER, FLOAT	DecimalType**
BINARY FLOAT	FloatType
BINARY DOUBLE	DoubleType
CHAR、NCHAR、VARCHAR2、 NVARCHAR2	StringType

* DATEとTIMESTAMPは、 spark.sql.timestampType = TIMESTAMP_LTZ (デフォルト) の場合、Spark TimestampTypeにマッピングされます。spark.sql.timestampType = TIMESTAMP_NTZの場合、それらはTimestampNTZTypeにマッピングされます。

**精度を指定せずにNUMBER指定すると、Spark では純粋な浮動小数点 Decimal がサポートされていないため、 DecimalType(38, 10)にマッピングされます。

トラブルシューティング

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

タイムゾーン値が Etc/UTC でない Oracle インスタンス 11.2.0.3.0 以降に接続すると、接続がエラー ORA-01882: timezone region not found で失敗する可能性があります。これは、接続時に Oracle サーバーがレポートされた名前付きタイムゾーン領域を認識しない場合に発生します。

このエラーを解決するには、Databricks では次の順序で実行することを推奨しています。

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

ライセンス

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

その他のリソース

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