feishu-bitable

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feishu Bitable (多维表格) SKILL

Feishu Bitable SKILL

🚨 执行前必读

🚨 Pre-execution Notes

✅ 创建数据表：支持两种模式 — ① 明确需求时，在
```
create
```
时通过
```
table.fields
```
一次性定义字段（减少 API 调用）；② 探索式场景时，使用默认表 + 逐步修改字段（更稳定，易调整）
⚠️ 默认表的空行坑：
```
app.create
```
自带的默认表中会有空记录（空行）！插入数据前建议先调用
```
feishu_bitable_app_table_record.list
```
+
```
batch_delete
```
删除空行，避免数据污染
✅ 写记录前：先调用
```
feishu_bitable_app_table_field.list
```
获取字段 type/ui_type
✅ 人员字段：默认 open_id（ou_...），值必须是
```
[{id:"ou_xxx"}]
```
（数组对象）
✅ 日期字段：毫秒时间戳（例如
```
1674206443000
```
），不是秒
✅ 单选字段：字符串（例如
```
"选项1"
```
），不是数组
✅ 多选字段：字符串数组（例如
```
["选项1", "选项2"]
```
）
✅ 附件字段：必须先上传到当前多维表格，使用返回的 file_token
✅ 批量上限：单次 ≤ 500 条，超过需分批（批量操作是原子性的）
✅ 并发限制：同一数据表不支持并发写，需串行调用 + 延迟 0.5-1 秒

✅ Create Data Table: Supports two modes — ① When requirements are clear, define all fields at once via
```
table.fields
```
during
```
create
```
(reduces API calls); ② For exploratory scenarios, use the default table + modify fields gradually (more stable and adjustable)
⚠️ Empty Rows in Default Table: The default table created by
```
app.create
```
contains empty records (empty rows)! It is recommended to call
```
feishu_bitable_app_table_record.list
```
+
```
batch_delete
```
to remove empty rows before inserting data to avoid data contamination
✅ Before Writing Records: First call
```
feishu_bitable_app_table_field.list
```
to get field type/ui_type
✅ User Field: Defaults to open_id (ou_...), value must be
```
[{id:"ou_xxx"}]
```
(array of objects)
✅ Date Field: Millisecond timestamp (e.g.,
```
1674206443000
```
), not seconds
✅ Single Select Field: String (e.g.,
```
"Option 1"
```
), not an array
✅ Multi Select Field: Array of strings (e.g.,
```
["Option 1", "Option 2"]
```
)
✅ Attachment Field: Must first upload to the current Bitable, use the returned file_token
✅ Batch Limit: ≤500 records per call, split into batches if exceeding (batch operations are atomic)
✅ Concurrency Limit: Concurrent writes are not supported for the same data table, use serial calls + 0.5-1 second delay

📋 快速索引：意图 → 工具 → 必填参数

📋 Quick Index: Intent → Tool → Required Parameters

用户意图	工具	action	必填参数	常用可选
查表有哪些字段	feishu_bitable_app_table_field	list	app_token, table_id	-
查记录	feishu_bitable_app_table_record	list	app_token, table_id	filter, sort, field_names
新增一行	feishu_bitable_app_table_record	create	app_token, table_id, fields	-
批量导入	feishu_bitable_app_table_record	batch_create	app_token, table_id, records (≤500)	-
更新一行	feishu_bitable_app_table_record	update	app_token, table_id, record_id, fields	-
批量更新	feishu_bitable_app_table_record	batch_update	app_token, table_id, records (≤500)	-
创建多维表格	feishu_bitable_app	create	name	folder_token
创建数据表	feishu_bitable_app_table	create	app_token, name	fields
创建字段	feishu_bitable_app_table_field	create	app_token, table_id, field_name, type	property
创建视图	feishu_bitable_app_table_view	create	app_token, table_id, view_name, view_type	-

User Intent	Tool	action	Required Parameters	Common Optional
Check table fields	feishu_bitable_app_table_field	list	app_token, table_id	-
Query records	feishu_bitable_app_table_record	list	app_token, table_id	filter, sort, field_names
Add a row	feishu_bitable_app_table_record	create	app_token, table_id, fields	-
Batch import	feishu_bitable_app_table_record	batch_create	app_token, table_id, records (≤500)	-
Update a row	feishu_bitable_app_table_record	update	app_token, table_id, record_id, fields	-
Batch update	feishu_bitable_app_table_record	batch_update	app_token, table_id, records (≤500)	-
Create Bitable	feishu_bitable_app	create	name	folder_token
Create data table	feishu_bitable_app_table	create	app_token, name	fields
Create field	feishu_bitable_app_table_field	create	app_token, table_id, field_name, type	property
Create view	feishu_bitable_app_table_view	create	app_token, table_id, view_name, view_type	-

