跳转至

Databricks 连接器

Databricks 通过 Statement Execution API（/api/2.0/sql/statements）接入某个 SQL warehouse，认证用个人访问令牌——不用驱动，也不用 SDK。

这个 API 每个请求都是无状态的，所以 catalog（以及可选的 schema）随每条语句一起发送，而不是用 USE 设置一次。首轮等待内没跑完的语句会被轮询到终态。由 exec-databricks 控制，Arrow 路径还需要 exec-databricks-arrow。

连接配置

datasources:
  databricks:
    type: databricks
    host: dbc-xxxx.cloud.databricks.com   # 直接粘贴 https://…/ 形式的 URL 也能识别
    warehouse: e9678899fc3ffa09           # SQL warehouse 的 id，在 Connection details 里看
    password: ${DATABRICKS_TOKEN}         # dapi… 开头的个人访问令牌
    catalog: workspace                    # Unity Catalog 的 catalog
    schema: analytics                     # 可选的默认 schema

参数

键 类型 必填 默认 说明
type string 是 — databricks
host string 是 — workspace 主机名。粘成 https://…/ 也会自动裁掉。
warehouse string 是 — SQL warehouse 的 id（一串十六进制），不是显示名。
password string 是 — 个人访问令牌。尽量用 ${VAR}。
catalog string 否 — Unity Catalog 的 catalog，作为请求上下文发送。内部会折进 database:，所以两个键写哪个都行。
schema string 否 — 查询的默认 schema。
default bool 否 false 见连接配置。

本连接器解析但不使用的键： username、port、sslmode、sslrootcert、arrow_flight_port、account、role、compat_mode。uri: 不只是被忽略——它会直接报错，并告诉你改用 host + warehouse + catalog。

认证

把个人访问令牌写在 password: 里，会作为 bearer token 发送。令牌以 dapi 开头。把它放在环境变量里，别写进文件。

Arrow 原生结果

带上 exec-databricks-arrow 之后，结果会以 ARROW_STREAM + EXTERNAL_LINKS 请求：每个分块都是一份自包含的 Arrow IPC 流，放在预签名的对象存储 URL 上，拉取时不带 workspace 令牌（URL 本身已签名），解码一次即可。这里不需要重新定型——Databricks 导出的就是真正的 Date32/Timestamp Arrow 类型。见 Arrow。

已知限制

  • 不支持可移植写法的三参数 DATEDIFF。 Databricks 有三参数版本，但要求单位是裸关键字（DAY），而不是跨引擎写法里带引号的单位，所以那样写的指标在这个方言下会被拒。
  • catalog 必须可写，如果你要让 Dosi 在里面建东西；workspace 自带的示例 catalog 是只读的。
  • 未加引号的标识符会以小写返回。

时间戳以带 T 和结尾 Z 的 ISO-8601 形式返回，会替你规整成其它引擎产出的那种无时区形态；日期本身就是 ISO 的。

本地验证连接

$ dosi query --model model.yaml \
    --metrics revenue --group-by orders.status --execute --connection databricks

第一次失败通常是 SQL warehouse 停着：语句会一直等它启动，冷启动时可能超出轮询预算。

排错

报错 原因与处理
connection "x" (databricks) needs host workspace 主机名。
connection "x" (databricks) needs warehouse (the SQL warehouse id) 从 warehouse 的 Connection details 页签里复制 id。
connection "x" (databricks) needs password (a Personal Access Token) 提示里写得很直接：set password: ${DATABRICKS_TOKEN} to a dapi... PAT。
datasource "x": uri "…" is not supported for databricks; use host + warehouse + catalog 这个连接器只接受离散键。
Databricks statement did not finish within the poll budget 通常是 warehouse 冷启动；先把它启动起来，或者调高自动停止阈值。
HTTP 401: <body> / HTTP 403: <body> 令牌过期或被吊销，或者在这个 catalog 上没权限。
bad Databricks JSON: <e> / bad Databricks chunk JSON: <e> 响应体不符合预期——通常是 workspace 前面挂了代理。
bad Arrow IPC: <e> / reading Arrow chunk: <e> 仅 Arrow 路径：某个预签名分块 URL 拉不到或解不出来。

参考链接