rongshu/.agents/skills/lark-base/references/lark-base-record-search.md

base +record-search

前置条件： 先阅读 ../lark-shared/SKILL.md 了解认证、全局参数和安全规则。

按关键词检索记录；CLI 侧通过 --json 透传请求体。

适用场景

• 需要关键词检索记录。
• 用户已提供明确搜索关键词（keyword）。
• 需要附带 view_id / select_fields 控制检索范围与返回字段。
• 不用于聚合统计。涉及 SUM/AVG/COUNT/MAX/MIN 时改用 +data-query。

推荐命令

lark-cli base +record-search \
  --base-token XXXXXX \
  --table-id tblXXX \
  --json '{"keyword":"Created","search_fields":["Title","fld_owner"],"offset":0,"limit":100}'

lark-cli base +record-search \
  --base-token XXXXXX \
  --table-id tblXXX \
  --json '{"view_id":"vewXXX","keyword":"Alice","search_fields":["Title","Owner"],"select_fields":["Title","Owner","Status"],"offset":0,"limit":50}'

参数

参数	必填	说明
--base-token <token>	是	Base Token
--table-id <id_or_name>	是	表 ID 或表名
--json <object>	是	搜索请求体 JSON（结构要求见下方“JSON 要求”）

返回关键字段

字段	类型	说明
query_context.record_scope	string	记录范围：all_records（全表）/ view_filtered_records（按 view_id 限定到视图记录）
query_context.field_scope	string	字段范围：selected_fields（显式传 select_fields）/ view_visible_fields（未传 select_fields 且按视图可见字段）/ all_fields（未传 select_fields 且无视图限制）
query_context.search_scope	string	实际参与搜索的字段集合，格式类似 fieldTitle(Title), fieldOwner(Owner)

API 入参详情

HTTP 方法和路径：

POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/search

JSON 格式要求

字段	必填	类型	约束
view_id	否	string	传入后仅在该视图范围内搜索，并默认按该视图可见字段返回结果
keyword	是	string	非空，最小长度 1
search_fields	是	string[]	数组长度 1-20；每项是字段 field_id 或字段名，代表在这些字段中做关键词搜索
select_fields	否	string[]	数组长度 <=50；每项是字段 field_id 或字段名
offset	否	int	>=0，默认 0
limit	否	int	1-200，默认 10

坑点

• ⚠️ +record-search 用于检索，不用于聚合分析；聚合场景使用 +data-query。
• ⚠️ 部分字段不支持搜索（例如 attachment、link）；传入后通常不会报错，但可能导致无法命中对应记录。

参考

• lark-base-record.md — record 索引页
• lark-base-record-list.md — 分页列表读取
• lark-base-data-query.md — 聚合分析