Notion Data Sources Query 与 Search API 复合查询实战:AND/OR 嵌套过滤、filter_properties 载荷瘦身与增量 CDC 游标同步工程指南

2026 年 11 月 20 日

一、为什么你的 Notion API 查询总是超时 504、触发 429 或拿回几兆冗余 JSON? #

在搭建企业级数据仓库同步(Reverse ETL)、BI 指标大盘或 AI 知识库增量索引管道时,许多研发团队虽然已经从旧版 databases/{id}/query 迁移到了新版数据源接口(参见 Data Sources API 迁移与多表容器实战),但在生产环境中依然频频遭遇以下四类性能与稳定性故障:

  1. 全表盲拉引发 429 与 504 Gateway Timeout:每次同步都无条件拉取全库数千行数据,再在本地用 Python/Node.js 过滤状态与更新时间,导致接口翻页几十次,瞬间击穿每秒 3 次请求(3 req/s)的速率上限;
  2. 未启用 filter_properties 导致单页响应膨胀数十倍:一张 40 列的项目主表往往包含大量长文本摘要、复杂 Rollup 和富文本 Formula,而下游任务只需要 标题、状态 与 截止日期 3 个字段;不加裁剪直接查询会让单批 100 行的 JSON 体积暴增,极易触发网关超时;
  3. 混用 POST /v1/search 与数据库查询接口:用全局 Search 接口去拉取业务流水,不仅不支持按数据库属性(如 Status == 进行中)精准过滤,还会因为全局搜索索引的最终一致性延迟导致漏单;
  4. 嵌套 and / or 过滤超过两层直接报 400 validation_error:Notion 查询过滤树在服务端严格限制嵌套深度,超出限制会整批拒绝请求。

在构建高吞吐同步流水线前,务必先厘清 Notion API 2025-09-03 三大检索与读取端点的能力边界(集成鉴权基础参阅 创建 Notion API 集成):

接口端点(Notion-Version: 2025-09-03) 过滤与排序能力 载荷裁剪支持 一致性与分页上限 核心适用工程场景
POST /v1/data_sources/{id}/query 支持全属性类型过滤与多字段 sorts(含两层 and/or 嵌套) 支持 ?filter_properties= 多值查询参数 强一致实时读取;单页 page_size <= 100 生产级增量 CDC 同步、业务状态轮询与条件导出
POST /v1/search 仅支持 object(page / data_source)与标题关键词匹配 不支持字段裁剪 最终一致(新建/修改页面有数秒索引延迟) 动态发现已授权数据源 ID 或工作区模糊定位
GET /v1/pages/{page_id}/properties/{prop_id} 无过滤;针对单页单属性精准取值 天然单字段最小载荷 支持分页返回 超过 25 项 的 relation 与长列表 补齐 Query 中被截断的关联列表与复杂汇总
GET /v1/blocks/{block_id}/children 仅按块树层级递归读取正文内容 无字段裁剪 单层 page_size <= 100 页面正文 Markdown/RAG 提取(参见 Blocks API 实战)

二、复合过滤(Compound Filter)、载荷瘦身与增量 CDC 四步规范 #

要在十万级数据量下维持亚秒级单页响应与零漏单增量同步,推荐严格执行以下四项工程规范(属性基础定义可参阅 数据库属性全览 与 视图过滤与排序指南):

  1. 先查数据源元数据,缓存 property_id 用于 filter_properties 裁剪:
    • 调用 POST /v1/data_sources/{id}/query 时,可以在 URL Query String 中追加多个 filter_properties 参数(例如 ?filter_properties=title&filter_properties=abc%3A1)。
    • 注意:filter_properties 接收的是属性的内部 id(如 title 或经过 URL 编码的 4 位字符 ID),而不是人类可读的中文属性名!因此同步脚本启动时应先调用一次 GET /v1/data_sources/{id},将需要的列名自动映射为 property_id 列表。实测在 30 列以上的宽表中,该参数可降低 65%~85% 的响应体大小并显著减少服务端序列化耗时。
  2. 严格遵守 and / or 两层复合嵌套上限:
    • Notion Query Filter 允许在顶层写一个 and 或 or 数组,数组内部最多再嵌套一层 or 或 and。如果需要三层以上逻辑(例如 (A 或 B) 且 (C 或 (D 且 E))),应先在本地展开为析取范式(两层 or 套 and),或者先用 Formula 2.0 属性 将复杂条件预先折叠为单个 Checkbox 门禁列再行过滤。
  3. 利用 timestamp: "last_edited_time" 构建增量 CDC 游标(Watermark):
    • 千万不要每次都扫描全库。在 filter 的顶层 and 数组中嵌入时间戳条件:{"timestamp": "last_edited_time", "last_edited_time": {"on_or_after": last_watermark_iso}},并搭配 sorts: [{"timestamp": "last_edited_time", "direction": "ascending"}]。
    • 为避免同一秒内并发修改引发边界漏数,每次增量拉取后应将游标回退 5 秒重叠窗口(Overlap Window),并在下游数据库按 page_id 执行 UPSERT 幂等落库。
  4. 主动剔除废纸篓记录与截断关联补采:
    • 在 2025-09-03 版本响应中,若目标行刚被拖入废纸篓或外部仅软删除,需检查页面对象中的 in_trash 布尔标记并同步清理下游索引;
    • 若裁剪后的关键 relation 属性返回 "has_more": true(即单行关联超过 25 条),务必再调用 GET /v1/pages/{page_id}/properties/{property_id} 翻页补全(详见 Relation 与 Rollup 工程治理)。

