第4章データベースのクエリとレコード操作

Notion のデータベースを対象に、レコードの検索（クエリ）、条件絞り込み（フィルター）、並び替え（ソート）、新規レコードの挿入、既存レコードの更新を行う Python プログラムの実装方法を解説します。

データベースのレコード取得（クエリ）

データベースの全レコードまたは特定条件に合うレコードを取得するには、databases.query を呼び出します。

Python（notion-client）による基本クエリ

import os
from dotenv import load_dotenv
from notion_client import Client

load_dotenv()
notion = Client(auth=os.getenv("NOTION_TOKEN"))
database_id = os.getenv("NOTION_DATABASE_ID")

# データベースからレコードを取得
response = notion.databases.query(
    database_id=database_id,
    page_size=10
)

# レコード一覧をループ処理
for page in response.get("results", []):
    page_id = page["id"]
    props = page["properties"]
    
    # "名前" 列（title型）の値を取得
    title_list = props.get("名前", {}).get("title", [])
    title_text = title_list[0]["plain_text"] if title_list else "（無題）"
    
    print(f"ID: {page_id} | タイトル: {title_text}")

フィルターとソートの指定

Notion API では、条件を指定して効率的にデータを絞り込むことができます。

フィルター（絞り込み）

たとえば、「ステータスが “未着手”」または「期限が今日以降」のタスクを絞り込む構文です。

# ステータスが「未着手」のレコードのみ取得
query_filter = {
    "property": "ステータス",
    "status": {
        "equals": "未着手"
    }
}

response = notion.databases.query(
    database_id=database_id,
    filter=query_filter
)

複合条件（AND / OR）を指定する場合は、and や or のリストを使います。

query_filter = {
    "and": [
        {
            "property": "ステータス",
            "status": {
                "equals": "進行中"
            }
        },
        {
            "property": "優先度",
            "select": {
                "equals": "高"
            }
        }
    ]
}

ソート（並び替え）

取得結果を特定の日付順や優先度順に並べ替えるには sorts パラメータを指定します。

response = notion.databases.query(
    database_id=database_id,
    sorts=[
        {
            "property": "作成日時",
            "direction": "descending"  # 降順（新しい順）
        }
    ]
)

ページネーション（100件を超えるデータの取得）

Notion API は、1 回のリクエストで最大 100 件のレコードしか返しません。 100 件を超えるデータをすべて取得するには、カーソルを使ったページネーション処理を行います。

all_records = []
has_more = True
next_cursor = None

while has_more:
    kwargs = {"database_id": database_id, "page_size": 100}
    if next_cursor:
        kwargs["start_cursor"] = next_cursor
        
    res = notion.databases.query(**kwargs)
    all_records.extend(res.get("results", []))
    
    has_more = res.get("has_more", False)
    next_cursor = res.get("next_cursor")

print(f"取得完了: 合計 {len(all_records)} 件")

新規レコード（行）の追加

データベースに新しい行を追加するには、親（parent）にデータベース ID を指定して ページ作成 API（pages.create） を呼び出します。

new_page = notion.pages.create(
    parent={"database_id": database_id},
    properties={
        "タスク名": {
            "title": [
                {"text": {"content": "週次レポート作成"}}
            ]
        },
        "ステータス": {
            "status": {
                "name": "未着手"
            }
        },
        "優先度": {
            "select": {
                "name": "高"
            }
        },
        "期日": {
            "date": {
                "start": "2026-10-10"
            }
        },
        "完了": {
            "checkbox": False
        }
    }
)

print(f"新規レコード作成完了: {new_page['id']}")

既存レコードのプロパティ更新

既存のレコード（ページ）のプロパティを変更するには、pages.update を使用します。変更したい列のみを指定します。

page_id = "target_page_id_here"

updated_page = notion.pages.update(
    page_id=page_id,
    properties={
        "ステータス": {
            "status": {
                "name": "完了"
            }
        },
        "完了": {
            "checkbox": True
        }
    }
)

print(f"レコード更新完了: {updated_page['id']}")

Keyboard shortcuts