使用 remote_query 函数查询外部数据库

使用 remote_query 表值函数 （TVF），可以使用远程系统的本机 SQL 语法直接从 Azure Databricks 中对外部数据库和数据仓库运行 SQL 查询。 此函数提供了查询联合的灵活替代方法，使你可以运行以远程数据库方言编写的查询，而无需将其转换为 Databricks SQL。

remote_query 与查询联合化比较

下表总结了 remote_query 函数与查询联邦之间的主要差异：

在您开始之前

工作区要求：

• 已为 Unity Catalog 启用工作区。

计算要求：

• 从 Databricks Runtime 群集或 SQL 仓库到目标数据库系统的网络连接。 请参阅 Lakehouse Federation 网络建议。
• Azure Databricks 群集必须使用 Databricks Runtime 17.3 或更高版本。
• SQL 仓库必须是 Pro，并且使用版本 2025.35 或更高版本。

所需的权限：

• 若要创建连接，你必须是元存储管理员或具有 CREATE CONNECTION Unity 目录元存储特权的用户。
• 若要使用remote_query函数，您必须在连接上具有USE CONNECTION特权，或者在包装该函数的视图上具有SELECT特权。 单用户群集还需要对连接拥有 MANAGE 权限。

创建连接

若要使用该 remote_query 函数，首先需要创建与外部数据库的 Unity 目录连接。 如果已为查询联合创建了连接，则可以重复使用它。

该 remote_query 函数支持连接到以下连接类型：

• MySQL
• PostgreSQL
• Teradata
• Oracle
• Amazon Redshift
• Snowflake
• Microsoft SQL Server

有关管理现有连接的信息，请参阅管理 Lakehouse Federation 的连接。

授予连接访问权限

若要使用该 remote_query 函数，必须对连接具有 USE CONNECTION 特权（或 MANAGE 对单用户群集具有特权）。

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

使用 remote_query 函数

该 remote_query 函数对远程数据库运行查询，并将结果作为可在 Databricks SQL 查询中使用的表返回。

Syntax

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

必需的参数

• connection-name：要使用的 Unity 目录连接的名称。

所有其他必需的参数因连接类型而异。 有关详细信息，请参阅 特定于连接器的选项 。

特定于连接器的选项

可用选项因连接类型而异。 下表描述了每个连接器的选项。

MySQL、PostgreSQL、SQL Server、Redshift 和 Teradata

Oracle

Snowflake

其他下推控制选项

可以将 remote_query 函数与 Databricks SQL 操作相结合，并且大部分操作也可以下推。 还可以控制哪些 Databricks SQL 的操作能够下推。 这些选项适用于所有连接类型，且不区分大小写。

默认情况下，所有下推功能都处于启用状态。 如果需要对特定的远程数据库进行故障排除或解决兼容性问题，可以禁用特定的推下操作。

通过视图委托访问权限。

可以通过在视图中包装USE CONNECTION函数来委托对远程数据的访问，而无需向用户授予直接remote_query权限。 此方法提供以下优势：

• 简化的访问控制：授予 SELECT 对视图的权限，而不是管理 USE CONNECTION 特权。
• 数据安全性：通过定义视图查询来控制哪些列和行用户可以访问。
• 跟踪谱系：通过视图谱系跟踪数据访问，而不是直接连接使用。

通过视图委托访问权限：

1. 创建一个调用 remote_query 函数的视图：

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

2. 将视图上的 SELECT 权限授予用户或组：

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

3. 用户现在可以查询视图，而无需 USE CONNECTION 特权：

   SELECT * FROM sales_data_view WHERE region = 'US';
   

例子

基本查询执行

对 PostgreSQL 数据库执行查询：

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

查询特定表

直接查询 MySQL 表：

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

具有服务名称的 Oracle

查询 Oracle 数据库：

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

Snowflake 查询

查询 Snowflake：

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

使用分区进行性能优化

从 SQL Server 表并行提取数据：

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

与 Databricks 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 权限即可查询数据：

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 函数的视图时，此功能非常有用。

可以向下推送以下操作：

• 筛选器：应用于远程查询结果的条件
• 投影：列选择（SELECT 特定列）
• 限制: LIMIT 用于限定返回行数的子句
• 偏移量： OFFSET 跳过行的语句
• 聚合：聚合函数，例如COUNT，、SUM、AVGMAX、MIN
• Top-N：组合 ORDER BY 和 LIMIT 用于顶部/底部 N 查询

下推支持因数据源而异。 有关详细信息，请参阅特定连接类型的文档。

禁用特定的推送功能以便进行故障排除或保证兼容性。

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 通过执行架构检查来验证查询是否为只读，但语法和语义验证由远程数据库执行。

Troubleshooting

权限错误

如果收到权限错误，请检查以下几点：

1. 你对连接具有 USE CONNECTION 特权或者对包装函数的视图具有 SELECT 特权。
2. 连接中的凭据对远程数据库具有适当的权限。

示例错误：

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

解决方法：

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 语句。

其他资源

• 什么是查询联合？
• 管理 Lakehouse 联合平台的连接
• Lakehouse 联邦性能推荐
• 管理 Unity 目录中的权限