行记录 Upsert（record upsert）

按 recordId 是否存在，自动把入参拆分到 update 链路或 create 链路：批次混合"已存在改 + 新出现建"时用，省掉客户端按 ID 分批的逻辑。

命令

dws aitable record upsert \
  --base-id BASE_ID --table-id TABLE_ID \
  --records '[{"recordId":"<可选>","cells":{...}}, ...]'

flag	说明
`--base-id`	必填（可用 `--base` 别名）
`--table-id`	必填
`--records`	待 upsert 的记录 JSON 数组，单次最多 100 条（必填）
`--records-file`	从文件读入（命令行 JSON 太长时用），与 `--records` 互斥优先级更高

--records 结构

每项 JSON：

{
  "recordId": "rec1",                  // 可选；带 → update，缺省 → create
  "cells": {                            // 必填；key 是 fieldId，value 按字段类型
    "fldTitleId": "新标题",
    "fldNumberId": 42
  }
}

cells 写入格式与 record create / record update 完全一致（key 必须是 fieldId 不是字段名；按字段类型见 aitable-cell-value.md）。

返回结构

{
  "data": {
    "createdRecordIds": ["recX", "recY"],   // 不带 recordId 的项产出
    "updatedRecordIds": ["recA", "recB"]    // 带 recordId 的项产出
  }
}

createdRecordIds 顺序对应入参里不带 recordId的项（按出现顺序汇总），同理 updatedRecordIds 对应带 recordId的项。

典型用法

# 1) 全部新建：所有项都不带 recordId
dws aitable record upsert --base-id BASE --table-id TBL --records '[
  {"cells":{"fldTitleId":"任务1","fldStatusId":"待办"}},
  {"cells":{"fldTitleId":"任务2","fldStatusId":"待办"}}
]'

# 2) 全部更新：所有项都带 recordId
dws aitable record upsert --base-id BASE --table-id TBL --records '[
  {"recordId":"rec1","cells":{"fldStatusId":"已完成"}},
  {"recordId":"rec2","cells":{"fldStatusId":"已完成"}}
]'

# 3) 混合：第 1 条更新（带 recordId），第 2 条创建（不带）
dws aitable record upsert --base-id BASE --table-id TBL --records '[
  {"recordId":"rec1","cells":{"fldStatusId":"已完成"}},
  {"cells":{"fldTitleId":"新增任务","fldStatusId":"待办"}}
]'

# 4) 长 JSON 用文件
dws aitable record upsert --base-id BASE --table-id TBL --records-file ./batch.json

与 record create / record update 的关系

场景	命令
确定全是新增	`record create`
确定全是更新（每条独立 cells）	`record update`
确定全是更新（共享同一 cells）	`record batch-update`
不确定有没有，按 recordId 自动分流	`record upsert`（本命令）

record upsert 的 --records 入参格式与 record update 完全相同，唯一差别是 recordId 字段在 upsert 里是可选的。如果批次确定全是更新或全是新建，用专用命令更清晰；批次混合时（典型场景：定时同步外部数据，源里既有已存在的也有新出现的），用 upsert。

注意事项

单次最多 100 条（创建 + 更新合计），超出请客户端拆批。
cells 的 key 必须是 fieldId 不是字段名（先用 record query 或 field get 拿 fieldId）。
只读字段（formula / lookup / 系统字段）不能写入 — upsert 链路与 update 链路同样限制。

3.3 KiB Raw Permalink Blame History Unescape Escape