`remote_query`関数を使用して外部データベースをクエリする

備考

プレビュー

remote_queryテーブル値関数 (TVF) を使用すると、リモートシステムのネイティブSQL構文を使用して、 Databricks内から外部データベースやデータウェアハウスに対してSQLクエリを直接実行できます。この関数は、クエリフェデレーションの柔軟な代替手段を提供し、リモートデータベースの方言で記述されたクエリを Databricks SQL に変換せずに実行できるようにします。

`remote_query`クエリフェデレーションと比較

次の表は、 remote_query関数とクエリフェデレーションの主な違いをまとめたものです。

属性	`remote_query` function	クエリフェデレーション
クエリ構文	リモートデータベースのネイティブ SQL 方言 (Oracle PL/SQL、BigQuery SQL など) を使用してクエリを記述します。	Databricks SQL 構文を使用してクエリを記述します。Databricks は互換性のある操作を変換し、リモートデータベースにプッシュダウンします。
ユースケース	リモートデータベースの方言で記述された既存の SQL クエリがあり、これを変更せずに実行します。 Databricks SQL では使用できない可能性のあるデータベース固有の関数または構文を使用する必要があります。フォーリンカタログを作成せずに、リモートデータにアドホックアクセスしたい。	Databricks SQL 構文を使用して外部データをクエリします。 Unity Catalogフォーリンカタログを通じて管理されたアクセスを備えた長期的なデータアクセスパターンが必要です。一貫した構文を使用して、複数のソースからのデータを 1 つのクエリに結合します。クエリの作成には Genie アシスタントを使用します。
アクセス制御	ユーザーは接続に対して`USE CONNECTION`権限が必要です。権限はビューを通じて委任できます。	ユーザーには、フォーリンカタログオブジェクトに対するテーブルレベルの権限が必要です。きめ細かな制御。

始める前に

ワークスペースの要件：

Unity Catalogのワークスペースが有効になっています。

コンピュートの要件：

Databricks RuntimeクラスターまたはSQLウェアハウスからターゲットデータベースシステムへのネットワーク接続。レイクハウスフェデレーションのネットワーキングに関する推奨事項を参照してください。
Databricks クラスターでは、Databricks Runtime 17.3 以上を使用する必要があります。
SQLは Pro またはサーバレスであり、バージョン 2025.35 以降を使用する必要があります。

必要な権限：

接続を作成するには、メタストア管理者またはUnity Catalogメタストアに対するCREATE CONNECTION権限を持つユーザーである必要があります。
remote_query関数を使用するには、接続に対するUSE CONNECTION権限、またはその関数をラップするビューに対するSELECT権限が必要です。シングルユーザークラスターでは、接続に対するMANAGE権限も必要です。

接続を作成する

remote_query関数を使用するには、まず外部データベースへの Unity Catalog 接続を作成する必要があります。クエリフェデレーション用の接続がすでに作成されている場合は、それを再利用できます。

remote_query関数は、次の接続タイプへの接続をサポートします。

既存の接続の管理については、「レイクハウスフェデレーションの接続の管理」を参照してください。

接続アクセスを許可する

remote_query関数を使用するには、接続に対するUSE CONNECTION権限 (またはシングルユーザークラスターに対するMANAGE権限) が必要です。

SQL
GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-or-group>;

`remote_query`関数を使用する

remote_query関数は、リモートデータベースに対してクエリを実行し、結果を Databricks SQL クエリで使用できるテーブルとして返します。

構文

SQL
SELECT * FROM remote_query(
  '<connection-name>',
  <option-key> => '<option-value>'
  [, <option-key> => '<option-value>' ...]
)

必須

connection-name: 使用するUnity Catalog接続の名前。

その他に必要なすべての事項は、接続タイプによって異なります。詳細については、コネクタ固有のオプションを参照してください。

コネクタ固有のオプション

利用可能なオプションは接続タイプによって異なります。次の表では、各コネクタのオプションについて説明します。

MySQL、PostgreSQL、SQL Server、Redshift、Teradata

パラメーター	必須	説明
`database`	はい	リモートシステム上のデータベース名。
`query`	はい（または`dbtable` ）	リモートデータベースで実行する SQL クエリ文字列。`dbtable`では使用できません。
`dbtable`	はい（または`query` ）	クエリするテーブル名。`query`では使用できません。
`fetchsize`	No	ラウンドトリップごとに取得する行数。値を大きくするとパフォーマンスは向上しますが、メモリの使用量も多くなります。大丈夫: 0 (ドライバーを使用してください)。
`partitionColumn`	No	並列データフェッチに使用する均一に分散された値を持つ列。`lowerBound` 、 `upperBound` 、 `numPartitions`と一緒に使用する必要があります。`query`オプションと併用することはできません。
`lowerBound`	No	パーティション列の最小値。`partitionColumn` 、 `upperBound` 、 `numPartitions`と一緒に使用する必要があります。
`upperBound`	No	パーティション列の最大値。`partitionColumn` 、 `lowerBound` 、 `numPartitions`と一緒に使用する必要があります。
`numPartitions`	No	データの取得に使用する並列接続の数。あまり高く（数百）設定しないでください。`partitionColumn` 、 `lowerBound` 、 `upperBound`と一緒に使用する必要があります。

