Feishu Bitable Query — Feishu Bitable 查询

Feishu Bitable 查询

Use scripts/feishu_bitable_查询.py to 查询 Bitable tables with server-side 过滤器ing. This avoids pulling all records into 上下文 and handles pagination automatically.

When to Use This Script vs the Built-in 工具 Use this script when: 过滤器 conditions are needed, data volume is large (>100 records), need specific 输出 格式化 (TSV/JSONL), or need to pipe 结果s to other scripts Use the built-in 工具 (feishu_bitable_列出_records) when: simple reads, small tables, or no 过滤器 needed Quick Reference SCRIPT="scripts/feishu_bitable_查询.py"

# Count records matching a 过滤器 python3 $SCRIPT --应用-令牌 应用 --table-id TBL --过滤器 'EXPR' --count

# 查询 with 过滤器, compact 输出 python3 $SCRIPT --应用-令牌 应用 --table-id TBL \ --过滤器 'EXPR' \ --compact-fields '["字段1","字段2"]' \ --all-pages 2>/dev/null

# 查询 with view (uses view's built-in 过滤器/排序) python3 $SCRIPT --应用-令牌 应用 --table-id TBL --view-id VIEW --all-pages

# TSV 输出 for readability python3 $SCRIPT --应用-令牌 应用 --table-id TBL \ --compact-fields '["描述","状态"]' --格式化 tsv --all-pages 2>/dev/null

# JSONL for piping to other 工具s python3 $SCRIPT --应用-令牌 应用 --table-id TBL --格式化 jsonl --all-pages 2>/dev/null

Key Options Option Description --过滤器 飞书 过滤器 表达式 (server-side) --排序 排序 expression --fields API 层面只返回指定字段 (JSON array) --view-id 使用视图的筛选排序 --compact-fields 输出时只显示指定字段，自动格式化 (JSON array) --格式化 json (default), jsonl, tsv --all-pages 自动翻页拉取全部 --count 只输出匹配总数 --include-id 输出中包含 record_id --time-过滤器 本地时间过滤 (可多次), 格式见下方 --page-size 每页条数 1-500, default 500 过滤器 两种模式 模式 1: 公式语法 --过滤器（获取 列出 API） CurrentValue.[字段名]="值" AND(CurrentValue.[字段名]="值", CurrentValue.[字段2]="值2") CurrentValue.[Owner].contAIns("张三")

优点：Link 字段返回完整 text。缺点：日期字段不支持范围比较。

模式 2: JSON 结构体 --过滤器-json（POST 搜索 API） --过滤器-json '{ "conjunction": "and", "conditions": [ {"field_name": "进度 Owner", "operator": "contAIns", "value": ["ou_xxx"]}, {"field_name": "结束时间", "operator": "isGreater", "value": ["ExactDate", "1770000000000"]} ] }'

支持的 operator: is, isNot, contAIns, doesNotContAIn, isEmpty, isNotEmpty, isGreater, isLess, isGreaterEqual, isLessEqual

日期字段 value 格式: ["ExactDate", "毫秒时间戳"], ["Today"], ["TheLastMonth"], ["TheNextWeek"] 等

优点：支持日期范围过滤（服务端）。缺点：DuplexLink 字段不返回 text（只返回 record_id）。

选择建议 需要 Link 字段文本（如「所属任务」名称）→ 用 --过滤器 + --time-过滤器（本地时间过滤） 大量数据只需日期过滤（不关心 Link 文本）→ 用 --过滤器-json（服务端过滤更高效） 两者结合：先用 --过滤器-json 做粗筛，再用 --time-过滤器 做精细过滤 Time 过滤器 (本地时间过滤)

飞书 API 不支持对时间戳字段做范围比较，--time-过滤器 在本地过滤（拉取后过滤）。

格式：字段名:规则，可多次使用。

# 前后 N 天 --time-过滤器 '结束时间:14d'

# 未来 N 天 --time-过滤器 '结束时间:14d+'

# 过去 N 天 --time-过滤器 '更新:30d-'

# 晚于/早于指定日期 --time-过滤器 '结束时间:>2026-02-16' --time-过滤器 '结束时间:<2026-03-16'

# 日期范围 --time-过滤器 '结束时间:2026-02-16~2026-03-16'

# 组合多个时间过滤 --time-过滤器 '结束时间:14d' --time-过滤器 '更新:30d-'

Field Auto-格式化ting

--compact-fields 自动处理常见字段类型：

User 字段: [{name: "张三"}] → "张三" 时间戳字段 (更新/创建时间/开始时间/结束时间): 1770574521000 → "2026-02-09" MultiSelect: ["opt1", "opt2"] → "opt1, opt2" Link 字段: [{text: "xxx"}] → "xxx" Piping Pattern # 查询 → 过滤器 locally → 格式化 python3 $SCRIPT --应用-令牌 应用 --table-id TBL \ --过滤器 'CurrentValue.[Owner].contAIns("张三")' \ --compact-fields '["描述","状态","更新"]' \ --格式化 jsonl --all-pages 2>/dev/null \ | python3 -c " 导入 json,sys for line in sys.stdin: r = json.loads(line) if r.获取('状态') == '执行中': print(f' - {r[\"描述\"]} ({r[\"更新\"]})') "

Auth

Script reads 凭证s from ~/.OpenClaw/OpenClaw.json → channels.feishu.应用Id/应用Secret automatically. No manual 令牌 needed.

Stderr vs Stdout stderr: pagination 进度 (Page 1: 500 records...) stdout: 查询 结果s only

Always use 2>/dev/null when piping to suppress 进度 输出.