Notion Data Sources Query 与 Search API 复合查询实战:AND/OR 嵌套过滤、filter_properties 载荷瘦身与增量 CDC 游标同步工程指南
一、为什么你的 Notion API 查询总是超时 504、触发 429 或拿回几兆冗余 JSON? #
在搭建企业级数据仓库同步(Reverse ETL)、BI 指标大盘或 AI 知识库增量索引管道时,许多研发团队虽然已经从旧版 databases/{id}/query 迁移到了新版数据源接口(参见 Data Sources API 迁移与多表容器实战),但在生产环境中依然频频遭遇以下四类性能与稳定性故障:
- 全表盲拉引发
429与504 Gateway Timeout:每次同步都无条件拉取全库数千行数据,再在本地用 Python/Node.js 过滤状态与更新时间,导致接口翻页几十次,瞬间击穿每秒 3 次请求(3 req/s)的速率上限; - 未启用
filter_properties导致单页响应膨胀数十倍:一张 40 列的项目主表往往包含大量长文本摘要、复杂Rollup和富文本Formula,而下游任务只需要标题、状态与截止日期3 个字段;不加裁剪直接查询会让单批 100 行的 JSON 体积暴增,极易触发网关超时; - 混用
POST /v1/search与数据库查询接口:用全局Search接口去拉取业务流水,不仅不支持按数据库属性(如Status == 进行中)精准过滤,还会因为全局搜索索引的最终一致性延迟导致漏单; - 嵌套
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 四步规范 #
要在十万级数据量下维持亚秒级单页响应与零漏单增量同步,推荐严格执行以下四项工程规范(属性基础定义可参阅 数据库属性全览 与 视图过滤与排序指南):
- 先查数据源元数据,缓存
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% 的响应体大小并显著减少服务端序列化耗时。
- 调用
- 严格遵守
and / or两层复合嵌套上限:- Notion Query Filter 允许在顶层写一个
and或or数组,数组内部最多再嵌套一层or或and。如果需要三层以上逻辑(例如(A 或 B) 且 (C 或 (D 且 E))),应先在本地展开为析取范式(两层or套and),或者先用 Formula 2.0 属性 将复杂条件预先折叠为单个Checkbox门禁列再行过滤。
- Notion Query Filter 允许在顶层写一个
- 利用
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幂等落库。
- 千万不要每次都扫描全库。在
- 主动剔除废纸篓记录与截断关联补采:
- 在
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 投入企业级生产调度前,请逐项完成以下四项架构验收:
- 切勿用
POST /v1/search充当实时事务触发器:- 用户在 Notion 客户端刚刚创建一条记录后立即触发外部 Webhook,若后端立刻调用
POST /v1/search按标题去反查该页,极有可能返回空数组——因为全局搜索索引属于异步更新,存在数秒级延迟。已知data_source_id或page_id时,必须直接调用POST /v1/data_sources/{id}/query或GET /v1/pages/{page_id}。
- 用户在 Notion 客户端刚刚创建一条记录后立即触发外部 Webhook,若后端立刻调用
- 注意
filter_properties必须传 URL 编码后的property_id,且无法过滤掉系统元数据:- 虽然启用
filter_properties可以剔除冗余业务列(如长达数千字的多行备注与复杂的关联字段),但每条记录的顶层系统字段(id、created_time、last_edited_time、url、in_trash)依然会保留返回,正好满足增量 CDC 游标对比需要。同时注意不同数据源中即使列名都叫“状态”,其底层随机生成的 4 位property_id也不相同,切勿硬编码跨库复用。
- 虽然启用
- 跨月/跨时区
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)。
- 在过滤
- 单次
page_size设为100并不等于单页不会触发 504 超时:- 如果目标数据源包含大量嵌套极深的
Formula或Rollup,即便裁剪了部分字段,单次请求 100 行仍可能逼近网关 60 秒超时红线。当发现某张宽表耗时持续超过 5 秒时,应在代码层将page_size动态降级为25或50,以换取更稳定的流式翻页成功率。
- 如果目标数据源包含大量嵌套极深的
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。