三、Notion API 2025-09-03 实战:带载荷瘦身与增量游标的 Python 同步脚本 #

以下生产级 Python 脚本完整演示了:自动解析属性 ID 构建 filter_properties、组装两层 and/or + last_edited_time 复合过滤、升序游标分页,以及 429 Retry-After 退避防护。

import os
import time
from datetime import datetime, timedelta, timezone
from typing import Any
import httpx

NOTION_TOKEN = os.environ["NOTION_TOKEN"]
DATA_SOURCE_ID = os.environ["NOTION_DATA_SOURCE_ID"]

HEADERS = {
    "Authorization": f"Bearer {NOTION_TOKEN}",
    "Notion-Version": "2025-09-03",
    "Content-Type": "application/json",
}

def request_with_retry(
    client: httpx.Client, method: str, url: str, **kwargs: Any
) -> dict[str, Any]:
    """统一处理 429 速率限制与 5xx 瞬断的重试封装"""
    for attempt in range(5):
        resp = client.request(method, url, headers=HEADERS, timeout=25.0, **kwargs)
        if resp.status_code == 429:
            retry_after = float(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(retry_after + 0.25)
            continue
        if resp.status_code in (500, 502, 503, 504) and attempt < 4:
            time.sleep(1.5 * (attempt + 1))
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"Notion API 请求连续失败: {method} {url}")

def resolve_property_ids(
    client: httpx.Client, data_source_id: str, required_names: list[str]
) -> list[str]:
    """拉取 Data Source Schema,将中文/英文列名映射为 filter_properties 所需的 property_id"""
    ds_meta = request_with_retry(
        client, "GET", f"https://api.notion.com/v1/data_sources/{data_source_id}"
    )
    props = ds_meta.get("properties", {})
    prop_ids: list[str] = []
    for name in required_names:
        if name in props:
            prop_ids.append(props[name]["id"])
    return prop_ids

def query_incremental_cdc(
    client: httpx.Client,
    data_source_id: str,
    last_watermark_iso: str,
    required_prop_names: list[str],
) -> tuple[list[dict[str, Any]], str]:
    """执行增量复合查询(AND/OR 嵌套 + filter_properties 载荷裁剪 + 游标分页)"""
    prop_ids = resolve_property_ids(client, data_source_id, required_prop_names)
    # httpx params 传入 list[tuple[str, str]] 可自动生成 ?filter_properties=id1&filter_properties=id2
    query_params = [("filter_properties", pid) for pid in prop_ids]

    # 两层复合过滤:(last_edited_time >= watermark) AND (状态 == 进行中 OR 状态 == 待验收)
    payload: dict[str, Any] = {
        "page_size": 100,
        "filter": {
            "and": [
                {
                    "timestamp": "last_edited_time",
                    "last_edited_time": {"on_or_after": last_watermark_iso},
                },
                {
                    "or": [
                        {"property": "状态", "status": {"equals": "进行中"}},
                        {"property": "状态", "status": {"equals": "待验收"}},
                    ]
                },
            ]
        },
        "sorts": [
            {"timestamp": "last_edited_time", "direction": "ascending"}
        ],
    }

    records: list[dict[str, Any]] = []
    next_cursor: str | None = None
    max_edited_time = last_watermark_iso

    while True:
        if next_cursor:
            payload["start_cursor"] = next_cursor
        else:
            payload.pop("start_cursor", None)

        data = request_with_retry(
            client,
            "POST",
            f"https://api.notion.com/v1/data_sources/{data_source_id}/query",
            params=query_params,
            json=payload,
        )

        for page in data.get("results", []):
            if page.get("in_trash"):
                continue  # 跳过已移入废纸篓的数据,或在此记录下游软删任务
            edited_at = page.get("last_edited_time", "")
            if edited_at > max_edited_time:
                max_edited_time = edited_at
            records.append(page)

        if not data.get("has_more"):
            break
        next_cursor = data.get("next_cursor")
        time.sleep(0.35)  # 保持在 3 req/s 安全频率内

    # 回退 5 秒安全重叠窗口作为下次增量起点,避免同秒并发修改漏数
    dt = datetime.fromisoformat(max_edited_time.replace("Z", "+00:00"))
    safe_next_watermark = (dt - timedelta(seconds=5)).astimezone(timezone.utc).isoformat()
    return records, safe_next_watermark