🎯 核心约束（Schema 未透露的知识）

🎯 Core Constraints (Undisclosed Schema Knowledge)

📚 详细参考文档

📚 Detailed Reference Documents

当遇到字段配置、记录值格式问题或需要完整示例时，查阅以下文档：

字段 Property 配置详解 - 每种字段类型创建/更新时需要的
```
property
```
参数结构（单选的 options、进度的 min/max、关联的 table_id 等）
记录值数据结构详解 - 每种字段类型在记录中对应的
```
fields
```
值格式（人员字段只传 id、日期是毫秒时间戳、附件需先上传等）
使用场景完整示例 - 8 个完整场景示例（创建表模式对比、批量导入、筛选查询、附件处理、关联字段等）

何时查阅:

创建/更新字段时收到
```
125408X
```
错误码（property 结构错误）→ 查 field-properties.md
写入记录时收到
```
125406X
```
错误码（字段值转换失败）→ 查 record-values.md
需要完整的操作流程和参数示例 → 查 examples.md

When encountering field configuration, record value format issues or needing complete examples, refer to the following documents:

Field Property Configuration Details -
```
property
```
parameter structure required for creating/updating each field type (options for single select, min/max for progress, associated table_id, etc.)
Record Value Data Structure Details -
```
fields
```
value format corresponding to each field type in records (only pass id for user fields, date is millisecond timestamp, attachments need pre-upload, etc.)
Complete Usage Scenario Examples - 8 complete scenario examples (comparison of table creation modes, batch import, filtered query, attachment processing, associated fields, etc.)

When to Refer:

Received error code
```
125408X
```
when creating/updating fields (incorrect property structure) → Check field-properties.md
Received error code
```
125406X
```
when writing records (field value conversion failed) → Check record-values.md
Need complete operation flows and parameter examples → Check examples.md

1. 字段类型与值格式必须严格匹配

1. Field Type and Value Format Must Strictly Match

Bitable 最大的坑：不同字段类型对 value 的数据结构要求完全不同。

Bitable's Biggest Pitfall: Different field types have completely different requirements for value data structures.

最易错的字段类型（完整列表见 record-values.md）

Most Error-Prone Field Types (Full list in record-values.md)

type	ui_type	字段类型	正确格式	❌ 常见错误
11	User	人员	`[{id: "ou_xxx"}]`	传字符串 `"ou_xxx"` 或 `[{name: "张三"}]`
5	DateTime	日期	`1674206443000` （毫秒）	传秒时间戳或字符串
3	SingleSelect	单选	`"选项名"`	传数组 `["选项名"]`
4	MultiSelect	多选	`["选项1", "选项2"]`	传字符串 `"选项1"`
15	Url	超链接	`{link: "...", text: "..."}`	只传字符串 URL
17	Attachment	附件	`[{file_token: "..."}]`	传外部 URL 或本地路径

强制流程：

先调用

feishu_bitable_app_table_field.list

获取字段的

type

和

ui_type

根据上表或 record-values.md 构造正确格式
错误码
```
125406X
```
或
```
1254015
```
→ 检查字段值格式

人员字段特别注意：

默认使用 open_id（ou_...），与 calendar/task 一致
格式：
```
[{id: "ou_xxx"}]
```
（数组对象）
只能传 id 字段，不能传 name/email 等

type	ui_type	Field Type	Correct Format	❌ Common Mistakes
11	User	User	`[{id: "ou_xxx"}]`	Pass string `"ou_xxx"` or `[{name: "Zhang San"}]`
5	DateTime	Date	`1674206443000` (milliseconds)	Pass second-level timestamp or string
3	SingleSelect	Single Select	`"Option Name"`	Pass array `["Option Name"]`
4	MultiSelect	Multi Select	`["Option 1", "Option 2"]`	Pass string `"Option 1"`
15	Url	Hyperlink	`{link: "...", text: "..."}`	Pass only string URL
17	Attachment	Attachment	`[{file_token: "..."}]`	Pass external URL or local path

Mandatory Process:

First call

feishu_bitable_app_table_field.list

to get field

type

and

ui_type

Construct the correct format based on the above table or record-values.md
Error code
```
125406X
```
or
```
1254015
```
→ Check field value format

Special Note for User Field:

Defaults to open_id (ou_...), consistent with calendar/task
Format:
```
[{id: "ou_xxx"}]
```
(array of objects)
Only pass the id field, do not pass name/email, etc.

📌 核心使用场景

📌 Core Usage Scenarios

