pipefy-database-tables

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Database Tables

数据库表

Tables, records (rows), schema columns (table fields), and attachments for Pipefy Database Tables. 17 MCP tools.

Pipefy数据库表的表、记录（行）、架构列（表字段）和附件。17种MCP工具。

Cross-cutting patterns

通用模式

Same conventions as pipe building:

introspect_type

on inputs such as

CreateTableFieldInput

UpdateTableFieldInput

debug=true

on mutations.

Pagination:
```
get_table_records
```
and
```
find_records
```
support
```
first
```
/
```
after
```
. With the unified MCP envelope, read top-level
```
pagination.has_more
```
and
```
pagination.end_cursor
```
(and
```
pagination.page_size
```
) and pass
```
after=end_cursor
```
for the next page (default page size is 50).
find_records
over paginated
get_table_records
when you know the field value. One
```
find_records
```
call with a
```
column_id
```
/
```
search_value
```
filter beats N pages of
```
get_table_records
```
.
Legacy mutation envelope. Several table mutation tools still return the GraphQL operation name as a nested key under
```
result
```
(for example
```
result.createTableRecord
```
). Read the payload inside that key; shape may differ from tools that already use the unified envelope.

与管道构建遵循相同约定：
```
CreateTableFieldInput
```
/
```
UpdateTableFieldInput
```
等输入参数中包含
```
introspect_type
```
，变更操作中包含
```
debug=true
```
。
分页：
```
get_table_records
```
和
```
find_records
```
支持
```
first
```
/
```
after
```
参数。通过统一的MCP响应结构，读取顶层的
```
pagination.has_more
```
、
```
pagination.end_cursor
```
（以及
```
pagination.page_size
```
），并在下一页请求中传入
```
after=end_cursor
```
（默认每页大小为50）。
当已知字段值时，优先使用
find_records
而非分页的
get_table_records
：一次带有
```
column_id
```
/
```
search_value
```
过滤条件的
```
find_records
```
调用，优于N页的
```
get_table_records
```
请求。
旧版变更响应结构： 部分表变更工具仍会在
```
result
```
下以嵌套键的形式返回GraphQL操作名称（例如
```
result.createTableRecord
```
）。需读取该键内的负载数据；其结构可能与已使用统一响应结构的工具不同。

Table operations

表操作

Tool (MCP)	CLI	Read-only	Purpose
`get_tables`	`pipefy table list`	Yes	List database tables by org.
`search_tables`	`pipefy table list --search`	Yes	Search tables by name.
`get_table`	`pipefy table get <id>`	Yes	Table metadata and field schema.
`create_table`	`pipefy table create`	No	Create a new database table.
`update_table`	`pipefy table update <id>`	No	Rename or change settings.
`delete_table`	`pipefy table delete <id>`	No	Two-step destructive.

工具（MCP）	CLI命令	只读	用途
`get_tables`	`pipefy table list`	是	按组织列出数据库表。
`search_tables`	`pipefy table list --search`	是	按名称搜索表。
`get_table`	`pipefy table get <id>`	是	获取表元数据和字段架构。
`create_table`	`pipefy table create`	否	创建新的数据库表。
`update_table`	`pipefy table update <id>`	否	重命名或修改设置。
`delete_table`	`pipefy table delete <id>`	否	两步式破坏性操作。

Table field (schema column) operations

表字段（架构列）操作

Tool (MCP) CLI Purpose

Tool (MCP)	CLI	Purpose
`create_table_field`	`pipefy table field create <table_id> --label <name> --type <type>`	Add a column to a table schema.
`update_table_field`	`pipefy table field update <field_id> --table <table_id> --label <name>`	Rename or change column settings ( `--description` , `--required` , `--options` ).
`delete_table_field`	`pipefy table field delete <field_id> --table <table_id>`	Two-step destructive. Requires `table_id` .

create_table_field

pipefy table field create <table_id> --label <name> --type <type>

Add a column to a table schema.

update_table_field

pipefy table field update <field_id> --table <table_id> --label <name>

