Hotdata CLI OLAP分析进阶：Chain物化与查询历史，让你的报表查询快上数倍

Hotdata CLI 是 Hotdata 平台的官方命令行工具，一条命令即可完成登录、建库、加载数据与执行 PostgreSQL 方言的 SQL 分析。对于跑报表的工程师来说，它真正的进阶能力藏在两个命令组里：**查询历史（Query History）**帮你定位重复的重查询，Chain 物化帮你把大表扫描的结果固化成小表，让后续报表查询快上数倍。这篇指南面向新手，带你从零理解这两个特性，并给出可直接照抄的操作步骤。

一、快速安装 Hotdata CLI（1 分钟上手）

在终端执行下面任一方式即可安装：

brew install hotdata-dev/tap/cli # macOS / Linux（Homebrew） cargo install --path . # 从源码构建（需要 Rust 环境）

安装后登录并创建你的第一个"即时数据库"（instant database）：

hotdata auth login hotdata databases create --catalog demo hotdata query "SELECT count(*) FROM demo.public.trips"

💡 即时数据库是 Hotdata 的核心概念：数据落库后可立即用 SQL 查询，表在 SQL 中写作<catalog>.<schema>.<table>，详见 README.md。

二、查询历史：先用数据找出"慢在哪"

很多团队的报表变慢，不是因为单条 SQL 写得不行，而是同一份重查询被反复执行。Hotdata CLI 把每次执行都记成了可检索的历史。

2.1 列出最近的查询运行

hotdata databases queries list --limit 20

列表会展示每条运行的状态、耗时、返回行数与 SQL 预览，默认每页 20 条。如果只想盯失败的或正在跑的任务，加过滤条件：

hotdata databases queries list --status running,failed

2.2 查看单次运行详情

hotdata databases queries <query_run_id>

详情包含完整格式化 SQL、耗时与结果 ID（result_id）。历史列表功能的实现位于 src/commands/queries.rs，其中 SQL 预览还会做关键字高亮，方便肉眼扫读。

关键技巧：翻一遍历史，找出反复出现的WHERE/JOIN/GROUP BY模式——它们就是你接下来要物化的候选对象。官方分析技能文档把这条建议写得很明确："Use history to find recurring patterns before adding indexes or chains"，出处见 skills/hotdata/subskills/analytics/SKILL.md。

2.3 缓存结果：别再重跑同一条重查询

每条查询的结果都会落盘保存（rslt…形式的 result-id，也会出现在查询输出的页脚里）。取回历史结果比重跑查询便宜得多：

hotdata databases results list # 列出已存结果 hotdata databases results get <result_id> -o csv

注意两点（来自 src/commands/results.rs 的实现约定）：

• results list默认返回100条（上限 1000），与queries list的 20 条不同；
• 官方工作流文档明确建议："Preferresults get <result_id>over re-running identical heavy SQL"——重跑既浪费资源，还可能因为数据已变化而得到不同答案。详见 skills/hotdata/subskills/analytics/references/WORKFLOWS.md。

三、Chain 物化三步走：把"大表扫描"变成"查小表"

Chain 是 Hotdata 分析工作流的官方术语：跑一次重 SQL → 把结果物化成即时数据库里的小表 → 后续查询直接打这个小表。三步走如下（完整流程见 skills/hotdata/subskills/analytics/references/WORKFLOWS.md 的 Chain 章节）。

第一步：跑基础查询

hotdata query "SELECT region, sum(amount) FROM demo.public.orders WHERE created_at >= '2026-01-01' GROUP BY region"

如果查询较长，CLI 会异步执行并打印query_run_id，用hotdata query status <id>轮询即可，不要在轮询期间重复提交同一条 SQL。

第二步：物化到即时数据库

把上一步导出的结果（parquet 文件）装进一个专门的 catalog：

hotdata databases create --catalog chain_db hotdata databases load --catalog chain_db --table revenue_slice --file ./revenue_slice.parquet

加载完成后，这张表在 SQL 中的完整名字就是chain_db.public.revenue_slice，用hotdata databases tables list确认一下即可。

第三步：对物化表发"链式查询"

hotdata query "SELECT * FROM chain_db.public.revenue_slice WHERE region = 'East'"

从此，所有基于这份数据的下钻、透视、二次聚合都跑在已经过滤裁剪过的小表上，不再重复扫描原始大表——这就是"快上数倍"的来源。

命名与护栏：让 Chain 可持续维护

这些护栏直接来自官方工作流文档的 Guardrails 一节，遵循它们可以避免"物化了一堆没人用的大宽表"的常见坑。

四、把稳定链路写进 DATAMODEL：让全团队共享同一张地图

Chain 表如果打算长期存在，就应该写进数据库级的数据模型文档（context:DATAMODEL）：

hotdata databases context show DATAMODEL # 查看现有文档 hotdata databases context push DATAMODEL # 推送修改后的 ./DATAMODEL.md

官方模板里专门为 Chain 预留了Derived tables (Chain)章节，记录表名、来源 SQL、用途与负责人，模板文件见 skills/hotdata/references/DATA_MODEL.template.md。这样新同事和 AI 代理（通过hotdata manage skills install安装的 agent skill）都能用同一份地图理解你的数据。

五、进阶技巧清单：再挤一点性能

• 🚀异步轮询看退出码：query status返回0成功、1失败、2仍在跑、3成功但打印的是截断预览——脚本里直接依赖退出码就能安全编排（实现见 src/commands/query.rs）。
• 📊大结果集用-o csv或-o json：二者完整流式输出且内存占用平稳；-o table是给人看的视图，超过 1 万行会被截断并提示INCOMPLETE PREVIEW。
• 🔀方言转译：--dialect snowflake|duckdb|postgres可让服务端把你的方言 SQL 转成 HotSQL 再执行，迁移旧报表脚本时无需逐行改写。
• 🛡️高风险变更前先 fork：hotdata databases fork深度复制一个独立数据库做实验，源库不受影响，做完再用databases lineage查看完整的 fork 家族树。
• ⏱️排序索引加速过滤：对等值/范围/排序密集的分析场景，用hotdata search create --type sorted建排序索引，比全文/向量索引更对路（见 skills/hotdata/subskills/analytics/SKILL.md 的 Sorted indexes 一节）。

小结

Hotdata CLI 的 OLAP 进阶路径可以浓缩成一条闭环：

1. databases queries list翻历史，找出被反复执行的慢查询；
2. 把结果Chain 物化为即时数据库中的小表，后续查询打小表；
3. 用databases results get复用已存结果，避免无谓重跑；
4. 稳定链路写进DATAMODEL，让团队与 AI 共享同一份数据地图。

按照这个顺序实践，你的报表查询将从"每次全量扫大表"进化为"秒级查切片"，而整个过程只需要几条终端命令。