Hotdata CLI 的5种加载模式揭秘:一次搞定数据表的增删改,告别重复导入

原创2026-10-10 12:57:101,379 阅读

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 在命令行里给你的完整增删改工具箱。

登录后查看全文
hotdata-cli