Feishu Bitable - SQL-like Database Interface

Read and edit Feishu Bitable (多维表格) data with a familiar SQL-like interface.

Quick Start with URL

Simply pass the Feishu URL and the skill will auto-extract all parameters:

# Parse URL to see extracted parameters
python3 {baseDir}/feishu_bitable.py parse-url "https://xxx.feishu.cn/base/APP_TOKEN?table=TABLE_ID&view=VIEW_ID"

# Query records using URL
python3 {baseDir}/feishu_bitable.py select --url "https://xxx.feishu.cn/base/APP_TOKEN?table=TABLE_ID" --limit 10

# Get table schema using URL
python3 {baseDir}/feishu_bitable.py describe --url "https://xxx.feishu.cn/base/APP_TOKEN?table=TABLE_ID"

Quick Reference

Operation	Command
Parse URL	parse-url <URL>
List tables	list-tables --url <URL>
Get schema	describe --url <URL>
Query records	select --url <URL> --limit 100
Count records	count --url <URL>
Insert record	insert --url <URL> --data '{"field":"value"}'
Update record	update --url <URL> --record-id R --data '{"field":"value"}'
Delete record	delete --url <URL> --record-id R
Aggregate	aggregate --url <URL> --group-by Field --agg "SUM(Amount)"

URL Format

Feishu Bitable URLs follow this pattern:

https://<domain>.feishu.cn/base/<app_token>?table=<table_id>&view=<view_id>

Example:
https://ncnv0ov0snlp.feishu.cn/base/IsPPb8tkYaIiwdsjiS1cG8tTnhe?table=tblOetM5ZD9wSTGH&view=vew6BTuyh8

Extracted:
- app_token: IsPPb8tkYaIiwdsjiS1cG8tTnhe
- table_id: tblOetM5ZD9wSTGH
- view_id: vew6BTuyh8

Commands

1. Parse URL

Extract parameters from a Feishu URL:

python3 {baseDir}/feishu_bitable.py parse-url "https://xxx.feishu.cn/base/APP_TOKEN?table=TABLE_ID&view=VIEW_ID"

Output:

{
  "ok": true,
  "app_token": "IsPPb8tkYaIiwdsjiS1cG8tTnhe",
  "table_id": "tblOetM5ZD9wSTGH",
  "view_id": "vew6BTuyh8"
}

2. List Tables

List all tables in a Bitable app:

python3 {baseDir}/feishu_bitable.py list-tables --url <URL>
# Or with app-token
python3 {baseDir}/feishu_bitable.py list-tables --app-token <APP_TOKEN>

Output:

{
  "ok": true,
  "tables": [
    { "table_id": "tblXXX", "name": "Orders", "revision": 1 },
    { "table_id": "tblYYY", "name": "Products", "revision": 1 }
  ]
}

3. Describe Table (Get Schema)

Get table fields and views:

python3 {baseDir}/feishu_bitable.py describe --url <URL>

Output includes:

• fields: Field definitions with names, types, and properties
• views: Available views with IDs and names

Field types: 1=Text, 2=Number, 3=SingleSelect, 4=MultiSelect, 5=Date, 7=Checkbox, 11=Person, 15=URL, 17=Attachment, 18=Link

4. SELECT - Query Records

Basic query (returns all records up to limit):

python3 {baseDir}/feishu_bitable.py select --url <URL> --limit 100

Filter by view (recommended for filtering):

python3 {baseDir}/feishu_bitable.py select --url <URL> --view-id <VIEW_ID> --limit 100

Select specific fields:

python3 {baseDir}/feishu_bitable.py select --url <URL> --fields "Name,Status,Amount" --limit 100

Sort results:

python3 {baseDir}/feishu_bitable.py select --url <URL> --order-by "created_time DESC" --limit 100

5. COUNT - Count Records

python3 {baseDir}/feishu_bitable.py count --url <URL>

Output:

{ "ok": true, "count": 42 }

6. AGGREGATE - Group By & Sum