注記

パーティション問題を使用する場合は、4 つすべて ( partitionColumn 、 lowerBound 、 upperBound 、 numPartitions ) を一緒に指定する必要があり、 queryの代わりにdbtableオプションを使用する必要があります。

オラクル

パラメーター	必須	説明
`serviceName`	はい	Oracle サービス名 ( `database`の代わりに使用されます)。
`query`	はい（または`dbtable` ）	リモートデータベースで実行する SQL クエリ文字列。`dbtable`では使用できません。
`dbtable`	はい（または`query` ）	クエリするテーブル名。`query`では使用できません。
`fetchsize`	No	ラウンドトリップごとに取得する行数。値を大きくするとパフォーマンスは向上しますが、メモリの使用量も多くなります。大丈夫: 0 (ドライバーを使用してください)。
`partitionColumn`	No	並列データフェッチに使用する均一に分散された値を持つ列。`lowerBound` 、 `upperBound` 、 `numPartitions`と一緒に使用する必要があります。`query`オプションと併用することはできません。
`lowerBound`	No	パーティション列の最小値。`partitionColumn` 、 `upperBound` 、 `numPartitions`と一緒に使用する必要があります。
`upperBound`	No	パーティション列の最大値。`partitionColumn` 、 `lowerBound` 、 `numPartitions`と一緒に使用する必要があります。
`numPartitions`	No	データの取得に使用する並列接続の数。あまり高く（数百）設定しないでください。`partitionColumn` 、 `lowerBound` 、 `upperBound`と一緒に使用する必要があります。

注記

Snowflake

パラメーター	必須	説明
`database`	はい	Snowflake 内のデータベース名。
`query`	はい（または`dbtable` ）	リモートデータベースで実行する SQL クエリ文字列。`dbtable`では使用できません。
`dbtable`	はい（または`query` ）	クエリするテーブル名 (単一部分の名前または複数部分の名前)。`query`では使用できません。
`schema`	No	Snowflake のスキーマ名。デフォルト: `public` 。
`query_timeout`	No	クエリのタイムアウト（秒単位）。デフォルト: 0 (タイムアウトなし)。
`partition_size_in_mb`	No	並列データ取得の予想されるパーティションサイズ (メガバイト単位)。デフォルト: 100 MB。

BigQuery

パラメーター	必須	説明
`query`	はい（または`dbtable` ）	リモートデータベースで実行する SQL クエリ文字列。`dbtable`では使用できません。
`dbtable`	はい（または`query` ）	クエリするテーブル名。`query`では使用できません。
`materializationDataset`	結果の具体化が必要な場合は、はい。`query`が指定されており、 `dbtable`ビューを指している場合は、実体化が必要です。	一時テーブルがマテリアライズされる BigQuery データセット名。一時テーブルのデフォルトの有効期間 (TTL) は 24 時間です。
`materializationProject`	No	マテリアライズ化のための BigQuery プロジェクト ID。デフォルトでは、接続で指定されたプロジェクトになります。
`materializationEnabled`	No	クエリのマテリアライゼーションを有効にするかどうか。ビューを照会するには`true`に設定します。デフォルト: `dbtable`が指定されている場合は`false` 、 `query`が指定されている場合は`true` 。
`parentProject`	No	課金目的の親プロジェクト ID。

重要

すべてのBigQueryでは大文字と小文字が区別されます。

追加のプッシュダウンコントロールオプション

remote_query関数を Databricks SQL 操作と組み合わせることができ、それらの操作のほとんどはプッシュダウンすることもできます。また、プッシュダウンできる Databricks SQL 操作を制御することもできます。これらのオプションはすべての接続タイプに適用され、大文字と小文字は区別されません。

パラメーター	デフォルト	説明
`pushdown.limit.enabled`	`true`	`LIMIT`句をリモートデータベースにプッシュダウンする機能を有効または無効にします。
`pushdown.offset.enabled`	`true`	`OFFSET`句をリモートデータベースにプッシュダウンする機能を有効または無効にします。
`pushdown.filters.enabled`	`true`	`WHERE`フィルターをリモートデータベースにプッシュダウンする機能を有効または無効にします。
`pushdown.aggregates.enabled`	`true`	集計関数 ( `COUNT` 、 `SUM` 、 `AVG` 、 `MAX` 、 `MIN` ) をリモートデータベースにプッシュダウンする機能を有効または無効にします。
`pushdown.sortLimit.enabled`	`true`	上位 N クエリ ( `ORDER BY`と`LIMIT`の組み合わせ) をリモートデータベースにプッシュダウンする機能を有効または無効にします。

