Databricks AI Tools:让编码 Agent 直接跑 SQL 的 5 个命令,参数绑定与并行查询都实测过

Databricks AI Tools:让编码 Agent 直接跑 SQL

问你的编码 Agent 一个简单问题:“哪个取车邮编的出租车行程最多?”数据在 Databricks 的一张表里,Agent 手里有 Databricks CLI,本该一条命令搞定——但没有帮手时,它要走很多步:先列出 SQL 仓库找 ID,再拼一个 JSON 请求体调 Statement Execution API,用 databricks api post 发出去,轮询等状态变成 SUCCEEDED,再解析分块返回的结果;或者干脆写个 Python 脚本连 SQL 连接器。每一步都可能出错,每次出错都烧 token、费时间。

Databricks CLI 现在有了一个专门为这件事准备的命令组,叫 aitools。作者 Eduardo Rabelo 在 2026 年 11 月 15 日发表的这篇实测里,用真实工作区把 5 个关键命令逐条跑了一遍,也把踩到的坑都记了下来。下面是全文的中文整理,命令与输出数字均与原文一致。

aitools 是什么:两个命令组

Databricks CLI 是 Databricks 的命令行工具,装在笔记本或 CI 里,用 ~/.databrickscfg 里的 profile 登录。aitools 是它里面的两个命令组:

命令组 做什么 谁用
databricks aitools 把 Databricks 的 Skill 和插件装进编码 Agent 你,每台机器或每个项目装一次
databricks experimental aitools tools 跑 SQL、读表结构,输出是 Agent 能解析的格式 你的编码 Agent、你的脚本、你自己

第二个命令组挂在 experimental 下面,CLI 的帮助文本也老实写着:这些工具是给 Claude Code、Cursor 这类 AI 编码 Agent 用的,随时可能变,没有稳定性保证。这句警告要先记在心里,文末还会回来讲它。

实测环境:Databricks CLI v1.26.0,工作区 profile 叫 aws-workspace,用的是一张公开表 samples.nyctaxi.trips(21,932 行)。samples 是每个 Unity Catalog 工作区自带的演示目录,不用自己造数据就能跑通下面所有命令。为省事,作者先定义了一个 shell 函数:

# ~/.zshrc(或直接粘进终端)
ait() { databricks experimental aitools tools "$@"; }

下文的 ait query ... 就是 databricks experimental aitools tools query ...。如果你的 profile 不是默认的,在命令后加 -p <profile>。

命令 1:get-default-warehouse

每个 tools 命令都要一个 SQL 仓库;不给的话 CLI 会帮你挑一个。先看它挑了哪个:

ait get-default-warehouse --output json
{
  "id": "9810e746a2babb0b",
  "name": "Serverless Starter Warehouse",
  "state": "RUNNING"
}

就这么简单——重点正在于此:Agent 不用再列出 SQL 仓库一个个猜。想固定用某个仓库,可以设环境变量 DATABRICKS_WAREHOUSE_ID=9810e746a2babb0b,或在每个 query、statement submit 命令后加 --warehouse <id>。

命令 2:query——最常用的一个

跑 SQL、等结果、打印出来,一条命令全办了:

ait query "
  SELECT pickup_zip, count(*) AS trips, round(avg(fare_amount), 2) AS avg_fare
  FROM samples.nyctaxi.trips
  GROUP BY 1 ORDER BY 2 DESC LIMIT 3"

Agent 在非交互终端里跑时,输出是 JSON:

[
  { "avg_fare": "10.62", "pickup_zip": "10001", "trips": "1227" },
  { "avg_fare": "10.98", "pickup_zip": "10003", "trips": "1181" },
  { "avg_fare": "10.91", "pickup_zip": "10011", "trips": "1129" }
]

注意一个细节:所有值都是字符串,"1227" 不是数字。Agent 读文本没问题,但脚本里要先做求和得先转类型。

SQL 有四种给法:位置参数、--file report.sql(或 -f)、以 .sql 结尾且真实存在的文件名作位置参数、stdin 管道输入。

最值得学的是参数绑定,别再拼字符串。用 :name 占位、--param 传值:

ait query --output csv \
  --param zip:INT=10001 \
  --param since:DATE=2016-02-14 \
  "SELECT tpep_pickup_datetime, fare_amount
   FROM samples.nyctaxi.trips
   WHERE pickup_zip = :zip AND tpep_pickup_datetime >= :since
   ORDER BY 1 LIMIT 3"