Rename or change column settings (

--description

--required

--options

delete_table_field

pipefy table field delete <field_id> --table <table_id>

Two-step destructive. Requires

table_id

工具（MCP） CLI命令用途

工具（MCP）	CLI命令	用途
`create_table_field`	`pipefy table field create <table_id> --label <name> --type <type>`	向表架构中添加一列。
`update_table_field`	`pipefy table field update <field_id> --table <table_id> --label <name>`	重命名或修改列设置（ `--description` 、 `--required` 、 `--options` ）。
`delete_table_field`	`pipefy table field delete <field_id> --table <table_id>`	两步式破坏性操作。需要传入 `table_id` 。

create_table_field

pipefy table field create <table_id> --label <name> --type <type>

向表架构中添加一列。

update_table_field

pipefy table field update <field_id> --table <table_id> --label <name>

重命名或修改列设置（

--description

、

--required

、

--options

）。

delete_table_field

pipefy table field delete <field_id> --table <table_id>

两步式破坏性操作。 需要传入

table_id

。

Record operations

记录操作

Tool (MCP)	CLI	Read-only	Purpose
`get_table_records`	`pipefy record find --table <id>`	Yes	Paginated list of all records in a table.
`find_records`	`pipefy record find --filter`	Yes	Filter records by field value (JSON filter) — preferred over paginating `get_table_records` .
`get_table_record`	`pipefy record get <id>`	Yes	Single record with all populated field values.
`create_table_record`	`pipefy record create`	No	Add a row to a table.
`update_table_record`	`pipefy record update <id> --fields ...`	No	Update one or more field values on a row.
`set_table_record_field_value`	`pipefy record update <id> --field-id <slug> --value <json>`	No	More targeted single-field update than `update_table_record` .
`delete_table_record`	`pipefy record delete <id>`	No	Two-step destructive.

工具（MCP）	CLI命令	只读	用途
`get_table_records`	`pipefy record find --table <id>`	是	分页列出表中的所有记录。
`find_records`	`pipefy record find --filter`	是	按字段值过滤记录（JSON过滤器）——优先于分页的 `get_table_records` 。
`get_table_record`	`pipefy record get <id>`	是	获取包含所有已填充字段值的单条记录。
`create_table_record`	`pipefy record create`	否	向表中添加一行。
`update_table_record`	`pipefy record update <id> --fields ...`	否	更新一行中的一个或多个字段值。
`set_table_record_field_value`	`pipefy record update <id> --field-id <slug> --value <json>`	否	相比 `update_table_record` ，更精准的单字段更新操作。
`delete_table_record`	`pipefy record delete <id>`	否	两步式破坏性操作。

Attachment uploads

附件上传

Tool (MCP)	CLI	Purpose
`upload_attachment_to_table_record`	`pipefy attachment upload --record <id> --field <slug> --file <path> --organization <id>`	Attach a file to a table record. Exactly one source: `file_path` (local; local profile only) or `file_url` (downloaded, SSRF-guarded; any profile — required on the hosted server). CLI is `--file` only. See `pipefy-attachments` .

工具（MCP）	CLI命令	用途
`upload_attachment_to_table_record`	`pipefy attachment upload --record <id> --field <slug> --file <path> --organization <id>`	向表记录附加文件。仅支持一种来源： `file_path` （本地文件；仅本地配置可用）或 `file_url` （下载文件，受SSRF防护；任何配置——托管服务器上必须使用此方式）。CLI仅支持 `--file` 参数。详见 `pipefy-attachments` 。

Steps — find and update a record

步骤——查找并更新记录

Get table ID (if not known):

MCP:

get_tables organization_id=123

CLI:

pipefy table list

Find the record (use

find_records

, not pagination):

MCP:

find_records table_id=456 filter='{"column_id":"email","search_value":"user@example.com"}'

CLI:

pipefy record find --table 456 --filter '{"column_id":"email","search_value":"user@example.com"}'

Update one field (targeted):

MCP:

set_table_record_field_value record_id=789 field_id="status" value="Active"

CLI:

pipefy record update 789 --field-id status --value '"Active"'

Update multiple fields:

MCP:

update_table_record record_id=789 node_fields='[{"field_id":"status","field_value":"Active"}]'

CLI:

pipefy record update 789 --fields '{"status":"Active"}'

获取表ID（若未知）：
MCP命令：
```
get_tables organization_id=123
```
CLI命令：
```
pipefy table list
```

查找记录（使用

find_records

，而非分页）：

MCP命令：

find_records table_id=456 filter='{"column_id":"email","search_value":"user@example.com"}'

CLI命令：

pipefy record find --table 456 --filter '{"column_id":"email","search_value":"user@example.com"}'

更新单个字段（精准更新）：

MCP命令：

set_table_record_field_value record_id=789 field_id="status" value="Active"

CLI命令：

pipefy record update 789 --field-id status --value '"Active"'

更新多个字段：

MCP命令：

update_table_record record_id=789 node_fields='[{"field_id":"status","field_value":"Active"}]'

CLI命令：

pipefy record update 789 --fields '{"status":"Active"}'

Two-step destructive previews

两步式破坏性操作预览

Always call without

confirm=true

first, surface the preview to the user, then call again with

confirm=true

after explicit approval. Preview content per tool:

delete_table
— show table name, field count, and record count. Deleting a table destroys all rows and schema.
delete_table_record
— show record title and key field values so the user can identify which row will vanish.
delete_table_field
— show field name and type; warn explicitly that all column data will be permanently lost.

Never delete in a single call.

始终先不带

confirm=true

调用，向用户展示预览内容，在获得明确批准后再带

confirm=true

调用。各工具的预览内容：

delete_table
—— 展示表的名称、字段数量和记录数量。删除表会销毁所有行和架构。
delete_table_record
—— 展示记录的标题和关键字段值，以便用户确认要删除的行。
delete_table_field
—— 展示字段的名称和类型；需明确警告该列的所有数据将永久丢失。

禁止单次调用直接执行删除操作。

Success criteria

成功标准

```
get_table_records
```
returns the created/updated records with correct field values.
Schema changes reflect immediately in
```
get_table
```
.

```
get_table_records
```
返回包含正确字段值的已创建/更新记录。
架构变更会立即在
```
get_table
```
的结果中体现。

Failure modes

失败场景

get_table_record
/
get_table_records
omit empty fields. Records only return populated fields, so you cannot tell "field unset" from "field doesn't exist" without calling
```
get_table
```
for the full schema.
create_table_record
title silently overridden. When the first table field is a start-form-style label column, Pipefy uses that field's value as the record
```
title
```
, ignoring the
```
title
```
parameter. Don't rely on
```
title
```
if the first field auto-populates a label-like column.

create_table_field
rejects type: call

introspect_type type_name="CreateTableFieldInput"

for valid field types.

find_records
returns empty: check that
```
column_id
```
matches a field's ID (not label) from
```
get_table
```
.
Pagination cursor expired: re-fetch from the beginning; cursors are short-lived.

get_table_record
/
get_table_records
会省略空字段：记录仅返回已填充的字段，因此若不调用
```
get_table
```
获取完整架构，无法区分“字段未设置”和“字段不存在”。
create_table_record
的title会被静默覆盖：当表的第一个字段是起始表单样式的标签列时，Pipefy会使用该字段的值作为记录的
```
title
```
，忽略传入的
```
title
```
参数。若第一个字段会自动填充类似标签的列，则不要依赖
```
title
```
参数。

create_table_field
拒绝类型：调用

introspect_type type_name="CreateTableFieldInput"

获取有效的字段类型。

find_records
返回空结果：检查
```
column_id
```
是否与
```
get_table
```
返回的字段ID（而非标签）匹配。
分页游标过期：从头重新获取数据；游标有效期较短。

另请参阅

skills/relations/pipefy-relations/SKILL.md — connect tables to pipes (and the table-relation ID namespace gotcha).
skills/introspection/pipefy-introspection/SKILL.md — discover field input schemas.

skills/relations/pipefy-relations/SKILL.md —— 将表与管道关联（以及表关系ID命名空间的注意事项）。
skills/introspection/pipefy-introspection/SKILL.md —— 发现字段输入架构。

pipefy-database-tables

Original

Translation

Database Tables

数据库表

Cross-cutting patterns

通用模式

Table operations

表操作

Table field (schema column) operations

表字段（架构列）操作

Record operations

记录操作

Attachment uploads

附件上传

Steps — find and update a record

步骤——查找并更新记录

Two-step destructive previews

两步式破坏性操作预览

Success criteria

成功标准

Failure modes

失败场景

See also

另请参阅