デフォルトでは、すべてのプッシュダウンが有効になっています。トラブルシューティングや特定のリモートデータベースとの互換性の問題を回避するために必要な場合は、特定のプッシュダウンを無効にすることができます。

ビューを通じてアクセスを委任する

ビューでremote_query関数をラップすることで、ユーザーに直接USE CONNECTION権限を付与せずに、リモートデータへのアクセスを委任できます。このアプローチには次の利点があります。

簡素化されたアクセス制御 : USE CONNECTION権限を管理する代わりに、ビューに対するSELECT権限を付与します。
データセキュリティ : ビュークエリを定義して、ユーザーがアクセスできる列と行を制御します。
リネージの追跡 : 直接的な接続の使用ではなく、ビューリネージを通じてデータアクセスを追跡します。

ビューを通じてアクセスを委任するには:

remote_query関数を呼び出すビューを作成します。

SQL
CREATE VIEW sales_data_view AS
SELECT * FROM remote_query(
  'my_connection',
  database => 'sales_db',
  query => 'SELECT region, product, revenue FROM sales'
);

ビューに対するSELECT権限をユーザーまたはグループに付与します:
SQL
```
GRANT SELECT ON VIEW sales_data_view TO <user-or-group>;
```
ユーザーは、 USE CONNECTION権限を必要とせずにビューをクエリできるようになりました。
SQL
```
SELECT * FROM sales_data_view WHERE region = 'US';
```

重要

ビューの所有者は接続に対してUSE CONNECTION権限を持っている必要があります。ユーザーがビューをクエリする場合、クエリを実行したユーザーの権限ではなく、ビューの所有者の権限を使用して接続アクセスチェックが実行されます。

例

基本的なクエリ実行

PostgreSQL データベースでクエリを実行します。

SQL
SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'sales_db',
  query => 'SELECT * FROM orders WHERE order_date > CURRENT_DATE - INTERVAL \'30 days\''
);

特定のテーブルをクエリする

MySQL テーブルを直接クエリします。

SQL
SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'inventory',
  dbtable => 'my_schema.products'
);

サービス名付きOracle

Oracle データベースをクエリします。

SQL
SELECT * FROM remote_query(
  'my_oracle_connection',
  serviceName => 'ORCL',
  query => 'SELECT * FROM customers WHERE ROWNUM <= 1000'
);

BigQueryクエリ

Google BigQuery にクエリを実行します。

SQL
SELECT * FROM remote_query(
  'my_bigquery_connection',
  materializationDataset => 'analytics',
  query => 'SELECT * FROM `project.dataset.table` WHERE created_date > DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)'
);

Snowflakeクエリ

クエリSnowflake :

SQL
SELECT * FROM remote_query(
  'my_snowflake_connection',
  database => 'ANALYTICS_DB',
  query => 'SELECT * FROM SALES WHERE SALE_DATE >= DATEADD(day, -30, CURRENT_DATE())'
);

パーティショニングによるパフォーマンスチューニング

SQL Server テーブルからデータを並列に取得します。

SQL
SELECT * FROM remote_query(
  'my_sqlserver_connection',
  database => 'sales',
  dbtable => 'transactions',
  partitionColumn => 'transaction_id',
  lowerBound => '0',
  upperBound => '1000000',
  numPartitions => '10',
  fetchsize => '1000'
);

Databricks SQL操作と組み合わせる

追加のフィルターと変換を適用します。

SQL
SELECT customer_id, SUM(amount) as total_amount
FROM remote_query(
  'my_postgres_connection',
  database => 'orders_db',
  query => 'SELECT customer_id, amount, order_date FROM orders'
)
WHERE order_date >= '2025-01-01'
GROUP BY customer_id
HAVING total_amount > 1000
ORDER BY total_amount DESC
LIMIT 100;

委任アクセス用のビューを作成する

remote_query関数をラップするビューを作成します。ビューに対するSELECT権限を持つユーザーは、基礎となる接続に対するUSE CONNECTION権限を必要とせずにデータをクエリできます。

SQL
CREATE VIEW sales_summary AS
SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'sales',
  query => 'SELECT region, product, SUM(revenue) as total_revenue FROM sales_data GROUP BY region, product'
);

GRANT SELECT ON VIEW sales_summary TO <user-or-group>;

プッシュダウン動作を制御する