name=value 绑字符串,name:TYPE=value 绑带类型的数值(比如 DATE、INT);CLI 把空值当 NULL 发,不支持 ? 这种位置占位符。Agent 靠拼接字符串组装 SQL 时,迟早有一天会把数据里的引号拼进去出问题,参数绑定直接消灭了这一整类 bug。加 --output csv 还能把结果导出文件,不用开 notebook:ait query --output csv "SELECT * FROM samples.nyctaxi.trips LIMIT 1000" > trips.csv。

多条 SQL 可以并行跑。一次传多条语句,CLI 同时执行(默认最多 --concurrency 条,即 8 条)。作者故意在第二条里写了个错列名做测试:

ait query \
  "SELECT count(*) AS n FROM samples.nyctaxi.trips" \
  "SELECT nope FROM samples.nyctaxi.trips"

结果先报了错:multiple queries require --output json。帮助文本说“多查询输出永远是 JSON”,但在 v1.26.0 里并非如此,必须自己加 --output json。加上之后,两条语句各回各的结果,错的那条还带上了修正建议:

[
  {
    "sql": "SELECT count(*) AS n FROM samples.nyctaxi.trips",
    "statement_id": "01f1e012-704d-163a-b2d2-17ed3cd4c4f2",
    "state": "SUCCEEDED",
    "elapsed_ms": 1348,
    "columns": ["n"],
    "rows": [["21932"]]
  },
  {
    "sql": "SELECT nope FROM samples.nyctaxi.trips",
    "state": "FAILED",
    "error": {
      "message": "[UNRESOLVED_COLUMN.WITH_SUGGESTION] A column, variable, or function parameter with name `nope` cannot be resolved. Did you mean one of the following? [`dropoff_zip`, `pickup_zip`, `fare_amount`, `trip_distance`, `tpep_dropoff_datetime`]. SQLSTATE: 42703; line 1 pos 7",
      "error_code": "BAD_REQUEST"
    }
  }
]
exit=1

三点值得注意:好的查询照常返回结果,一条失败不会盖住另一条的答案;错误自带修正建议(“你是想说 pickup_zip 吗”),Agent 下次自己就能改对;退出码是 1,任何一条失败整条命令就算失败,CI 检查和脚本可以信它。另外注意输出形状变了:单条查询返回对象列表,批量返回 columns + rows 的数组,写脚本解析时两种都要处理。

命令 3:discover-schema——写 SQL 之前先认表

Agent 写 SQL 之前得知道表的列。没有这个命令,它要跑 DESCRIBE、再跑一条采样 SELECT、可能还要查空值——每张表三次往返。discover-schema 一次全给:

ait discover-schema samples.nyctaxi.trips
COLUMNS:
  tpep_pickup_datetime: timestamp
  tpep_dropoff_datetime: timestamp
  trip_distance: double
  fare_amount: double
  pickup_zip: int
  dropoff_zip: int
SAMPLE DATA:
  Row 1:
    tpep_pickup_datetime: 2016-02-13T21:47:53.000Z
    ...
NULL COUNTS:
  total_rows: 21932
  tpep_pickup_datetime_nulls: 0
  ...

每张表给列名与类型、5 行采样数据、每列空值数和总行数。一次可以传多张表(用完整的 CATALOG.SCHEMA.TABLE 名),所有探测共享一个 --concurrency 预算(默认 8)。一个提醒:采样行是真实数据,如果表里有个人信息,Agent 的上下文里就有了这 5 行——只让 Agent 看它有权限看的表。

命令 4:statement submit / status / get / cancel——长活别干等

query 会等结果,大多数时候这正是你想要的。但一个大的 OPTIMIZE、一次长回填、一份重报表可能跑好几分钟,Agent 堵在上面就什么都干不了。statement 命令把活拆成几步:

命令 做什么 会等吗
statement submit 把 SQL 发出去,立刻返回一个 statement_id 否
statement status <id> 读一次当前状态 否
statement get <id> 等到跑完再打印结果 是
statement cancel <id> 让服务端停掉它 否

