通过

支持的连接属性

  • 项目

本文介绍了 Databricks JDBC 驱动程序 (OSS) 支持的连接属性。

身份验证和代理属性

Databricks JDBC 驱动程序 (OSS) 支持以下连接属性。 属性不区分大小写。

财产 默认值 DESCRIPTION
AsyncExecPollInterval 200 每次轮询异步查询执行状态之间的时间(以毫秒为单位)。 异步是指用于对 Spark 执行查询的 RPC 调用是异步的。 这并不意味着支持 JDBC 异步操作。
Auth_Flow 0 驱动程序连接的 OAuth2 身份验证流。 如果 AuthMech 为 11，则此属性是必需项。
Auth_JWT_Key_File null 用于 JWT 身份验证的私钥文件（PEM 格式）的路径。
Auth_JWT_Alg RS256 私钥 JWT 身份验证的算法。 支持的算法包括：RSA 算法：RS256、RS384、RS512、PS256、PS384、PS512；以及 EC 算法：ES256、ES384、ES512
Auth_JWT_Key_Passphrase null 用于解密加密私钥的密码。
Auth_KID null JWT 身份验证所需的密钥 ID (KID)。 使用私钥 JWT 时，此属性为必需项。
AuthMech 必选 身份验证机制，其中 3 指定机制为 Azure Databricks 个人访问令牌，11 则指定机制为 OAuth 2.0 令牌。 每个机制都需要额外属性。 请参阅对驱动程序进行身份验证。
CFProxyAuth 0 如果设置为 1，驱动程序将使用代理身份验证用户和密码，由 CFProxyUID 和 CFProxyPwd 表示。
CFProxyHost null 一个字符串，表示当 UseCFProxy 也设置为 1 时要使用的代理主机的名称。
CFProxyPort null 一个整数，表示当 UseCFProxy 也设置为 1 时要使用的代理端口的数目。
CFProxyUID null 一个字符串，表示在 CFProxyAuth 和 UseCFProxy 也设置为 1 时用于代理身份验证的用户名。
CFProxyPwd null 一个字符串，表示在 CFProxyAuth 和 UseCFProxy 设置为 1 时用于代理身份验证的密码。
ConnCatalog 或 catalog SPARK 要使用的默认目录的名称。
ConnSchema 或 schema default 要使用的默认架构的名称。 可以通过将 URL 中的 <schema> 替换为要使用的架构的名称或将 ConnSchema 属性设置为要使用的架构的名称来指定它。
EnableComplexDatatypeSupport 0 如果设置为 1，则启用对复杂数据类型（数组、结构体、映射）的支持，使其作为原生 Java 对象而非字符串。
GoogleServiceAccount null 使用 Google 服务帐户启用身份验证。
GoogleCredentialsFile null 用于 Google 服务帐户身份验证的 JSON 密钥文件的路径。
EnableOIDCDiscovery 1 如果设置为 1，则使用 OpenID Connect 发现 URL。
OIDCDiscoveryEndpoint null 用于检索 OIDC 配置的 OpenID Connect 发现 URL。
Auth_RefreshToken null 用于获取新的访问令牌的 OAuth2 刷新令牌。
OAuth2ConnAuthAuthorizeEndpoint null OAuth2 流中使用的授权终结点 URL。
OAuth2ConnAuthTokenEndpoint null OAuth2 流的令牌终结点 URL。
ProxyAuth 0 如果设置为 1，驱动程序将使用代理身份验证用户和密码，由 ProxyUID 和 ProxyPwd 表示。
ProxyHost null 一个字符串，表示当 UseProxy 也设置为 1 时要使用的代理主机的名称。
ProxyPort null 一个整数，表示当 UseProxy 也设置为 1 时要使用的代理端口的数目。
ProxyPwd null 一个字符串，表示在 ProxyAuth 和 UseProxy 设置为 1 时用于代理身份验证的密码。
ProxyUID null 一个字符串，表示在 ProxyAuth 和 UseProxy 也设置为 1 时用于代理身份验证的用户名。
SSL 1 连接器是否通过启用 SSL 的套接字与 Spark 服务器通信。
UseProxy 0 如果设置为 1，驱动程序将使用提供的代理设置（例如：ProxyAuth、ProxyHost、ProxyPort、ProxyPwd、ProxyUID）。
UseSystemProxy 0 如果设置为 1，驱动程序将使用已在系统级别设置的代理设置。 如果在连接 URL 中设置了任何其他代理属性，则这些额外的代理属性将替代已在系统级别设置的属性。
UseCFProxy 0 如果设置为 1，则驱动程序将使用云提取代理设置（如果已提供这些设置），否则将使用常规代理。
UseJWTAssertion false 为客户端机密身份验证受限的 M2M 用例启用私钥 JWT 身份验证。
UserAgentEntry browser 要包含在 HTTP 请求中的 User-Agent 条目。 此值采用以下格式：[ProductName]/[ProductVersion] [Comment]
UseThriftClient 1 JDBC 驱动程序是否应使用 Thrift 客户端或语句执行 API。

SQL 配置属性

Databricks JDBC 驱动程序 (OSS) 支持以下 SQL 配置属性。 配置参数中也介绍了这些参数。 属性不区分大小写。

