集合与数据
在 GetMyBot 中建立数据表,保存申请、订单与预约,并在反应中查询和修改。
本页内容
集合类似数据表:每一行是一份申请、一笔订单或一次课程预约。机器人可根据用户回答添加记录,您也可以在数据 → 集合中查看和编辑。
例如,为咨询预约建立 leads 集合,添加 name、phone、topic 字段。机器人提问后,将姓名、电话和主题保存到同一行,之后还可在反应中查找。
什么是集合
字段是列,例如“电话”和“主题”;记录是一行的值。字段名称和类型组成集合结构。记录实际以 JSON 文档保存,因此添加字段不需要重建已有记录。
集合名在同一机器人内唯一,也是反应动作中引用它的标识符,例如 leads、orders、scores。
字段类型
| 类型 | 保存内容 | 示例 |
|---|---|---|
text | 文本 | 姓名、电子邮件或备注 |
number | 数字 | 金额、数量或积分 |
bool | 是或否:true / false | 订单是否已付款 |
datetime | 日期和时间 | 课程预约时间 |
json | 嵌套对象或列表 | 含商品属性的订单明细 |
类型决定界面如何编辑字段,以及保存时如何转换值。结构不是严格限制:结构中没有的字段也会保存,并显示为单独一列。
创建集合
- 打开数据 → 集合,点击添加。
- 输入名称,建议使用无空格的拉丁字母名称,方便在反应中引用。
- 点击字段添加所需列,逐一选择类型。
- 如有需要,设置下方的保存规则,然后保存。
查看与编辑记录
集合卡片上的表格图标会打开该集合的数据窗口:
- 查看:逐行显示记录,最新的排在前面。
- 添加记录:按字段类型填写表单;
bool使用开关,json使用 JSON 输入框等。 - 编辑(铅笔图标):修改已有记录。
- 删除(垃圾桶图标):删除记录。
机器人反应也能自动写入记录;手动编辑和自动写入使用同一个集合。
保存期限(retention)
可以设置自动清理,避免集合无限增长:
- 最多保留记录数:超出时删除最旧的记录。
- 最长保留天数:删除超过指定天数的记录。
例如,临时日志可保留 30 天。清理会定期执行,并非恰好在到期时运行;两种限制可同时使用。仍需处理的订单不要设置会提前删除它们的期限。
在反应中处理数据
- 创建记录:以
{{user_id}}、{{text}}等替换内容填写一行。可设置去重键,使同键的再次调用更新原记录,例如每个用户只保留一份当前申请。 - 更新记录:修改符合条件的行。
- 查询记录:把记录作为数组载入
ctx,供后续遍历。 - 读取集合页面(
record_page):分批读取记录,例如一次显示两张卡片,并提供“下一页”按钮。 - 汇总整个集合(
record_aggregate):按保存规则允许访问的所有匹配记录计算数量和金额;只加载了第一页也不会限制此计算。 - 集合原子事务(
collection_transaction):检查条件并一起保存多项更改,例如占用名额并创建申请;发生冲突时,之前的更改也会回滚。 - 删除记录:按条件删除行。
- 循环(for-each):遍历上下文中的数组,逐项更新、计算或向外部服务发送数据。
这样可以在 GetMyBot 内管理客户资料、申请、积分和报表,不必另建数据库。集合练习展示目录续页、整个集合的订单汇总与最后名额的预订。已载入列表的一页、集合的一页与整个集合的汇总,分别解决不同问题。
循环不能代替群发。 单次循环最多处理 500 项,而一个事件最多发送 50 条消息。若循环逐项发消息,前 50 条可以进入队列,其余会因限额失败。向集合中的人群发时,先建立人群分组,再使用群发,以便控制速度、暂停和统计。见动作:单个事件的预算。
商品目录:搜索、选择与详情
先看查找课程练习,了解如何准备集合、设置动作顺序,并检查无结果、多结果和旧按钮。
目录数据可与反应分开保存。例如 products 集合含 name、aliases,variants 含 product_id、name、card。在 variants.product_id 字段启用关联另一集合,选 products、键 _record_id 和显示字段 name。此关联只说明字段含义,不会级联更新或删除记录。
- 在入站文字反应中添加搜索集合(
record_search)。选择products,查询{{text}},搜索字段name,同义词字段aliases,结果名search。同义词可以是文字或 JSON 字符串数组。搜索不区分大小写及俄语е/ё,标点会换成空格。 - 添加选择下一步(
branch_result),来源设为search。按先后顺序处理结果不完整(请用户缩小查询)、未找到、模糊匹配(请用户确认)、一条记录和多条记录。首个匹配分支生效;“未找到”和“一条记录”要求结果完整。 - 多个结果时,在消息中选择从找到的记录生成按钮。指定
search、文字字段name和下一反应。助手会设置buttons_from.over = search.rows、文字模板和carry.selected_id = {{item._record_id}}。确认返回字段包含name;仍可在高级按钮编辑器中调整。 - 在下一反应添加查找关联记录(
record_related):集合variants,键product_id,值{{ctx.selected_id}},结果名variants。要读取所选商品本身,用products和_record_id。如果关联使用自定义业务键,按钮助手和读取动作都应选择该键。 - 再根据结果选择分支。一条记录可用
{{ctx.variants.first.card}}显示详情;多种规格可生成按钮。按钮只传 ID,点击后再读取最新数据,不要将可能变化的商品详情放入 Carry。
读取结果
search.rows 是记录列表,search.count 是已载入行数,search.first 是第一条记录,search.first.name 是该记录的字段。每行另外包含保留字段 _record_id、_score 和 _match_type。没有记录时,之前的第一条记录及其字段会被清空。
search.total 只统计已检查的候选项。total_exact = false 表示尚未检查完整集合,truncated = true 表示结果受到截断;此时不能把结果当作完整列表,也不能保证找到了全库最佳匹配。单次最多检查 10,000 条记录和 16 MiB 数据,响应会说明实际限制。默认最多返回 100 行,上限 10,000 行。
测试与解释搜索
在搜索编辑器中打开测试搜索,输入具体查询文字或 ID。测试只读取数据,不执行后续反应、消息或动作;附加筛选中的替换内容须先换成具体值。测试会显示记录、匹配类型、检查数量和限制。更换项目、集合、设置或访问权限后,旧测试结果会隐藏。
执行日志显示搜索字段、匹配类型、检查和返回的记录数、结果限制及选择的分支。反应图中会标出通向同一反应的全部条件。若您有权查看事件内容,重新打开该执行事件时也能看到搜索解释。
按钮助手默认最多生成 20 个按钮,最多按钮数可设为 1 至 100。这是数量限制,不是分页;空列表不会生成按钮。结果太多时,请让用户缩小查询。计算动作中的对已载入列表执行操作助手可生成记录数、第一条记录、字段总和与标题列表公式;不完整结果的计算不是整个集合的汇总。
API 与 MCP
同样的操作可通过 POST /api/bots/{botID}/collections/{name}/search 和 /related,或拥有 collections:read 权限的 MCP 工具 search_records、related_records 使用。请求仅针对当前项目和区域。REST 测试需传具体值;反应动作才会解析模板替换内容。
处理结果与有条件修改
list_transform 可筛选、排序、去重或分页处理集合结果;list_aggregate 可对已载入的行计算命名汇总,也可分组。这些动作也适用于 HTTP 响应中的普通列表,不要求使用集合。
为避免两个同时运行的流程重复变更状态,可用 record_update_if 指定记录 ID、预期字段和新值。单条记录的检查与修改以原子操作完成,结果 updated、conflict 或 not_found 可交给 branch_value 分支处理。这与无条件修改所有符合筛选条件的行不同。详见设置、限制与示例及只确认一次申请的练习。
从 Mini App 读取
机器人的 Telegram Mini App 可按集合名、筛选条件和数量上限读取记录,向用户展示订单、历史或排行榜。
使用建议
- 字段使用简短的拉丁字母名称(
email、total、paid),方便在反应模板中使用。 - 用去重键防止重复动作创建多条记录;这称为幂等性。
- 给临时日志和不再需要的数据设置保存期限(
retention)。 - 值的结构不固定时可用
json类型。