pipefy-database-tables

数据库表

MCP 客户端：阅读 references/mcp.md。CLI 用户：阅读 references/cli.md。以下示例介绍通用操作参数。

Pipefy 数据库表中的表、记录（行）、架构列（表字段）和附件。

---

通用模式

• 对 CreateTableFieldInput / UpdateTableFieldInput 等输入使用 introspect_type。
• 分页：get_table_records 和 find_records 支持 first / after；默认页大小为 50。
• **已知字段值时，优先使用 find_records，而非对 get_table_records 分页。**调用一次并传入 field_id 和 field_value，比调用 N 页 get_table_records 更高效。

---

表操作

操作	只读	用途
get_tables	是	按 ID 加载数据库表。
search_tables	是	按名称搜索表。
get_table	是	获取表元数据和字段架构。
create_table	否	创建新的数据库表。
update_table	否	重命名或更改设置。
delete_table	否	具有破坏性；请先检查并批准。

---

表字段（架构列）操作

操作	用途
create_table_field	向表架构添加一列。
update_table_field	重命名，或更改列描述、必填状态或选项。
delete_table_field	**具有破坏性；请先检查并批准。**需要 table_id。

---

记录操作

操作	只读	用途
get_table_records	是	分页列出表中的所有记录。
find_records	是	按 field_id 和 field_value 筛选记录——优先于对 get_table_records 分页。
get_table_record	是	获取包含所有已填字段值的单条记录。
create_table_record	否	向表中添加一行。
update_table_record	否	更新行的 title、due_date 或 status_id。任何其他键都会被丢弃，且不会报错。
set_table_record_field_value	否	设置行的单个字段值。所有表字段都应使用此操作。
delete_table_record	否	具有破坏性；请先检查并批准。

---

步骤 — 查找并更新记录

1. 获取表 ID（如果尚未知晓）：

   操作：search_tables(table_name="Customers")，并从结果中选取表 ID。

2. 查找记录（使用 find_records，不要使用分页）：

   操作：find_records(table_id=456, field_id="email", field_value="[email protected]")

3. 更新单个字段（定向更新）：

   操作：set_table_record_field_value(record_id=789, field_id="status", value="Active")

   更新记录元数据（例如标题、到期日期或状态）：

   操作：update_table_record(record_id=789, fields={"title":"Updated title"})

---

检查破坏性更改

删除前，请展示受影响的数据并获得明确批准。按操作预览内容：

• delete_table — 展示表的名称和字段数量。get_table 不会返回记录数量；请通过经过架构验证的 GraphQL 获取，或在可行时分页遍历所有记录以获取数量。若数量未知，请明确说明。删除表会销毁所有行和架构。
• delete_table_record — 展示记录的标题和关键字段值，以便用户确认将被删除的行。
• delete_table_field — 展示字段的名称和类型；明确警告：该列的所有数据都将永久丢失。

务必先检查受影响的数据，再执行删除。

---

成功标准

• get_table_records 返回创建或更新后的记录，且字段值正确。
• 架构更改会立即反映在 get_table 中。

失败模式

• get_table_record / get_table_records 会省略空字段。 记录只返回已填充的字段，因此如果不调用 get_table 获取完整架构，就无法区分“字段未设置”和“字段不存在”。
• create_table_record 的标题会被静默覆盖。 如果表格的第一个字段是类似启动表单的标签列，Pipefy 会使用该字段的值作为记录的“标题”，忽略 title 参数。如果第一个字段会自动填充类似标签的列，请勿依赖 title。
• create_table_field 拒绝类型： 调用 introspect_type(type_name="CreateTableFieldInput") 查看有效的字段类型。
• update_table_record 忽略自定义字段且不报错： 它只发送 title、due_date 和 status_id，并丢弃所有其他键。仅当这三个键都不存在时才会失败。使用 set_table_record_field_value 设置每个自定义字段，然后使用 get_table_record 重新读取记录。
• find_records 返回空结果： 检查 field_id 是否与 get_table 返回的某个字段的ID（而非标签）匹配。
• 分页游标已过期： 从头重新获取；游标的有效期很短。

另请参阅

• pipefy-relations — 将表格连接到管道（以及表格关系 ID 命名空间的注意事项）。
• pipefy-introspection — 发现字段输入架构。