remote_query関数を使用すると、Databricks は指定したクエリを超えて、リモートデータベースに追加の操作をプッシュダウンできます。この機能は、 remote_query関数を使用するビューをクエリするときに役立ちます。

以下の操作をプッシュダウンできます。

フィルター : リモートクエリの結果に適用されるWHERE句
投影 : 列の選択 ( SELECT個の特定の列)
制限 : 返される行の数を制限するLIMIT句
オフセット : 行をスキップするOFFSET節
集計 : COUNT 、 SUM 、 AVG 、 MAXなどの集計関数 MIN
Top-N : 上位/下位NクエリのORDER BYとLIMITの組み合わせ

プッシュダウンのサポートはデータソースによって異なります。詳細については、特定の接続タイプのドキュメントを参照してください。

トラブルシューティングや互換性のために特定のプッシュダウンを無効にします。

SQL
SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'analytics',
  query => 'SELECT * FROM complex_view',
  `pushdown.aggregates.enabled` => 'false',
  `pushdown.filters.enabled` => 'false'
);

制限事項

読み取り専用操作 : remote_query関数はSELECTクエリのみをサポートします。データ変更操作 (INSERT、UPDATE、DELETE、MERGE)、DDL 操作 (CREATE、DROP、ALTER)、およびストアドプロシージャはサポートされていません。
クエリの検証 : 指定したクエリはリモートデータベースで直接実行されます。Databricks は、スキーマ検査を実行してクエリが読み取り専用であることを検証しますが、構文とセマンティックの検証はリモートデータベースによって実行されます。

トラブルシューティング

権限エラー

権限エラーが発生した場合は、次の点を確認してください。

接続に対するUSE CONNECTION権限、または関数をラップするビューに対するSELECT権限があります。
接続の資格情報には、リモートデータベースに対する適切な権限があります。

エラー例:

PERMISSION_DENIED: User does not have USE CONNECTION on Connection 'my_connection'

解決：

SQL
GRANT USE CONNECTION ON CONNECTION my_connection TO <user-or-group>;

サポートされていない

サポートされていないというエラーが表示された場合は、接続の種類に応じて正しい接続を使用していることを確認してください。エラーメッセージには、許可されている問題がリストされます。

エラー例:

REMOTE_QUERY_FUNCTION_UNSUPPORTED_CONNECTOR_PARAMETERS: The following parameters are not supported for connection type 'postgresql': 'materializationDataset'. Allowed parameters for this connection type are: 'database', 'query', 'dbtable', 'fetchsize', 'partitionColumn', 'lowerBound', 'upperBound', 'numPartitions'.

解決策: サポートされていない問題を削除し、接続の種類に適した正しい問題を使用してください。

DML操作はサポートされていません

remote_query関数は読み取り専用のSELECTクエリのみをサポートします。

エラー例:

DML_OPERATIONS_NOT_SUPPORTED_FOR_REMOTE_QUERY_FUNCTION: Data modification operations are not supported in remote_query function.

解決策: クエリから INSERT、UPDATE、DELETE、または DDL ステートメントを削除します。SELECT ステートメントのみを使用します。

remote_queryクエリフェデレーションと比較​

始める前に​

接続を作成する​

接続アクセスを許可する​

remote_query関数を使用する​

構文​

必須​

コネクタ固有のオプション​

MySQL、PostgreSQL、SQL Server、Redshift、Teradata​

オラクル​

Snowflake​

BigQuery​

追加のプッシュダウンコントロールオプション​

ビューを通じてアクセスを委任する​

例​

基本的なクエリ実行​

特定のテーブルをクエリする​

サービス名付きOracle​

BigQueryクエリ​

Snowflakeクエリ​

パーティショニングによるパフォーマンスチューニング​

Databricks SQL操作と組み合わせる​

委任アクセス用のビューを作成する​

プッシュダウン動作を制御する​

制限事項​

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

権限エラー​

サポートされていない​

DML操作はサポートされていません​

その他のリソース​

`remote_query`クエリフェデレーションと比較

始める前に

接続を作成する

接続アクセスを許可する

`remote_query`関数を使用する

構文

必須

コネクタ固有のオプション

MySQL、PostgreSQL、SQL Server、Redshift、Teradata

オラクル

Snowflake

BigQuery

追加のプッシュダウンコントロールオプション

ビューを通じてアクセスを委任する

例

基本的なクエリ実行

特定のテーブルをクエリする

サービス名付きOracle

BigQueryクエリ

Snowflakeクエリ

パーティショニングによるパフォーマンスチューニング

Databricks SQL操作と組み合わせる

委任アクセス用のビューを作成する

プッシュダウン動作を制御する

制限事項

トラブルシューティング

権限エラー

サポートされていない

DML操作はサポートされていません

その他のリソース