完整示例: 查阅 examples.md 了解更多场景（创建表模式对比、空行处理、附件上传、关联字段等）

Complete Examples: Check examples.md for more scenarios (comparison of table creation modes, empty row processing, attachment upload, associated fields, etc.)

场景 1: 查字段类型（必做第一步）

Scenario 1: Query Field Types (Mandatory First Step)

json

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl..."
}

返回：包含每个字段的

field_id

、

field_name

、

type

、

ui_type

、

property

json

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl..."
}

Return: Includes

field_id

field_name

type

ui_type

property

for each field

场景 2: 批量导入客户数据

Scenario 2: Batch Import Customer Data

json

{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "records": [
    {
      "fields": {
        "客户名称": "Bytedance",
        "负责人": [{"id": "ou_xxx"}],
        "签约日期": 1674206443000,
        "状态": "进行中"
      }
    },
    {
      "fields": {
        "客户名称": "飞书",
        "负责人": [{"id": "ou_yyy"}],
        "签约日期": 1675416243000,
        "状态": "已完成"
      }
    }
  ]
}

字段值格式：

人员：
```
[{id: "ou_xxx"}]
```
（数组对象）
日期：毫秒时间戳
单选：字符串
多选：字符串数组

限制: 最多 500 条记录

json

{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "records": [
    {
      "fields": {
        "Customer Name": "Bytedance",
        "Responsible Person": [{"id": "ou_xxx"}],
        "Signing Date": 1674206443000,
        "Status": "In Progress"
      }
    },
    {
      "fields": {
        "Customer Name": "Feishu",
        "Responsible Person": [{"id": "ou_yyy"}],
        "Signing Date": 1675416243000,
        "Status": "Completed"
      }
    }
  ]
}

Field Value Format:

User:
```
[{id: "ou_xxx"}]
```
(array of objects)
Date: Millisecond timestamp
Single Select: String
Multi Select: Array of strings

Limit: Maximum 500 records

场景 3: 筛选查询（高级筛选）

Scenario 3: Filtered Query (Advanced Filter)

json

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "filter": {
    "conjunction": "and",
    "conditions": [
      {
        "field_name": "状态",
        "operator": "is",
        "value": ["进行中"]
      },
      {
        "field_name": "截止日期",
        "operator": "isLess",
        "value": ["ExactDate", "1740441600000"]
      }
    ]
  },
  "sort": [
    {
      "field_name": "截止日期",
      "desc": false
    }
  ]
}

filter 说明：

支持 10 种 operator（is/isNot/contains/isEmpty 等，见附录 C）
⚠️ isEmpty/isNotEmpty 必须传
value: []
（虽然逻辑上不需要值，但 API 要求必须传空数组）
日期筛选可使用
```
["Today"]
```
、
```
["ExactDate", "时间戳"]
```
等
```
sort
```
可指定多个排序字段

json

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "filter": {
    "conjunction": "and",
    "conditions": [
      {
        "field_name": "Status",
        "operator": "is",
        "value": ["In Progress"]
      },
      {
        "field_name": "Deadline",
        "operator": "isLess",
        "value": ["ExactDate", "1740441600000"]
      }
    ]
  },
  "sort": [
    {
      "field_name": "Deadline",
      "desc": false
    }
  ]
}

filter Description:

Supports 10 operators (is/isNot/contains/isEmpty, etc., see Appendix C)
⚠️ isEmpty/isNotEmpty must pass
value: []
(logically no value is needed, but API requires empty array)
Date filtering can use
```
["Today"]
```
,
```
["ExactDate", "timestamp"]
```
, etc.
```
sort
```
can specify multiple sorting fields

🔍 常见错误与排查

🔍 Common Errors and Troubleshooting

错误码	错误现象	根本原因	解决方案
1254064	DatetimeFieldConvFail	日期字段格式错误	必须用毫秒时间戳（如 `1772121600000` ），不能用字符串（ `"2026-02-27"` 、RFC3339）或秒级时间戳
1254068	URLFieldConvFail	超链接字段格式错误	必须用对象 `{text: "显示文本", link: "URL"}` ，不能直接传字符串 URL
1254066	UserFieldConvFail	人员字段格式错误或 ID 类型不匹配	必须传 `[{id: "ou_xxx"}]` ，确认 `user_id_type`
1254015	Field types do not match	字段值格式与类型不匹配	先 list 字段，按类型构造正确格式
1254104	RecordAddOnceExceedLimit	批量创建超过 500 条	分批调用，每批 ≤ 500
1254291	Write conflict	并发写冲突	串行调用 + 延迟 0.5-1 秒
1254303	AttachPermNotAllow	附件未上传到当前表格	先调用上传素材接口
1254045	FieldNameNotFound	字段名不存在	检查字段名（包括空格、大小写）