Group by field with aggregations:

python3 {baseDir}/feishu_bitable.py aggregate 
  --url <URL> 
  --group-by "Category" 
  --agg "SUM(Amount), COUNT(), AVG(Score)"

Output:

{
  "ok": true,
  "total_groups": 3,
  "groups": [
    { "Category": "Electronics", "sum_Amount": 15000, "count": 42, "avg_Score": 4.5 },
    { "Category": "Clothing", "sum_Amount": 8000, "count": 30, "avg_Score": 4.2 }
  ]
}

Aggregation functions: COUNT, SUM, AVG, MIN, MAX

With alias:

--agg "SUM(Amount) as total, AVG(Score) as avg_score"

7. INSERT - Create Records

Create single record:

python3 {baseDir}/feishu_bitable.py insert 
  --url <URL> 
  --data '{"Name": "New Item", "Status": "Pending", "Amount": 100}'

Create multiple records:

python3 {baseDir}/feishu_bitable.py insert-batch 
  --url <URL> 
  --data '[{"Name": "Item 1"}, {"Name": "Item 2"}, {"Name": "Item 3"}]'

8. UPDATE - Update Records

Update by record_id:

python3 {baseDir}/feishu_bitable.py update 
  --url <URL> 
  --record-id recXXXXXX 
  --data '{"Status": "Done"}'

9. DELETE - Delete Records

Delete by record_id:

python3 {baseDir}/feishu_bitable.py delete 
  --url <URL> 
  --record-id recXXXXXX

Delete multiple records:

python3 {baseDir}/feishu_bitable.py delete 
  --url <URL> 
  --record-ids "recXXX,recYYY,recZZZ"

Field Value Formats

Field Type	Value Format
Text	"string"
Number	123 or 45.67
SingleSelect	"Option Name"
MultiSelect	["Tag1", "Tag2"]
Checkbox	true or false
Date	1709000000000 (timestamp in ms)
Person	{"id": "ou_xxx"}
Link	["recXXX", "recYYY"]
Attachment	[{"file_token": "...", "name": "file.pdf"}]

Common Workflows

Explore a new Bitable

# 1. Parse URL to verify
python3 {baseDir}/feishu_bitable.py parse-url "https://xxx.feishu.cn/base/APP?table=TBL&view=VIEW"

# 2. Get schema
python3 {baseDir}/feishu_bitable.py describe --url <URL>

# 3. Query first few records
python3 {baseDir}/feishu_bitable.py select --url <URL> --limit 5

Query and aggregate data

# 1. Query records
python3 {baseDir}/feishu_bitable.py select --url <URL> --limit 100

# 2. Aggregate by category
python3 {baseDir}/feishu_bitable.py aggregate 
  --url <URL> 
  --group-by "Category" 
  --agg "SUM(Amount), COUNT()"

Create multiple records

python3 {baseDir}/feishu_bitable.py insert-batch 
  --url <URL> 
  --data '[
    {"Name": "Task 1", "Status": "Todo"},
    {"Name": "Task 2", "Status": "Todo"},
    {"Name": "Task 3", "Status": "Done"}
  ]'

Troubleshooting

Authentication Errors

• Verify FEISHU_APP_ID and FEISHU_APP_SECRET are set
• Check app has required permissions: bitable:app, bitable:app:readonly

Permission Errors (403)

• Share the Bitable to the app bot as collaborator
• Check API permissions in Feishu admin console

Empty Results

• Verify URL is correct
• Try using --view-id to filter by a specific view

Rate Limits

• 100 requests/minute per app per tenant
• 10 requests/second per app per tenant

Environment Variables

Required:

• FEISHU_APP_ID - Feishu application ID
• FEISHU_APP_SECRET - Feishu application secret

Optional:

• FEISHU_API_HOST - API host (default: https://open.feishu.cn)
• FEISHU_DEBUG - Set to 1 for debug output
• FEISHU_PRETTY - Set to 1 for pretty JSON output