Notion · 2026.06.09 · 4 min read
Notion API 查詢資料庫教學：filter、sort、pagination 與 data source query 完整範例（2026）
Notion API 查詢資料庫教學：filter、sort、pagination 與 data source query 完整範例（2026）
解答先行
2026 年要用 Notion API 查資料庫資料，建議先改用這個觀念：
你不是在 query database，而是在 query database 底下的 data source。
最常用 endpoint 是：
POST /v1/data_sources/{data_source_id}/query
如果你還沒拿到 token，先看母文：Notion API Key 怎麼拿。如果你還沒用 curl 測過連線，先跑這篇：Notion API 用 curl 測試教學。
這篇專門處理查資料庫時最常卡住的 4 件事：
| 問題 | 對應做法 |
|---|---|
| 不知道要用哪個 ID | 先用 search 找 data source |
| 想只查特定狀態 | 用 filter |
| 想照時間排序 | 用 sorts |
| 資料很多查不完 | 用 start_cursor 和 has_more |
database 和 data source 差在哪？
舊教學常寫：
POST /v1/databases/{database_id}/query
但 Notion 官方在 2025-09-03 之後，把 database 和 data_source 拆開。新寫法應該優先理解：
| 名詞 | 白話理解 |
|---|---|
| database | Notion UI 裡看到的資料庫容器 |
| data source | 裡面真正被查詢、排序、篩選的資料表 |
| page | data source 裡的一筆資料 |
如果你只是寫一個新自動化，不建議繼續把 database id 當唯一答案。先找 data source id，後面接 filter、sort、webhook 會比較不容易改到崩。
第一步：先找 data source id
最穩的方式是用 search。
curl -X POST "https://api.notion.com/v1/search" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"query": "文章",
"filter": {
"property": "object",
"value": "data_source"
},
"page_size": 10
}'
如果找不到，通常不是 API 壞掉，而是權限沒開。
請回 Notion 把目標 database 或上層 page 的 Add connections 設好。
第二步：查前 10 筆資料
最小 query：
curl -X POST "https://api.notion.com/v1/data_sources/$DATA_SOURCE_ID/query" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"page_size": 10
}'
回傳結果會是一串 page 物件。
這些 page 通常就是你在 Notion database 裡看到的一列資料。
第三步：用 filter 查特定狀態
例如你有一個 Status 欄位，想查 Ready：
curl -X POST "https://api.notion.com/v1/data_sources/$DATA_SOURCE_ID/query" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"filter": {
"property": "Status",
"status": {
"equals": "Ready"
}
},
"page_size": 20
}'
常見 filter 類型：
| 欄位類型 | filter key | 範例 |
|---|---|---|
| status | status |
equals |
| select | select |
equals |
| multi_select | multi_select |
contains |
| checkbox | checkbox |
equals: true |
| date | date |
on_or_after |
| rich_text | rich_text |
contains |
| number | number |
greater_than |
欄位名稱要完全對上 Notion 裡的 property name。中文、大小寫、空格都會影響。
第四步：用 and / or 做複合條件
例如查「已準備好」而且「發布日期在今天之後」：
curl -X POST "https://api.notion.com/v1/data_sources/$DATA_SOURCE_ID/query" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"filter": {
"and": [
{
"property": "Status",
"status": {
"equals": "Ready"
}
},
{
"property": "Publish Date",
"date": {
"on_or_after": "2026-06-09"
}
}
]
},
"page_size": 20
}'
如果條件開始變多，不要急著加。
先用一個 filter 成功，再慢慢加第二個。這樣比較好排錯。
第五步：加 sort 排序
按照最後編輯時間倒序：
curl -X POST "https://api.notion.com/v1/data_sources/$DATA_SOURCE_ID/query" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"sorts": [
{
"timestamp": "last_edited_time",
"direction": "descending"
}
],
"page_size": 20
}'
按照 property 排序：
"sorts": [
{
"property": "Publish Date",
"direction": "ascending"
}
]
排序可以多個條件一起用，但順序很重要。前面的排序優先權比較高。
第六步：處理 pagination
Notion API 不會一次把所有資料都丟給你。
回傳裡通常會有：
| 欄位 | 意思 |
|---|---|
has_more |
後面還有沒有資料 |
next_cursor |
下一頁游標 |
下一次 query 時帶上：
{
"start_cursor": "NEXT_CURSOR",
"page_size": 100
}
實務上，不要每次全表掃描。
比較好的做法是：
| 場景 | 建議 |
|---|---|
| 每天同步文章 | 用 Last edited time 或更新時間 filter |
| 社群排程 | 查 Status = Ready + 日期範圍 |
| CRM | 查 Stage 或 Next Follow-up Date |
| 備份 | 分批跑 pagination，不要一次打到底 |
常見錯誤
| 錯誤 | 最常見原因 | 修法 |
|---|---|---|
| 401 | token 錯 | 回 Developer Portal 重複製 |
| 403 | 沒 Add connections 或缺 read content | 回 Notion 授權 |
| 404 | data source id 錯，或 connection 看不到 | 用 search 重找 |
| 400 | filter 型別或欄位名稱錯 | 先刪到最小 query |
| 429 | 請求太多 | 加 retry / backoff |
最小實戰：查出待發布文章
假設你的 Notion 寫作資料庫有：
| 欄位 | 型別 |
|---|---|
| Name | title |
| Status | status |
| Publish Date | date |
| Slug | rich_text |
你可以查出待發布文章：
curl -X POST "https://api.notion.com/v1/data_sources/$DATA_SOURCE_ID/query" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"filter": {
"and": [
{
"property": "Status",
"status": {
"equals": "Ready"
}
},
{
"property": "Publish Date",
"date": {
"on_or_before": "2026-06-09"
}
}
]
},
"sorts": [
{
"property": "Publish Date",
"direction": "ascending"
}
],
"page_size": 20
}'
這就是很多 Notion 自動化的核心。
查出該處理的資料，再交給下一個工具。
如果你要接 WordPress，可以看：一人自媒體的內容自動化系統：Notion × WordPress × Claude Code。
FAQ
Notion API 查資料庫現在要用 data source id 嗎？
建議用。2026 年的新寫法是用 POST /v1/data_sources/{data_source_id}/query 查資料列。
filter 可以用中文欄位名稱嗎？
可以，但要完全對上 Notion property 名稱。中文、空格、大小寫都要一致。
Notion API 一次可以查幾筆？
你可以設定 page_size，但仍要看 API 回傳的 has_more 和 next_cursor 分頁，不要假設一次會拿完所有資料。
為什麼 query 只回傳部分資料？
可能是 pagination 還沒跑完，也可能是 connection 權限不足，或 filter 條件太嚴。
資料來源
資料最後查核日期：2026-06-09
