企业官网建设流程全解析

Hotdata CLI 是 Hotdata 平台的命令行工具：一条 SQL 即可查询外部数据库、API、云存储、Iceberg 目录与本地上传文件。它的流式输出机制基于Arrow 列式传输 + 并发管道，结果集达到2000 万行时依然能稳定拉取——内存峰值只保留几个数据批次，且绝不对管道消费方"静默截断"。

本文带你拆解这套机制背后的工程取舍。

先认识：Hotdata CLI 是什么？

Hotdata CLI（当前版本 0.36.1，Rust 编写）的核心循环非常简单：

1. 创建一个即时数据库，把数据装进来（上传 csv/json/parquet，或从 Postgres、S3、Kafka、~150 种 API 服务导入）；
2. 用hotdata query "<sql>"执行 PostgreSQL 方言 SQL；
3. 结果以table、csv、json三种格式输出，可直接进管道。

安装只需一行：brew install hotdata-dev/tap/cli，详见 README.md。

真正的难点不在"查询"，而在取回结果——当结果集从几百行涨到几千万行时，普通 CLI 工具会撞上三堵墙。

大结果集的三大陷阱

第 ② 条不是理论推演：项目注释里记录了一次实测——在单线程"边解码边渲染"的模式下，20M 行传输慢7 倍，最终以error decoding response body收场（慢消费者撑爆了 WAN 链路的接收窗口，长连接被中间层掐断）。

Hotdata CLI 的解法是一条四段式并发管道。

核心机制：一条四段式并发管道

第一步：决定走哪条取数路径

CLI 提交查询时会声明：1 秒内能跑完就内联返回，否则转异步（见 src/commands/query.rs）。

• 快速路径（内联 200）：小结果直接带着行数据返回；
• 慢路径（异步）：返回query_run_id，CLI 每 500ms 轮询一次、最长等 5 分钟，成功后按result_id拉取 Arrow 结果；
• 关键的隐蔽情形：一个"跑得快但结果巨大"的查询会在快速路径上以截断预览形式返回，并附带指向持久化完整结果的result_id。CLI 不会就此打印预览，而是通过 plan_inline 判定后继续追到完整结果集——这是"绝不只给你一半数据"的第一道闸。

第二步：等待结果落盘就绪

大结果在命名它的那次响应到达时，服务端往往还在往存储里写入。open_result_arrow_when_ready 会带着 "waiting for the full result..." 的转圈动画持续轮询，遵守服务端Retry-After提示（钳制在 0.5–5 秒），上限 5 分钟（RESULT_READY_TIMEOUT）——绝不"取一次失败就降级为预览"。

第三步：并发管道——读取与渲染分离 ⚡

这是整个设计的核心，实现于 stream_result_batches：

• 一个独立的异步任务在 tokio 运行时上全速排空套接字，把解码后的 ArrowRecordBatch送入一个容量为 4 的有界队列（tokio::sync::mpsc）；
• 主线程上的同步渲染循环从队列取批、逐行写出；
• 队列满则读取端自动等待——背压确保常驻内存只有"几个批次"，而不是整个结果集；
• 队列以显式Done/Failed消息收尾：BatchMessage 中刻意区分"正常结束"和"读取端崩溃"，否则"截断的下载"会被误读成"结果就这么多"。

一句话：网络线程永远在满速收数据，渲染线程按自己的节奏消费，两边互不拖累。

第四步：按批次流式写出 CSV / JSON

print_streamed_result 用一个 256KB 的BufWriter包裹 stdout（避免"每行一次系统调用"），然后按格式分派：

• csv：stream_csv 表头一行、随后每批数据即编码即写出；
• json：stream_json 手写信封——先写columns等前导字段，rows数组流式展开，最后补上row_count/truncated尾部（因为总行数只有读完全文才知道）；
• table：给人看的表格没有"无限滚"的价值，走 fetch_capped 在服务端用?limit=截到10000 行（还多要 1 行"探针行"来证明后面还有数据），表尾会醒目地打印10000 of N rows — INCOMPLETE PREVIEW，退出码非零，让人一眼看清"这是窗口不是全集"。

为什么选 Arrow：更小的传输体积与类型保真 🧊

完整结果不再走 JSON，而是Arrow IPC 二进制列式流（Accept: application/vnd.apache.arrow.stream）。带来的好处：

• 传输更小：列式二进制比逐单元格 JSON 紧凑得多；
• 原生类型保真：DECIMAL(38,2)这种宽于f64的十进制每一位数字都完整保留（不会被四舍五入成 17 位），带命名时区（Asia/Kolkata）的时间戳能正确格式化，嵌套 list/struct 渲染为真正的 JSON 数组/对象而不是"[1, 2, 3]"这样的字符串；
• 渲染与内联路径字节一致：CLI 与服务端使用同一个 arrow-json 编码器（explicit_nulls等选项刻意对齐，见 Cargo.toml 的 feature 说明与 src/commands/query.rs），"同一查询走快路径还是慢路径，输出形状永远相同"——这由单元测试逐字节钉死。

端到端验证见 tests/results_arrow.rs：任何打印行数的调用都在真实走完一次 Arrow 往返。

防坑设计：把"不完整"变成显式信号 🛡️

这是 Hotdata CLI 最值得借鉴的部分——它宁可失败，也绝不让你拿到"看起来完整实则残缺"的数据：

1. 行数对账：服务端在X-Total-Row-Count头里报告真实总行数，与正文实际行数独立核对；正文提前结束会被捕获并报"上面输出不完整"；
2. 失败语义分层（StreamFailure）：第一个字节写出之前失败 → 回退打印预览，尽量保住已有行；中途失败 → 明确报告"上面的结果是残缺的"；
3. 退出码协议，方便脚本分支：

3这个专门编码（EXIT_INCOMPLETE_RESULT）的意图很明确：让消费方"宁可断链，也不要把子集当全集"。

上手指南：千万行结果的最快拉取姿势 🚀

• 流式落盘：hotdata query "SELECT ..." -o csv > out.csv—— 峰值内存恒为几个批次，边收边写；
• 脚本集成：-o json输出同样流式且信封完整（truncated、total_row_count可判断），配合退出码3做防断链校验；
• 长查询：结果会打印query_run_id，用hotdata query status <id>轮询（0完成 /1失败 /2运行中）；
• 事后取回：结果已持久化，随时hotdata databases results get <result-id>再次拉取，走的是同一条 Arrow 流式通道；
• 表格速览：直接-o table，自动截到 1 万行窗口并明确标注INCOMPLETE PREVIEW。

写在最后

Hotdata CLI 的流式输出本质上是三个工程判断的叠加：用 Arrow 换传输与类型保真，用有界队列的并发管道换吞吐与内存上限，用显式截断信号换管道可信。三件事都不复杂，但组合起来，就是"2000 万行也能稳稳进终端"的全部秘密。