在 n8n 中设计内置 Data Tables…

当需要在 n8n 实例内用内置表结构保存查找表、最近事件、计数器、幂等/去重状态并执行增删改查时使用。

适用场景

解决思路

1. 将 Data Tables 用于 n8n 实例内的本地持久状态：查找表、最近事件、每会话库存、计数器、幂等跟踪；仅在有行级逻辑或外部可见性时用于去重状态，普通是否见过值去重不要用它。适合小到中等量，几万行可以，百万行用真实 DB。
2. 每个 Data Table 自动有三列：id（bigserial）、createdAt、updatedAt；不要在 create_data_table 中声明它们，也不要在 insert 时写入它们。
3. 对来自外部的领域标识符（arxivId、stripeCustomerId、requestId）新增单独列，并在该列上做去重/查找键，不要依赖自动 id 作为跨系统标识。
4. 列中只放原始类型；不存在 JSON/object/array 列类型；嵌套数据（数组、解析对象）用 string 列，写入时 JSON.stringify(...)，读取时 JSON.parse(...)，列名加 _object 后缀（如 keyInsights_object），该后缀是让读者解析的契约。
5. 不要在 Data Table 节点前加 Set 节点来修改字段；直接在 Data Table 节点的每列表达式槽位映射，或重命名上游字段以启用 auto-map。
6. 用户列使用与 n8n 自动管理列一致的 camelCase，例如 arxivId、paperId、taxRate；避免同一查询中混用 createdAt >= ... AND arxiv_id eq ...；stringified-blob 列继续保留 _object 后缀。
7. 创建/更新后通过 get_workflow_details 验证 columns 参数；UI 手动映射模式可能显示 “Currently no items exist” 且无实际数据丢失，检查 JSON 确认持久化内容。
8. 当数据确实是父子结构时使用关系设计：用父行 id 引用父行；在列名中显式命名（paperId、customerId）；在工作流逻辑中强制完整性；不要强加于无关系的扁平场景（去重、查找、审计）。
9. 存储格式不是接口格式：从子工作流返回 _object 字段前先解析；调用方不应收到需要自行解析的字符串化外壳。
10. 默认列 id：bigserial/number，自动递增主键，n8n 在 insert 时分配，你不能写入，插入响应返回它。
11. 默认列 createdAt：timestamp，在 insert 时自动设置。
12. 默认列 updatedAt：timestamp，每次 update 时自动刷新。
13. 查询时使用系统列而不是自建时间戳列：如 “Created today” 用 createdAt >= '<today ISO>'；“Updated since last sync” 用 updatedAt >= $('Last Sync').item.json.timestamp。
14. 不要把自动 id 用作跨系统标识符；它是内部使用，表重建或实例迁移会重置；跨系统引用用领域 ID 列。
15. 关系完整性：插入子行前查找父行；删除父行前决定子行处理（删除、孤儿、归档）；n8n 不会级联；监视陈旧引用，使用软删除或清理工作流。
16. 对复杂关系结构（3+ 表带 join、事务写入），改用真实 SQL DB。
17. insert 操作：总是新增，n8n 分配 id。
18. upsert 操作：新则添加、存在则更新；需要 matchType 和 filter 判断存在。
19. update 操作：修改匹配 filter 的行；无匹配不插入。
20. get 操作：获取匹配 filter 的行（0+）；支持 orderBy、limit、returnAll。
21. deleteRows 操作：删除匹配 filter 的行。
22. rowExists / rowNotExists 操作：对传入 items 做布尔式过滤；常用于去重分支。
23. 完整操作面（filter 语法、matchType、排序模式）读 references/OPERATIONS.md。
24. UI quirk：当 SDK 保存手动模式列映射（mappingMode: 'defineBelow'）后，n8n UI 的 “Values to insert” 面板可能渲染为空（“Currently no items exist”），即使运行时正确持久化。
25. 若用户报告 Insert 节点“看起来坏了”或“没有字段”，告诉用户这是 UI 显示问题，按 columns 参数上的 reload（refresh）按钮，会重新填充 schema 并渲染映射；无数据丢失，任何时候安全。
26. 普通“是否见过此值？”去重默认用 Remove Duplicates 节点（“items seen in previous executions” 模式）；它是单节点方案，有内部存储，无需维护 schema。
27. 只有满足以下条件才让 Data Tables 承接去重状态：你会查询或检查去重状态（仪表盘、审计、最近一周处理了什么）。
28. 只有满足以下条件才让 Data Tables 承接去重状态：命中时有行级逻辑（按类别 TTL，例如 category A 过期 30 天、category B 过期 7 天；基于存储状态条件重处理；按状态列分支）。
29. 只有满足以下条件才让 Data Tables 承接去重状态：需要按租户/用户命名空间，而 Remove Duplicates 的 history-store 无法表达。
30. 满足条件时的去重流程：[Source: { arxivId, ... }] -> [Data Table Get: filter arxivId eq $json.arxivId, limit 1] -> [IF: result has items?]；Yes -> [Skip，或根据存储行应用行级逻辑]；No -> [Process] -> [Data Table Insert: { arxivId, ...rest }]。
31. 完整去重模式（upsert、rowNotExists、Get+IF、幂等键）读 references/DEDUP_PATTERNS.md。
32. 查找表流程：稳定参考数据（country -> tax rate、plan -> feature flags），通过 n8n UI 编辑，工作流执行时读取：[Data Table Get: filter country eq $json.country, limit 1] -> [使用查到的行的 taxRate 等]。
33. 最近事件/审计跟踪流程：只追加插入，之后查询：[Workflow event] -> [Data Table Insert: { userId, eventType, payloadSummary }]；createdAt 让“最近一小时事件”无需自建时间戳。
34. 参考文件读取时机：设计列/类型、无 FK 关系模式、mapping mode（defineBelow vs autoMapInputData）、判断何时 Data Tables 是错误工具时读 references/SCHEMA_DESIGN.md。
35. 参考文件读取时机：需要完整操作面（insert/upsert/update/get/delete/rowExists）、filter 语法、matchType、orderBy 时读 references/OPERATIONS.md。
36. 参考文件读取时机：需要幂等键、RemoveDuplicates 节点 vs Data Table 去重、search-then-insert vs upsert 时读 references/DEDUP_PATTERNS.md。
37. 表达式纪律（$json vs $('Node Name').item.json、Set-node 反模式）参考 n8n-expressions-official；Merge 收敛和同形分支参考 n8n-node-configuration-official references/MERGE_NODE.md。
38. 反模式：Set 节点放在 Insert 上游“塑造输入”；修复：直接在 Insert 节点每列槽位映射，或重命名上游字段以启用 auto-map。
39. 反模式：在 create_data_table 中声明 id、createdAt、updatedAt；修复：不要声明，它们已经存在。
40. 反模式：把应用关键数据存 Data Tables；修复：用真实 DB 存不能丢的数据。
41. 反模式：把跨应用 system-of-record 放 Data Tables；修复：用真实 DB。
42. 反模式：把自动 id 当稳定跨实例标识；修复：用领域 ID 列（arxivId、requestId）做跨系统引用。
43. 反模式：假设外键级联；修复：软删除，或运行维护引用完整性的清理工作流。
44. 反模式：引用立即前一个节点而中间节点剥离 json；Insert 会静默写入 NULL；修复：按名称引用稳定上游节点，或用 NoOp/Merge 收敛锚点。
45. 反模式：手动映射模式 + Set 节点修复 “Currently no items exist”；修复：用 get_workflow_details 验证 columns.value 有映射，运行时正常；告诉用户按 columns 参数 reload 按钮让 UI 渲染字段。
46. 发布前验证 1：validate_workflow 通过。
47. 发布前验证 2：get_workflow_details 检查每个 Data Table 节点的 columns；value 和（手动映射时）schema 均已填充。
48. 发布前验证 3：test_workflow 用 pinned data；Insert 响应应包含 id、createdAt、updatedAt。
49. 发布前验证 4：通过 UI 或后续 Get 检查实际 Data Table 内容，确认列没有静默 NULL；第一次接新 Insert 尤其要做，因为上下文剥离的中间节点 + 手动映射 + UI quirk 会静默产生 NULL 列。

适用边界 · 注意事项

• 不要把应用关键、不能丢失的数据或需要作为跨应用 system-of-record 的数据放在 Data Tables；应使用真实 DB。
• 不要用 Data Tables 处理复杂关系结构（3+ 表带 join、事务写入）或百万级数据；应使用真实 SQL DB。
• 普通“是否见过此值？”去重、无需查询/行级逻辑/租户命名空间时，不要用 Data Tables，默认用 Remove Duplicates 节点。