feishu-bitable-query

# 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

```bash
SCRIPT="scripts/feishu_bitable_query.py"

# Count records matching a filter
python3 $SCRIPT --app-token APP --table-id TBL --filter 'EXPR' --count

# Query with filter, compact output
python3 $SCRIPT --app-token APP --table-id TBL \
  --filter 'EXPR' \
  --compact-fields '["字段1","字段2"]' \
  --all-pages 2>/dev/null

# Query with view (uses view's built-in filter/sort)
python3 $SCRIPT --app-token APP --table-id TBL --view-id VIEW --all-pages

# TSV output for readability
python3 $SCRIPT --app-token APP --table-id TBL \
  --compact-fields '["描述","状态"]' --format tsv --all-pages 2>/dev/null

# JSONL for piping to other tools
python3 $SCRIPT --app-token APP --table-id TBL --format jsonl --all-pages 2>/dev/null
```

## Key Options

| Option | Description |
|--------|-------------|
| `--filter` | 飞书 filter 表达式 (server-side) |
| `--sort` | 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）

```
CurrentValue.[字段名]="值"
AND(CurrentValue.[字段名]="值", C...