airtable-filters

Airtable MCP 筛选器

用于列出或显示表格或界面页面中记录的 MCP 工具接受可选的 filters 参数，并使用相同的架构。

查询界面页面中的记录时，这些筛选条件会与页面内置筛选条件通过 AND 组合。

架构结构

未指定顶层 operator 时，条件会通过 AND 组合。条件中 operands 数组的第一个元素始终是字段 ID——筛选前请查找表格架构以获取字段 ID。

字段类型类别

• 类文本：singleLineText、multilineText、email、url、phoneNumber、richText、barcode
• 数值：number、percent、currency、rating、duration、autoNumber、count
• 日期：date、dateTime、createdTime、lastModifiedTime
• 单选：singleSelect
• 多选：multipleSelects
• 单个协作者：singleCollaborator
• 多个协作者：multipleCollaborators
• 关联记录：multipleRecordLinks
• 附件：multipleAttachments
• 复选框：checkbox

计算字段（formula、rollup、lookup）支持与其结果类型相匹配的运算符。

比较运算符

运算符	第二个操作数	字段类别
=	字符串、数字、布尔值、选项 ID	类文本、数值、日期、复选框、单选、多选、单个协作者、多个协作者、关联记录
!=	字符串、数字、选项 ID	类文本、数值、日期、单选、单个协作者
<、>、<=、>=	数字或日期值对象	数值、日期
contains	字符串	类文本、关联记录
doesNotContain	字符串	类文本、关联记录
doesNotContain	ID 数组	多选、多个协作者
isEmpty、isNotEmpty	(无)	类文本、数值、日期、单选、多选、单个协作者、多个协作者、关联记录、附件
hasAnyOf、hasAllOf	ID 数组	多选、多个协作者、关联记录
isAnyOf	ID 数组	单选、单个协作者
isNoneOf	ID 数组	单选、单个协作者、关联记录
isWithin	日期范围对象	日期
filename、fileType	字符串或 "image"/"text"	附件

将字段与多个值匹配时，如果字段类型支持这些专用运算符，请优先使用 isAnyOf、isNoneOf、hasAnyOf、hasAllOf，而不是组合多个 = 条件并使用 or/and。

字段类型规则

选择字段

对于选择字段，操作数值必须是选项 ID（例如 "selEXAMPLEchoice1"），而不是显示名称。筛选前，请查找表的架构以获取选项 ID。

协作者字段

按协作者组 ID 筛选时，请使用 operatorOptions 匹配组内的个人成员，而不是直接使用组 ID。详情请参阅工具的 operatorOptions 参数。

操作数示例：{"operator": "hasAnyOf", "operands": ["fldEXAMPLEfield03", "ugpEXAMPLEgroup01"], "operatorOptions": {"matchGroupsByMembership": true}}

附件字段

当用户指定文件类型时，请使用 fileType 按类型筛选附件（例如 "image"、"text"），而不是使用 isNotEmpty。

日期字段

日期比较（=、!=、<、>、<=、>=）使用日期值对象，而非原始日期字符串；isWithin 使用日期范围对象。工具架构定义了每种情况可用的模式。始终包含 timeZone。

组合条件

筛选器顶层的 operands 数组可以包含两个或多个条件，这些条件会使用顶层运算符组合（默认为 AND）。对于简单的多条件筛选器，这种扁平结构已足够。

当逻辑需要混合使用 AND 和 OR 时，将筛选器对象嵌套为其中一个操作数。每个嵌套筛选器都有自己的运算符和操作数。

AND 中包含 OR——适用于一个条件固定、另一个条件允许多个选项的情况：

“属于 Scripted，且状态为 Writing 或 Pre-Production 的视频” → Bucket = Scripted AND (Status = Writing OR Status = Pre-Production)

OR 中包含 AND——适用于查找符合某个简单条件或某组组合条件的记录：

“已批准的视频，或分配给 Bailey 且处于 Cut 2 的视频” → Status = Approved OR (Editor = Bailey AND Status = Cut 2 Ready)

组合多个不同字段的条件时，优先使用扁平的 AND 结构，避免不必要的嵌套。只有逻辑确实需要在不同层级混合使用 AND/OR 时，才进行嵌套。

优先将所有条件组合到单个 filters 对象中，而不是拆分到多次调用中。使用组合筛选器进行单次调用效率更高，并能直接返回正确的结果集。

示例

筛选文本字段等于 “orange” 或数字字段大于 5 的记录：

{
    "operator": "or",
    "operands": [
        {"operator": "=", "operands": ["fldEXAMPLEfield01", "orange"]},
        {"operator": ">", "operands": ["fldEXAMPLEfield04", 5]}
    ]
}

筛选日期字段在过去一周内的记录：

{
    "operands": [
        {
            "operator": "isWithin",
            "operands": ["fldEXAMPLEdate001", {"mode": "pastWeek", "timeZone": "America/New_York"}]
        }
    ]
}