Databricks JDBC 驱动 (Simba) 的驱动能力设置

本页介绍如何为 Databricks JDBC 驱动程序配置特殊和高级驱动程序功能设置。

Datbricks JDBC 驱动程序提供以下特殊和高级驱动程序功能设置。

JDBC 中的 ANSI SQL-92 查询支持

旧版 Spark JDBC 驱动程序接受 ANSI SQL-92 方言中的 SQL 查询，并在将其发送到服务器之前将其转换为 Databricks SQL。

如果应用程序直接生成 Databricks SQL，或使用特定于 Azure Databricks 的非 ANSI SQL-92 语法，请在连接配置中设置 UseNativeQuery=1 。 此设置将 SQL 查询逐字传递到 Azure Databricks，而无需翻译。

默认目录和架构

若要指定默认目录和架构，请将 ConnCatalog=<catalog-name>;ConnSchema=<schema-name> 添加到 JDBC 连接 URL。

用于跟踪的查询标记

将键值标记附加到 SQL 查询以进行跟踪和分析。 查询标记显示在 system.query.history 表中，用于查询标识和分析。

若要将查询标记添加到连接，请在 ssp_query_tags JDBC 连接 URL 中包含参数：

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;ssp_query_tags=key1:value1,key2:value2

将查询标记定义为逗号分隔的键值对，其中每个键和值都用冒号分隔。 例如，key1:value1,key2:value2。

在 JDBC 中提取大型查询结果

若要在提取大型查询结果时获得最佳性能，请使用包含以下优化措施的最新版 JDBC 驱动程序。

JDBC 中的 Arrow 序列化

JDBC 驱动程序版本 2.6.16 和更高版本支持使用 Apache Arrow 的优化查询结果序列化格式。

JDBC 中的云提取

JDBC 驱动程序版本 2.6.19 及更高版本支持 Cloud Fetch，该功能通过 Azure Databricks 部署中配置的云存储提取查询结果。

运行查询时，Azure Databricks将结果作为 20 MB 的箭头序列化文件存储在工作区的云存储中。 查询完成后，驱动程序会发送提取请求，Azure Databricks将共享访问签名（SAS）URL返回到结果文件。 然后，驱动程序使用这些 URL 直接从Azure存储下载结果。

Cloud Fetch 仅适用于大于 1 MB 的查询结果。 驱动程序直接从 Azure Databricks 检索较小的结果。

Azure Databricks自动垃圾回收累积的文件，方法是在 24 小时后将其标记为删除，并在 24 小时后永久删除这些文件。

网络先决条件

如果网络是专用网络，则必须配置以下设置才能使 Cloud Fetch 正常工作：

• 允许 *.blob.core.chinacloudapi.cn 和 *.store.core.chinacloudapi.cn 在网络环境中。

• 将所需的 证书下载和吊销 添加到允许列表。

• 如果在 Azure Databricks 工作区存储帐户上启用了防火墙支持，请配置 虚拟网络数据网关 或 本地数据网关 ，以允许对存储帐户进行专用访问。

若要禁用 Cloud Fetch，请在连接配置中设置 EnableQueryResultDownload=0 。

诊断下载速度缓慢

LogLevel 设置为 4 （INFO）和LogPath日志文件夹的完整路径，以查看 Cloud Fetch 下载速度指标。 驱动程序记录每个区块的下载速度，因此大型结果集生成多个日志行。 当速度低于大约 1 MB/秒时，驱动程序还会记录警告。 此功能在 2025 年 12 月之后发布的 JDBC （Simba） 驱动程序版本中提供。

如果下载速度缓慢或已停止，则驱动程序下载所有结果文件之前，SAS 令牌可能会过期。 检查客户端与Azure Blob 存储之间的带宽限制或网络拥塞。

启用日志记录

若要在 JDBC 驱动程序中启用日志记录，请将LogLevel属性设置为（仅限严重事件）和1（所有驱动程序活动）之间的6值。 将 LogPath 属性设置为要保存日志文件的文件夹的完整路径。

有关详细信息，请参阅 Databricks JDBC 驱动程序指南中的 配置日志记录 。