Hotdata CLI 的5种加载模式揭秘:一次搞定数据表的增删改,告别重复导入
Hotdata CLI 的5种加载模式揭秘:一次搞定数据表的增删改,告别重复导入
Hotdata CLI 是 Hotdata 的命令行工具,一条 databases load 命令即可把 csv、json、parquet 文件导入即时数据库表。很多人只知道它会"覆盖导入",其实它内置了 5 种加载模式(load modes):整表替换、追加行、按主键删除、更新、插入或更新(upsert),一张数据表的增删改全部一条命令搞定,彻底告别"导一次全量"的重复劳动。
5种加载模式全景图:一张表看懂怎么选
--mode 参数共接受 5 个取值,源码中由 clap 严格限定,写错会在解析阶段直接报错(不会把坏参数发到服务端):
| 模式 | 一句话说明 | 是否需要主键 |
|---|---|---|
replace(默认) |
清空整表,用新数据全量替换 | ❌ |
append |
把新行加到表末尾 | ❌ |
delete |
按主键值删掉对应行 | ✅ |
update |
只更新与主键匹配的行 | ✅ |
upsert |
有则更新、无则插入(最实用) | ✅ |
参数定义见 src/commands/databases.rs,回归测试确保 5 种取值都能在 --help 中完整发现:tests/databases_cli.rs。
模式一:replace 全量替换——默认行为,省心但费流量
什么都不写就是 replace:
hotdata databases load --catalog sales --table orders --file ./orders.csv
适合周期性全量快照(每天导出一次完整表)。注意它是"整表覆盖"——只上传了部分数据时,其余行会丢失,这是新手最常踩的坑。
模式二:append 追加行——增量攒数据,支持旧写法
hotdata databases load --catalog sales --table orders --file ./new-orders.csv --mode append
早期的 --append 开关是它的简写,两者互斥、不能同用(解析层会直接拒绝,见 tests/databases_cli.rs)。append 只做加法:不会去重、不会更新旧行,适合日志类只增不改的表。
模式三:delete 按键删除——文件里只需带主键列
hotdata databases load --catalog sales --table orders --file ./removed.csv --mode delete
removed.csv 只需包含主键列,服务端按主键值匹配删除对应行。这让"下架一批订单""清除测试数据"这类操作不用写任何 SQL。官方工作流示例见 skills/hotdata/references/WORKFLOWS.md。
模式四:update 按键更新——只改存在的行
hotdata databases load --catalog sales --table orders --file ./changed.csv --mode update
主键匹配到的行被更新,匹配不到的行直接跳过(不会新增)。适合"只修数据、不扩数据"的修补场景。
模式五:upsert 有则更新无则插入——增量同步的终极答案
hotdata databases load --catalog sales --table orders --file ./changed.csv --mode upsert
主键存在 → 更新该行;不存在 → 插入新行。一次上传同时完成"新增 + 修改",是把下游系统增量同步进 Hotdata 表的标准姿势。配合 delete 模式,增删改全覆盖:
| 同步场景 | 推荐模式 |
|---|---|
| 每天全量导出一次 | replace |
| 只增不减的日志表 | append |
| 业务系统改了若干订单 | upsert |
| 订单被取消要删行 | delete(文件只带订单号即可) |
| 纯修数据不扩表 | update |
关键前提:先用 tables add 声明主键(之后无法补)
delete / update / upsert 三种"按键模式"都有一个前提——表必须声明过主键,而且主键只能在建表时声明,已存在的表无法后补(这一点在 src/commands/databases.rs 的注释中写得很明确)。
所以正确顺序是:
# 1. 先建表并声明主键(复合主键可重复写 --key)
hotdata databases tables add orders --key order_id --sorted-by created_at=desc
# 2. 再加载数据,从此 upsert/delete/update 全部可用
hotdata databases load --catalog sales --table orders --file ./orders.csv
两个实用技巧:
- 临时指定主键:忘了建表时声明,可单次加载时用
--key order_id指定;复合主键写多个,如--key tenant --key id。 - 按键模式不能配
--result-id:从已保存查询结果加载时服务端会带出全部列,无法满足"按键匹配"的形状要求,CLI 会提前拦截并提示改用--file/--url(见 src/commands/databases.rs 及 tests/databases_cli.rs)。
常见坑与排查清单 🧭
| 现象 | 原因与解法 |
|---|---|
--append 和 --mode 一起用报错 |
两者互斥,--append 只是旧写法,任选其一 |
--mode merge 报 "invalid value" |
只接受 5 个取值,拼写要精确 |
| upsert 报找不到主键 | 建表时漏了 --key,且老表无法补主键 → 需重建表 |
用 --result-id + --mode delete 被拒 |
按键模式需要主键形状的文件,改用 --file/--url |
| replace 后数据"少了" | replace 是整表覆盖,增量场景请换 append 或 upsert |
按键模式自 0.33.0 版本引入,变更说明见 CHANGELOG.md;完整命令清单见 README.md。
小结
记住这张心智图:整表操作看 replace/append,行级增删改看 delete/update/upsert,一切按键模式都始于建表时的 --key。掌握这 5 种加载模式后,数据同步从"每次全量重导"进化为"只传变化量"——这正是 Hotdata CLI 在命令行里给你的完整增删改工具箱。