if __name__ == "__main__":
    watermark = os.environ.get("SYNC_WATERMARK", "2026-11-19T00:00:00Z")
    cols = ["任务名称", "状态", "负责人", "截止日期"]
    with httpx.Client() as http_client:
        rows, next_wm = query_incremental_cdc(http_client, DATA_SOURCE_ID, watermark, cols)
        print(f"本次增量命中有效记录数: {len(rows)},建议下次游标: {next_wm}")

四、Formula 2.0 实战:CDC 增量查询滞后与载荷膨胀门禁闭环 #

为了防止外部同步管道在无人察觉的情况下悄然停摆、或者某张业务表因为无限新增属性列而拖慢 API 响应,建议在企业的《集成管道监控台账》中建立 单次同步耗时(ms)(Number)、返回字段数(Number)、最后增量游标时间(Date)与 同步状态(Status)属性,并配置如下 查询健康度门禁 Formula 2.0 属性(公式语法可参阅 Formula 2.0 速查手册 与 Date 日期时区治理):

lets(
  status, format(prop("同步状态")),
  latencyMs, prop("单次同步耗时(ms)"),
  colCount, prop("返回字段数"),
  watermark, prop("最后增量游标时间"),
  lagMins, if(!empty(watermark), dateBetween(now(), watermark, "minutes"), 99999),

  ifs(
    status == "查询报错",
      style("🔴 接口异常:核查 and/or 嵌套层级或 filter_properties 有效性", "red", "bold", "red_background"),
    lagMins > 120,
      style("🚨 游标严重滞后(已超 " + format(lagMins) + " 分钟未同步)", "red", "bold", "red_background"),
    colCount > 15,
      style("🟠 未裁剪载荷(返回 " + format(colCount) + " 列):请启用 filter_properties 瘦身", "orange", "bold", "yellow_background"),
    latencyMs >= 4500,
      style("🟡 响应缓慢(" + format(latencyMs) + " ms):建议缩小增量窗口或拆表", "orange", "bold"),
    style("🟢 CDC 查询健康 · 延迟 " + format(lagMins) + " 分钟", "green")
  )
)

若接口持续返回 400、429 或页面响应超长导致同步中断,请结合 Notion 常见报错与故障诊断手册 与 数据库架构选型速查 进行全链路排查。


五、生产环境高频踩坑清单与上线前核验要点 #

在将 Data Sources Query 与 Search API 投入企业级生产调度前,请逐项完成以下四项架构验收:

  1. 切勿用 POST /v1/search 充当实时事务触发器:
    • 用户在 Notion 客户端刚刚创建一条记录后立即触发外部 Webhook,若后端立刻调用 POST /v1/search 按标题去反查该页,极有可能返回空数组——因为全局搜索索引属于异步更新,存在数秒级延迟。已知 data_source_id 或 page_id 时,必须直接调用 POST /v1/data_sources/{id}/query 或 GET /v1/pages/{page_id}。
  2. 注意 filter_properties 必须传 URL 编码后的 property_id,且无法过滤掉系统元数据:
    • 虽然启用 filter_properties 可以剔除冗余业务列(如长达数千字的多行备注与复杂的关联字段),但每条记录的顶层系统字段(id、created_time、last_edited_time、url、in_trash)依然会保留返回,正好满足增量 CDC 游标对比需要。同时注意不同数据源中即使列名都叫“状态”,其底层随机生成的 4 位 property_id 也不相同,切勿硬编码跨库复用。
  3. 跨月/跨时区 date 过滤务必显式携带 ISO-8601 时区偏移:
    • 在过滤 Date 属性时,若只传 "2026-11-20" 而不带时间与时区(例如 +08:00 或 Z),Notion 默认按 UTC 零点 解析,会导致北京时间早上 00:00~08:00 之间的工单被错归到前一天或后一天。所有服务端过滤日期字符串应统一标准化为带时区的完整 ISO-8601 格式(如 2026-11-20T00:00:00+08:00)。
  4. 单次 page_size 设为 100 并不等于单页不会触发 504 超时:
    • 如果目标数据源包含大量嵌套极深的 Formula 或 Rollup,即便裁剪了部分字段,单次请求 100 行仍可能逼近网关 60 秒超时红线。当发现某张宽表耗时持续超过 5 秒时,应在代码层将 page_size 动态降级为 25 或 50,以换取更稳定的流式翻页成功率。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。