
问你的编码 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》,原文链接