完整走一遍:submit 拿到 statement_id(状态 PENDING),status 查一次,get 等出结果。作者还实测了取消:提交一个很慢的自连接后立刻 cancel,再 status 确认,状态变成 CANCELED。两个容易踩的点:cancel 后的第一次状态是 CLI 乐观假设的(API 本身不返回 body),想确认必须再跑一次 status;query 上按 Ctrl+C 会取消服务端的语句,但 statement get 上按 Ctrl+C 只停止等待,语句还在跑、仓库还在计费,Agent 停下等待后还得补一个 statement cancel。

命令 5:aitools install——先让 Agent 知道这些命令存在

上面这些命令再好用,Agent 不知道它们的存在也没用,这就是另一个命令组的活。作者第一次列 profile 时,CLI 在列表前打印了提示:Databricks skills are not installed. To work with Databricks reliably, first run: databricks aitools install。

databricks aitools install

它会找到你机器上的编码 Agent 并把 Databricks 的 Skill 装进去:Claude Code、Codex、GitHub Copilot 走各自 CLI 装插件,其他(Cursor、OpenCode、Antigravity、Pi、Gemini CLI、Goose、Kiro)写原始 Skill 文件。只给某个 Agent、只装进当前项目:databricks aitools install --agents claude-code --scope project。常用 flag 还有 --agents、--scope project/global、--skills(只装指定 Skill)、--experimental、--path <dir>(把 Skill 文件写到文件夹里先读一遍再装)。该组还有 list、update、uninstall、version。作者自己没跑 install,他的建议是:先拿 --path 把 Skill 文件写出来读一遍,再决定信不信任它。

6 个坑:先看完再用

1. 它能跑任何 SQL,不只是 SELECT。同一条读表的命令也能删库:ait query 'DROP CATALOG IF EXISTS `my_catalog` CASCADE',CLI 不会问“你确定吗”。唯一的防线是你 profile 背后那个身份的权限。作者的建议:给 Agent 一个单独的身份(比如 service principal)和单独的 profile,只授读权限——GRANT USE CATALOG ... TO `agent-readonly`` 加上 CAN USE 一个 SQL 仓库,这样 DROP 在服务端就会失败;非读操作再走 Agent 自己的审批规则。

2. zsh/bash 里引号要小心。双引号里的反引号会被当成 shell 命令执行,带反引号标识符的 SQL 用单引号包起来。

3. 它可能启动一个 SQL 仓库。如果默认仓库是停着的,第一次查询会把它拉起来——要花钱。给 Agent 的活固定一个小的 SQL 仓库(DATABRICKS_WAREHOUSE_ID)。

4. JSON 里所有值都是字符串,脚本里做数学运算前先转类型。

5. 批量查询要加 --output json,至少在 v1.26.0 里是这样。

6. 它是实验性的。flag、输出形状、命令名都可能在任何一个 CLI 版本里变,别拿现在这个 JSON 形状去搭生产管线。

值不值得关注:作者的判断

优点:“跑这条 SQL 并把结果给我”一句话的事,输出是结构化的;有名有类型的参数绑定,不再拼字符串;discover-schema 一次调用给齐列、采样与空值;并行批量返回逐条结果、失败时退出码非零;异步 statement 命令处理长活;aitools install 把用法说明放到 Agent 找得到的地方。

缺点:实验性质、无稳定性保证,实测已发现一处帮助文本与行为不符;两种输出形状、值全是字符串;对破坏性 SQL 没有内置防护,安全全靠身份与 Agent 权限;自动挑仓库可能启动一个你没预期的仓库;discover-schema 的采样行会把真实数据放进 Agent 上下文。

作者的默认建议是:先在一个项目里装 Skill、固定一个小的 SQL 仓库、给 Agent 一个只读 profile,让它用 query 和 discover-schema 跑一周。他的判断是,Databricks 专门为编码 Agent 写命令、还在帮助文本里明说这是给 Agent 用的,这本身就是工具演进方向的一个信号——但这句话是他的观点,不是文档里的事实。

如果你已经在用 Databricks SQL,把 Claude Code 接进 CI 的那篇实测讲的是另一条线:PR 审查门禁怎么跑通;而谷歌、微软等联合出品的 Modern Web Guidance Skill 包则是给编码助手装规范的另一类 Skill,思路可以对照着看。

转自 DEV Community 作者 Eduardo Rabelo 的文章《Databricks AI Tools: The SQL Commands Your Coding Agent Should Use》,原文链接

© 版权声明
THE END
喜欢就支持一下吧
点赞5 分享