Feishu Bitable Query
Use scripts/feishu_bitable_query.py to query Bitable tables with server-side filtering. This avoids pulling all records into context and handles pagination automatically.
When to Use This Script vs the Built-in Tool
- - Use this script when: filter conditions are needed, data volume is large (>100 records), need specific output format (TSV/JSONL), or need to pipe results to other scripts
- Use the built-in tool (
feishu_bitable_list_records) when: simple reads, small tables, or no filter needed
Quick Reference
CODEBLOCK0
Key Options
| Option | Description |
|---|
| INLINECODE2 | 飞书 filter 表达式 (server-side) |
| INLINECODE3 |
Sort expression |
|
--fields | API 层面只返回指定字段 (JSON array) |
|
--view-id | 使用视图的筛选排序 |
|
--compact-fields | 输出时只显示指定字段，自动格式化 (JSON array) |
|
--format |
json (default),
jsonl,
tsv |
|
--all-pages | 自动翻页拉取全部 |
|
--count | 只输出匹配总数 |
|
--include-id | 输出中包含 record_id |
|
--time-filter | 本地时间过滤 (可多次), 格式见下方 |
|
--page-size | 每页条数 1-500, default 500 |
Filter 两种模式
模式 1: 公式语法 --filter（GET List API）
CODEBLOCK1
优点：Link 字段返回完整 text。缺点：日期字段不支持范围比较。
模式 2: JSON 结构体 --filter-json（POST Search API）
CODEBLOCK2
支持的 operator: is, isNot, contains, doesNotContain, isEmpty, isNotEmpty, isGreater, isLess, isGreaterEqual, INLINECODE27
日期字段 value 格式: ["ExactDate", "毫秒时间戳"], ["Today"], ["TheLastMonth"], ["TheNextWeek"] 等
优点：支持日期范围过滤（服务端）。缺点：DuplexLink 字段不返回 text（只返回 record_id）。
选择建议
- - 需要 Link 字段文本（如「所属任务」名称）→ 用
--filter + --time-filter（本地时间过滤） - 大量数据只需日期过滤（不关心 Link 文本）→ 用
--filter-json（服务端过滤更高效） - 两者结合：先用
--filter-json 做粗筛，再用 --time-filter 做精细过滤
Time Filter (本地时间过滤)
飞书 API 不支持对时间戳字段做范围比较，--time-filter 在本地过滤（拉取后过滤）。
格式：字段名:规则，可多次使用。
CODEBLOCK3
Field Auto-Formatting
INLINECODE39 自动处理常见字段类型：
- - User 字段:
[{name: "张三"}] → INLINECODE41 - 时间戳字段 (更新/创建时间/开始时间/结束时间):
1770574521000 → INLINECODE43 - MultiSelect:
["opt1", "opt2"] → INLINECODE45 - Link 字段:
[{text: "xxx"}] → INLINECODE47
Piping Pattern
CODEBLOCK4
Auth
Script reads credentials from ~/.openclaw/openclaw.json → channels.feishu.appId/appSecret automatically. No manual token needed.
Stderr vs Stdout
- - stderr: pagination progress (
Page 1: 500 records...) - stdout: query results only
Always use 2>/dev/null when piping to suppress progress output.
Feishu Bitable 查询
使用 scripts/feishubitablequery.py 通过服务端过滤查询 Bitable 表格。这避免了将所有记录拉取到上下文中，并自动处理分页。
何时使用此脚本与内置工具
- - 使用此脚本：当需要过滤条件、数据量大（>100条记录）、需要特定输出格式（TSV/JSONL）或需要将结果传递给其他脚本时
- 使用内置工具（feishubitablelist_records）：当进行简单读取、表格较小或不需要过滤时
快速参考
bash
SCRIPT=scripts/feishubitablequery.py
统计匹配过滤条件的记录数
python3 $SCRIPT --app-token APP --table-id TBL --filter EXPR --count
带过滤条件查询，紧凑输出
python3 $SCRIPT --app-token APP --table-id TBL \
--filter EXPR \
--compact-fields [字段1,字段2] \
--all-pages 2>/dev/null
使用视图查询（使用视图内置的过滤/排序）
python3 $SCRIPT --app-token APP --table-id TBL --view-id VIEW --all-pages
TSV 输出便于阅读
python3 $SCRIPT --app-token APP --table-id TBL \
--compact-fields [描述,状态] --format tsv --all-pages 2>/dev/null
JSONL 格式用于传递给其他工具
python3 $SCRIPT --app-token APP --table-id TBL --format jsonl --all-pages 2>/dev/null
关键选项
| 选项 | 描述 |
|---|
| --filter | 飞书过滤表达式（服务端） |
| --sort |
排序表达式 |
| --fields | API 层面只返回指定字段（JSON 数组） |
| --view-id | 使用视图的筛选排序 |
| --compact-fields | 输出时只显示指定字段，自动格式化（JSON 数组） |
| --format | json（默认）、jsonl、tsv |
| --all-pages | 自动翻页拉取全部 |
| --count | 只输出匹配总数 |
| --include-id | 输出中包含 record_id |
| --time-filter | 本地时间过滤（可多次使用），格式见下方 |
| --page-size | 每页条数 1-500，默认 500 |
过滤两种模式
模式 1：公式语法 --filter（GET List API）
CurrentValue.[字段名]=值
AND(CurrentValue.[字段名]=值, CurrentValue.[字段2]=值2)
CurrentValue.[Owner].contains(张三)
优点：Link 字段返回完整文本。缺点：日期字段不支持范围比较。
模式 2：JSON 结构体 --filter-json（POST Search API）
bash
--filter-json {
conjunction: and,
conditions: [
{fieldname: 进度 Owner, operator: contains, value: [ouxxx]},
{field_name: 结束时间, operator: isGreater, value: [ExactDate, 1770000000000]}
]
}
支持的运算符：is、isNot、contains、doesNotContain、isEmpty、isNotEmpty、isGreater、isLess、isGreaterEqual、isLessEqual
日期字段值格式：[ExactDate, 毫秒时间戳]、[Today]、[TheLastMonth]、[TheNextWeek] 等
优点：支持日期范围过滤（服务端）。缺点：DuplexLink 字段不返回文本（只返回 record_id）。
选择建议
- - 需要 Link 字段文本（如「所属任务」名称）→ 使用 --filter + --time-filter（本地时间过滤）
- 大量数据只需日期过滤（不关心 Link 文本）→ 使用 --filter-json（服务端过滤更高效）
- 两者结合：先用 --filter-json 做粗筛，再用 --time-filter 做精细过滤
时间过滤（本地时间过滤）
飞书 API 不支持对时间戳字段做范围比较，--time-filter 在本地过滤（拉取后过滤）。
格式：字段名:规则，可多次使用。
bash
前后 N 天
--time-filter 结束时间:14d
未来 N 天
--time-filter 结束时间:14d+
过去 N 天
--time-filter 更新:30d-
晚于/早于指定日期
--time-filter 结束时间:>2026-02-16
--time-filter 结束时间:<2026-03-16
日期范围
--time-filter 结束时间:2026-02-16~2026-03-16
组合多个时间过滤
--time-filter 结束时间:14d --time-filter 更新:30d-
字段自动格式化
--compact-fields 自动处理常见字段类型：
- - 用户字段：[{name: 张三}] → 张三
- 时间戳字段（更新/创建时间/开始时间/结束时间）：1770574521000 → 2026-02-09
- 多选字段：[opt1, opt2] → opt1, opt2
- 链接字段：[{text: xxx}] → xxx
管道模式
bash
查询 → 本地过滤 → 格式化
python3 $SCRIPT --app-token APP --table-id TBL \
--filter CurrentValue.[Owner].contains(张三) \
--compact-fields [描述,状态,更新] \
--format jsonl --all-pages 2>/dev/null \
| python3 -c
import json,sys
for line in sys.stdin:
r = json.loads(line)
if r.get(状态) == 执行中:
print(f - {r[\描述\]} ({r[\更新\]}))
认证
脚本从 ~/.openclaw/openclaw.json → channels.feishu.appId/appSecret 自动读取凭据。无需手动提供令牌。
标准错误输出 vs 标准输出
- - 标准错误输出：分页进度（Page 1: 500 records...）
- 标准输出：仅查询结果
使用管道时始终添加 2>/dev/null 以抑制进度输出。
