简介：这份《Coze数据库详细使用操作手册》面向具备编程基础、正在研发AI智能体的开发者，系统讲解Coze数据库在智能体中的落地用法。内容先梳理其轻量级NoSQL定位与核心能力，包括增删改查、自然语言查询、代码集成、数据关联及自动化触发，再结合用户状态管理、动态知识库、交互记录分析、临时缓存等典型场景，给出从创建智能体、自定义或模板建表、添加字段，到在工作流中配置数据库插入与查询节点的完整操作演示，帮助读者独立完成数据表创建、数据写入和检索。资源包含1个PDF文档，压缩包大小约2.87MB，适合边读边练。已有351人学习下载，适合希望快速掌握Coze数据库配置与使用的研发人员参考。
1. Coze数据库使用：不是存储桶，是智能体的记忆层
做coze工作流搭建的人大概率都有过这种感觉：工作流跑通了、回答也正确，但关掉对话后一切归零，下一次用户进来，智能体完全不记得之前聊过什么。Coze数据库就是专门解决这个问题的——它本质是一个轻量级NoSQL数据库，用数据集（Collection）当“表”，数据项（Item）当记录，字段存键值对，支持嵌套结构。你可以在工作流的数据库节点里把用户提问、大模型回答、业务参数持久化落库，后面需要时再用查询节点把数据读回来，让智能体真正具备跨会话的连续性。这份资源覆盖建表、写库、查库、多用户模式和常见翻车点，适合正在做AI智能体落地、卡在状态保存和业务数据回流上的开发者。
2. 数据模型与建表：数据集、数据项、字段，以及两类创建入口
在扣子（Coze）里操作数据库之前，我建议先把它的数据模型对齐。这个数据库不是传统关系型数据库，不能按MySQL的习惯去设计表结构；它更像MongoDB那类文档型存储，字段可以灵活增删，也允许嵌套。这个认知直接决定了你后面配置查询条件时顺不顺手。
2.1 数据集的定位：像表但不是关系型表
Coze数据库的结构分三层：数据集（Collection）、数据项（Item）、字段（Field）。数据集用来分类存储数据，比如用户配置、商品信息、对话记录各建一个数据集，相当于逻辑上的“表”；数据项是数据集中的单条记录，一条记录就是一个键值对组合；字段则是记录里的具体属性，比如一条用户数据里可以有user_id、name、preferences这些字段。
这里要特别注意，数据集和表不是一回事。关系型表有严格的列约束，字段类型和顺序基本固定；而Coze的数据集对字段类型没那么苛刻，甚至允许一条记录有另一条没有的字段。这种灵活性在智能体场景里很实用，比如存用户偏好时，有的用户有language字段，有的没有，不会因为缺字段就写不进去。
我自己的使用习惯是：对话记录类数据单独建一个数据集，用户配置单独建一个，产品信息再单独建一个。不要把所有东西塞进同一张“表”，因为Coze的查询节点是按数据集维度去筛选的，数据混在一起，后面做条件查询会非常难受。
2.2 自定义表与模板表：选型判断
创建数据表时，Coze提供了两个入口：自定义数据表和基于模板创建。模板表的本质是系统给了你一套预设字段的参考表，比如客服场景的表可能已经带好了user_name、question、answer、status这类字段，你直接在此基础上调整即可。
我做项目时的判断标准是：如果智能体的业务逻辑还处于原型验证阶段，直接基于模板创建，省时间去跑通流程；如果已经明确知道要存什么数据、字段是什么含义，就自定义数据表。模板的价值在于给没设计过数据结构的人兜底，避免连字段都不知道从哪下手；但模板字段通常偏通用，真正贴合业务还是得自己微调。
| 维度 | 自定义数据表 | 基于模板创建 |
|---|---|---|
| 字段自由度 | 完全按需定义 | 基于预置字段调整 |
| 上手速度 | 稍慢，需要先想清楚字段 | 快，适合快速验证 |
| 适用场景 | 业务字段明确、有定制化需求 | 原型验证、通用客服/记录类场景 |
| 后续维护 | 字段按业务演进自行迭代 | 多余字段需手动清理 |
如果选自定义表，创建表单里要填写两样东西：数据表名称和数据表描述。名称建议用英文或拼音的驼峰风格，描述写清楚这张表是做什么的就行；这段描述Coze会读取，后续起着辅助理解的作用。
2.3 字段命名规范与系统预留字段
创建完数据表，进入编辑页，你会发现Coze默认内置了几个必要字段，而且这几个字段无法删除。这是它的硬性规则，不需要去纠结能不能删，实际用下来这些预留字段通常也不影响业务逻辑。
需要重点注意的是新增字段时的命名规范。Coze对字段名有格式要求，不能随便用中文、空格或特殊符号。我在第一次建表时图省事用了一个带连字符的字段名，结果保存时直接报错，排查了半天才发现是命名的问题。
推荐的做法是：统一使用小写字母开头，多个单词用下划线连接，例如question_content、answer_content、user_id。字段名定下来之后不要频繁修改，因为工作流里的数据库节点是通过字段名做变量映射的。你改一个字段名，所有引用了这个字段的节点配置都要跟着改，非常容易遗漏。
字段添加的顺序也有讲究。我把用户标识类的字段放在前面，业务内容字段放后面，原因是在查询节点里，字段是按列表顺序展示的，常用的过滤字段排前面可以少滚动几次鼠标。这个纯属个人习惯，但确实能提升配置效率。
3. 写数据：工作流里的数据库节点，从变量映射到落库验证
建好数据表只是第一步，真正让数据流动起来，要靠工作流里的数据库节点。这一章我和实际操作流程放在一起讲，跟着做一遍就能完整走通“用户提问→大模型生成回答→写入数据库”这条链路。
3.1 创建智能体并添加数据库入口
先到项目开发一栏创建一个智能体，创建完成后进入智能体编辑页面。在编辑页中间可以看到一个数据库的选项，这就是给智能体挂载数据库的入口。点击右侧的加号，会弹出创建数据表的窗口，里面就是刚才说的自定义和模板两个入口。
这里有一个我个人觉得值得提醒的点：数据库是和当前智能体绑定的，但它的数据并不像某些平台那样完全封闭。你在工作流里引用数据表时，能看到当前工作空间下可用的数据库列表；如果同一个团队下多个智能体共用一个工作空间，注意表名尽量带业务前缀，比如customer_feedback、order_records，避免多个智能体之间表名混淆。虽然Coze在添加数据库时能区分具体是哪张表，但命名清晰总归能少一些认知负担。
3.2 自定义数据表实操：字段类型与字段追加
以对话记录表为例。我用自定义方式创建了一张名为chat_records的数据表，描述写的是“存储用户提问和智能体回答，用于交互记录分析”。创建成功后进入编辑页，能看到系统预留字段。接下来要追加的字段有两个：
- question：文本类型，存用户的问题内容；
- answer：文本类型，存大模型的回答结果。
字段类型的选择直接影响后续的数据处理。比如question如果要用模糊匹配去查询，必须是文本类字段；如果你打算把answer再交给其他大模型去二次分析，就别把它定义成枚举或数字类型。Coze默认字段类型对大部分对话记录场景是够用的，但如果涉及数值计算，比如缓存API调用耗时，字段类型建议单独确认。
添加完字段后点击保存，回到智能体编辑页，就能在数据库列表里看到这张刚建好的表了。到这一步，数据表的骨架已经完成。
3.3 工作流中配置数据库插入节点：字段值来源与变量映射
接下来在智能体中把这张表用起来。以我之前的一个客服智能体为例，工作流的结构是：开始节点捕获用户输入 → 大模型节点生成回答 → 数据库节点把问题和回答写入chat_records表。
数据库节点的配置核心是“字段值从哪里来”。点击数据库节点右侧的加号，选中chat_records表，系统会把表里的核心字段列出来。需要做的就是把question和answer两个字段分别绑定到工作流中的变量：
| 字段 | 取值来源 | 示例变量 |
|---|---|---|
| question | 开始节点中的用户输入 | {{start.user_input}} |
| answer | 大模型节点的输出参数 | {{llm.output}} |
这个映射关系看起来简单，但经常有人在这里翻车。常见错误是把answer字段直接绑定到大模型节点的整个输出对象，而不是具体的文本参数。如果大模型节点配置了多个输出参数，比如answer和summary，你要在数据库节点里精确选择answer这一个，否则写进去的数据会包含JSON结构，查询时处理起来相当麻烦。
配置完成后，把数据库节点引出到结束节点，点击试运行。试运行结束后，到资源库里找到chat_records表，就能看到刚插入的一条测试数据。如果你能看到question和answer都正确落库，说明写入链路已经打通。
有个细节我在配置时也会加一步：在数据库节点前面放一个代码节点或条件节点做数据校验。比如判断大模型的输出是否为空，为空就直接走兜底分支，不执行写入。这样做可以避免把空字符串或无效回复写进库里，后面的查询结果会干净许多。
4. 查数据：查询节点、自然语言解析与大模型提示词的配合
数据落库后，下一步就是把它查出来用起来。Coze数据库支持自然语言查询，但在工作流里，查询节点执行的还是结构化匹配逻辑，这种差异是很多查询“查不到”的根源。这一章重点讲清楚查询节点的配置思路，以及怎么用大模型节点去垫平“自然语言”和“结构化查询”之间的落差。
4.1 查询工作流：为什么前面要挂一个大模型节点
先看一个场景：用户问“帮我查一下小明上次反馈的问题”。如果直接在数据库节点里把查询条件设为“question等于用户输入”，那命中的概率几乎为零——用户输入是完整的一句话，而表里存的也是完整问题，除非一字不差，否则精确匹配必然落空。
所以我在查询工作流里，会在数据库节点前面加一个大模型节点，它的任务是从用户的自然语言里提取出查询参数。比如要求大模型只从用户输入中解析出用户名，输出格式限定为“username”，然后在数据库节点里用这个参数去匹配user_name字段。
这个过程本质是把自然语言查询转化为结构化参数。有一点需要在系统提示词里反复强调：大模型最终解析的返回参数只能输出用户名，不要带任何解释、标点或多余的修饰词。我见过最典型的失败案例就是大模型输出“用户是张三”，结果数据库节点拿“用户是张三”去匹配，查了个空。
4.2 查询条件设置：等于、模糊匹配与返回字段选择
添加数据库节点时，要选择“查询数据”这个功能项，不是写入。然后在配置表单里点添加数据库，选中chat_records表，系统会把表里的字段全部列出来。这里要选择参与查询的字段和返回的字段。
参与查询的字段就是过滤条件用的，我一般会选user_name字段；返回字段则看你下游要什么。比如只做身份确认，返回一个user_id就够了；做客服工单提取，则需要把question、answer、create_time都带上，多选几个返回字段不会影响查询性能，但会让下游节点收到更多数据，增加调试时的噪声。
查询条件的内置运算符还是比较全的：等于、不等于、模糊匹配、范围查询等都有。具体用哪个，取决于你的数据特征。精确匹配适合user_id这种唯一值；模糊匹配适合关键词检索，比如在question字段里查“退款”相关的记录，条件值填“退款”就能命中的所有相关历史问题。
这里有一个我踩过的坑：模糊匹配的关键词不能带正则符号。Coze的模糊匹配是包含语义，不是正则匹配。如果你把“退款|退货”当关键词，它匹配的是字面量“退款|退货”，而不是“退款”或“退货”。要做多关键词查询，要么拆成多个条件组合，要么在数据写入时做人工标签字段，比如提前给每条记录打上issue_type。
4.3 单用户与多用户模式：什么时候会查不到数据
Coze数据库支持单用户和多用户两种查询模式，这个设定直接影响你能不能查到数据。官方说明里有一个关键句：多用户模式仅在数据库节点中生效，也就是在工作流的数据库读写节点里才体现差异。
两者的区别用一句话概括：单用户模式下，数据库只存开发者自己的数据；多用户模式下，数据按使用者隔离，用户A写入的数据，用户B在工作流里查不到。
实际使用建议是：如果是智能体自己沉淀知识库、FAQ这类共享数据，用单用户模式就好；如果做的是“每个用户有自己的配置和偏好记录”，那必须开多用户模式，这样才能保证用户A只能读到自己的数据，不会串到用户B的隐私。
常见的翻车场景是：开发者自己在试运行窗口测试时，写入了一条记录，然后直接在对话里用另一个账号去问智能体，结果查不到。这不是节点配置错误，而是多用户模式的数据隔离在起作用。
| 模式 | 适用场景 | 数据可见性 | 数据库节点中的生效范围 |
|---|---|---|---|
| 单用户 | 知识库、共享业务表 | 所有用户共享 | 写入、查询均生效 |
| 多用户 | 用户配置、个性化偏好 | 按用户隔离 | 仅在数据库节点中生效 |
顺便提一下跨数据集关联。Coze数据库支持类似Join的关联查询，比如把用户表和订单表关联。但我在实际项目中，通常更倾向于在写入时就冗余关键字段，因为工作流里的关联查询调试起来比写SQL要繁琐，而且节点配置复杂后，后续维护成本会明显上升。除非是强依赖数据一致性，否则尽量用简单查询。
5. 避坑与排查：Coze数据库节点最常见的四个翻车现场
这一章直接从实际问题出发，我把过去折腾Coze数据库时遇到的和同行交流来的高频问题逐一拆开讲。每个问题都按现象、原因、解决的顺序来，方便你直接对照排查。
5.1 字段命名不规范导致保存失败
现象：在自定义数据表里添加字段时，点击保存后提示错误，字段始终没能添加成功。
原因：字段名里带了中文、空格、连字符或特殊符号。Coze对字段命名有格式要求，不符合规范的表单会被系统拦截。
解决：将字段名改成英文小写开头、下划线分隔的风格，比如request_content、response_content，再重新添加。注意字段名一旦被工作流引用，尽量不要改，否则所有引用点都要跟着调整。
5.2 大模型输出与查询条件类型不匹配，查不到数据
现象：数据库中明明存在记录，但通过查询节点执行结果为空。找遍业务流程也没发现逻辑差异，配置看着都对。
原因：前置大模型节点输出的参数是自然语言描述，比如“用户是张三”，而查询节点里条件字段期望的匹配值是“张三”，因为Coze的匹配规则是精确或包含匹配，不会智能理解。大模型输出里多一个“用户是”前缀，匹配就失败。
解决：在系统提示词里明确约束输出格式，例如“只输出用户名，不要输出任何解释文字或其他内容”，并在数据库节点前增加一个代码节点做trim处理，把前后空格去掉。这属于最稳妥的双保险。
5.3 单用户与多用户模式理解错误，数据串台或缺失
现象：多用户模式下，用户A在工作流中写入的数据，用户B在对话中无论如何也查不到；或者开发者自己测试时写入的数据，在以普通用户身份对话时消失。
原因：把多用户模式当成了共享表来用，忽略了数据按用户隔离的机制。多用户模式只在工作流的数据库节点中生效，数据隔离是功能特性，不是Bug。
解决：先想清楚这张表的归属。共享数据用单用户模式；用户私有数据用多用户模式。不要在需要共享的表上开多用户，也不要在用户私有场景里用单用户模式，否则会造成隐私数据越权读取。
5.4 查询条件过多过严，导致结果集趋近于零
现象：工作流试运行时，返回的记录数明显少于预期，有些合法数据也被过滤掉了，怀疑是查询节点表达式有问题。
原因：查询条件叠加时，多个条件之间默认是AND关系。比如既要求user_name等于某值，又要求question包含某关键词，同时还限制时间来缩小范围，条件越严则命中越少。
解决：先逐条测试条件，确认每一条都能单独命中，再叠加组合。实际项目中我优先用单条件查询，然后在代码节点里做二次过滤；确实需要多条件时，至少留一个字段作为宽松的模糊匹配，不要全部用精确匹配。
5.5 数据库变更触发不生效，自动化流程未启动
现象：配置了数据变更的监听事件，但数据库里插入新记录后预期的后续动作（比如发送通知、更新缓存）没有发生。
原因：监听事件需要与工作流的触发方式配合。如果工作流本身是手动触发或定时触发，不会因为数据变化自动执行端到端流程。数据库变更触发是单向事件，只会启动绑定了该事件的那个工作流，不会反向驱动其他工作流。
解决：检查监听事件绑定的工作流触发方式是否配置为自动触发；同时确认数据库节点修改后已保存并重新发布。数据库节点的配置变更后，直接试运行有时会走旧配置，我的习惯是保存后刷新页面，再发布到测试环境，最后试运行。
6. 进阶用法：把用户回流数据做成一个可校验的闭环
学完写入和查询，最后分享一个我每次搭完数据库节点都会做的收尾动作：在智能体里构建一个可追溯的“数据回流”闭环。这个做法能让数据不是躺在数据库里吃灰，而是反过来验证智能体本身的运行状态。
具体操作分三步。第一步，在工作流末尾把关键交互数据全部落库，不只是question和answer，还包括用户标识user_id、时间戳create_time，这样事后分析时能按人、按时段拆解。第二步，在智能体里增加一个查询工作流，让系统自然语言回答“最近X天有多少条对话”“某个用户提过哪些问题”这类统计需求。第三步，我在工作流里挂一个JavaScript代码节点，每次写库后读取数据库节点返回的写入状态：
// 读取数据库插入节点的返回状态，判断本次写入是否成功 const dbResponse = db_insert_output; // 数据库插入节点的输出变量名按实际节点替换 if (dbResponse && dbResponse.insertId) { console.log("写入成功，记录ID: " + dbResponse.insertId); } else { console.log("写入失败，请检查字段映射或变量来源"); }这段脚本不复杂，但它能把“数据是否落库”变成一个显性信号。试运行的时候，我会特意输入几种不同形态的问题：带标点的、带多余空格的、包含数字的，确认查询节点在模糊匹配下也稳定。发布后再跑到数据库资源页，核对最终写入的记录数，手工删掉测试行。
从那以后，我每次在智能体里动数据库节点，都强制走一遍“保存 → 试运行 → 资源库核验记录 → 删除测试行”的流程，能拦下一大半低级问题。这套习惯帮我少熬了很多夜，希望帮到你。
本文还有配套的精品资源，点击获取