财产 默认值 DESCRIPTION
ansi_mode TRUE 是否对某些函数和强制转换规则启用严格的 ANSI SQL 行为。
enable_photon TRUE 是否启用 Photon 矢量化查询引擎。
legacy_time_parser_policy EXCEPTION 用于分析和设置日期和时间戳格式的方法。 有效值为 EXCEPTION、LEGACY和 CORRECTED。
max_file_partition_bytes 128m 从基于文件的源读取时要打包到单个分区的最大字节数。 此设置可以是任何正整数，并且可以选择包含诸如 b（字节）、k 或 kb（1024 字节）之类的度量值。
read_only_external_metastore false 控制外部元存储是否被视为只读。
statement_timeout 172800 设置 0 到 172800 秒之间的 SQL 语句超时。
timezone UTC 设置本地时区。 格式为 area/city 的时区 ID，例如 America/Los_Angeles，或者格式为 (+|-) HH、(+|-) HH:mm 或 (+|-) HH:mm:ss 的时区偏移量，例如 -08、+01:00 或 -13:33:33。 此外，支持使用 UTC 作为 +00:00 的别名
use_cached_result true Databricks SQL 是否缓存并尽可能重复使用结果。

日志记录属性

Databricks JDBC 驱动程序 (OSS) 支持以下日志记录属性。 属性不区分大小写。

财产 默认值 DESCRIPTION
LogLevel OFF 日志记录级别，值为 0 到 6：
  • 0：禁用所有日志记录。
  • 1：启用 FATAL 级别的日志记录，将记录导致连接器中止的非常严重的错误事件。
  • 2：在 ERROR 级别启用日志记录，这会记录可能仍允许连接器继续运行的错误事件。
  • 3：在 WARNING 级别启用日志记录，这会记录如果未执行操作可能导致错误的事件。
  • 4：在 INFO 级别启用日志记录，这会记录描述连接器进度的常规信息。
  • 5：在 DEBUG 级别启用日志记录，这会记录对调试连接器有用的详细信息。
  • 6：在跟踪级别启用日志记录，将记录所有连接器活动。

使用此属性在连接器中启用或禁用日志记录，并指定日志文件中包含的详细信息量。
LogPath 为确定日志的默认路径，驱动程序按以下优先级顺序使用为这些系统属性设置的值：
  • user.dir
  • java.io.tmpdir
  • 当前目录，即 .
 启用日志记录时连接器保存日志文件的文件夹的完整路径，字符串格式。 若要确保连接 URL 与所有 JDBC 应用程序兼容，请键入另一个反斜杠来转义文件路径中的反斜杠 (\)。
如果 LogPath 值无效，连接器会将记录的信息发送到标准输出流 (System.out)。
LogFileSize 无最大值 允许的最大日志文件大小，以 MB 为单位指定
LogFileCount 无最大值 允许的最大日志文件数量

启用和配置日志记录

JDBC 驱动程序支持适用于 Java 的简单日志门面 (SLF4J) 和 java.util.logging (JUL) 框架。 默认情况下，驱动程序使用 JUL 日志记录框架。

要为 JDBC 驱动程序启用和配置日志记录，请执行以下操作：

  1. 启用要使用的日志记录框架：

    • 对于 SLF4J 日志记录，设置系统属性 -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER，并在类路径中提供 SLF4J 绑定实施（与 SLF4J 2.0.13 及更高版本兼容）和相应的配置文件。
    • 对于 JUL 日志记录，设置系统属性 -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER。 这是默认值。

  2. 在连接字符串上设置 LogLevel 属性，将其设为要包含在日志文件中的所需信息级别。

  3. 在连接字符串上设置 LogPath 属性，将其设为要保存日志文件的文件夹的完整路径。

    例如，以下连接 URL 启用日志记录级别 6，并将日志文件保存到 C:temp 文件夹：

    jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp

  4. 重新启动 JDBC 应用程序并重新连接到服务器以应用这些设置。

卷操作属性

Databricks JDBC 驱动程序（OSS）支持的 Unity Catalog 卷操作属性如下。 属性不区分大小写。

财产 默认值 DESCRIPTION
VolumeOperationAllowedLocalPaths `` 用于下载和上传 UC 卷引入文件的允许的本地路径的逗号分隔列表。 这些路径也包括子目录。

通过卷来管理文件

Databricks 提供了使用 Unity Catalog 卷的批量引入功能（上传/下载/删除），允许用户在本地文件（如 CSV 文件）和数据集之间传输数据。 请参阅什么是 Unity Catalog 卷？。 要启用 Unity Catalog 卷操作，请将连接属性 VolumeOperationAllowedLocalPaths 设置为允许卷操作的本地路径的逗号分隔列表。

必须启用 Unity Catalog 才能使用此功能。 使用 Databricks UI 提供类似的功能。 请参阅将文件上传到 Unity Catalog 卷。

Unity Catalog 引入命令是 SQL 语句。 以下示例演示 PUT、GET 和 REMOVE 操作。

上传本地文件

要将本地文件 /tmp/test.csv 上传到 Unity Catalog 卷路径 /Volumes/main/default/e2etests/file1.csv，请使用 PUT 操作：

PUT '/tmp/test.csv' INTO '/Volumes/main/default/e2etests/file1.csv' OVERWRITE

下载文件

若要将文件从 Unity Catalog 卷路径 /Volumes/main/default/e2etests/file1.csv 下载到本地文件 /tmp/test.csv，请使用 GET 操作：

GET '/Volumes/main/default/e2etests/file1.csv' TO '/tmp/test.csv'

删除文件

若要删除具有 Unity Catalog 卷路径/Volumes/main/default/e2etests/file1.csv的文件，请使用 REMOVE 操作。

  REMOVE '/Volumes/main/default/e2etests/file1.csv'