Error Code	Symptom	Root Cause	Solution
1254064	DatetimeFieldConvFail	Incorrect date field format	Must use millisecond timestamp (e.g., `1772121600000` ), do not use string ("2026-02-27", RFC3339) or second-level timestamp
1254068	URLFieldConvFail	Incorrect hyperlink field format	Must use object `{text: "Display Text", link: "URL"}` , do not pass string URL directly
1254066	UserFieldConvFail	Incorrect user field format or mismatched ID type	Must pass `[{id: "ou_xxx"}]` , confirm `user_id_type`
1254015	Field types do not match	Field value format does not match type	First list fields, then construct correct format by type
1254104	RecordAddOnceExceedLimit	Batch creation exceeds 500 records	Call in batches, ≤500 records per batch
1254291	Write conflict	Concurrent write conflict	Use serial calls + 0.5-1 second delay
1254303	AttachPermNotAllow	Attachment not uploaded to current table	First call the material upload interface
1254045	FieldNameNotFound	Field name does not exist	Check field name (including spaces, case sensitivity)

📚 附录：背景知识

📚 Appendix: Background Knowledge

A. 资源层级关系

A. Resource Hierarchy

App (多维表格应用)
 ├── Table (数据表) ×100
 │    ├── Record (记录/行) ×20,000
 │    ├── Field (字段/列) ×300
 │    └── View (视图) ×200
 └── Dashboard (仪表盘)

App (Bitable App)
 ├── Table (Data Table) ×100
 │    ├── Record (Row) ×20,000
 │    ├── Field (Column) ×300
 │    └── View ×200
 └── Dashboard

B. 筛选条件 operator 列表

B. Filter Operator List

operator	含义	支持字段	value 要求
`is`	等于	所有	单个值
`isNot`	不等于	除日期外	单个值
`contains`	包含	除日期外	可多个值
`doesNotContain`	不包含	除日期外	可多个值
`isEmpty`	为空	所有	必须为 `[]`
`isNotEmpty`	不为空	所有	必须为 `[]`
`isGreater`	大于	数字、日期	单个值
`isGreaterEqual`	大于等于	数字（不支持日期）	单个值
`isLess`	小于	数字、日期	单个值
`isLessEqual`	小于等于	数字（不支持日期）	单个值

日期字段特殊值:

["Today"]

["Tomorrow"]

["ExactDate", "时间戳"]

等（完整列表见 examples.md）

operator	Meaning	Supported Fields	Value Requirement
`is`	Equals	All	Single value
`isNot`	Not Equals	All except date	Single value
`contains`	Contains	All except date	Multiple values allowed
`doesNotContain`	Does Not Contain	All except date	Multiple values allowed
`isEmpty`	Is Empty	All	Must be `[]`
`isNotEmpty`	Is Not Empty	All	Must be `[]`
`isGreater`	Greater Than	Number, Date	Single value
`isGreaterEqual`	Greater Than or Equal	Number (not supported for date)	Single value
`isLess`	Less Than	Number, Date	Single value
`isLessEqual`	Less Than or Equal	Number (not supported for date)	Single value

Special Values for Date Field:

["Today"]

["Tomorrow"]

["ExactDate", "timestamp"]

, etc. (full list in examples.md)

C. 使用限制

C. Usage Limits

限制项	上限
数据表 + 仪表盘	100（单个 App）
记录数	20,000（单个数据表）
字段数	300（单个数据表）
视图数	200（单个数据表）
批量创建/更新/删除	500（单次 API 调用）
单元格文本	10 万字符
单选/多选选项	20,000（单个字段）
单元格附件	100
单元格人员	1,000

Limit Item	Upper Limit
Data Tables + Dashboards	100 (per App)
Number of Records	20,000 (per Data Table)
Number of Fields	300 (per Data Table)
Number of Views	200 (per Data Table)
Batch Create/Update/Delete	500 (per API call)
Cell Text	100,000 characters
Single Select/Multi Select Options	20,000 (per field)
Cell Attachments	100
Cell Users	1,000

D. 其他约束

D. Other Constraints

从其他数据源同步的数据表，不支持增删改记录
公式字段、查看引用字段是只读的
删除操作无法恢复
视图筛选条件使用
```
field_id
```
，需先调用 field.list 获取

Data tables synchronized from other data sources do not support adding/deleting/modifying records
Formula fields, view reference fields are read-only
Delete operations cannot be recovered
View filter conditions use
```
field_id
```
, need to call field.list first to get it