Notion APIのデータベース操作APIに破壊的変更があったので、実装を修正してみる
Notion APIのバージョン2025-09-03における破壊的変更について解説します。単一データベースモデルからマルチソースデータベースモデルへの移行に伴う実装修正方法を紹介します。
目次
Notion API はバージョン 2025-09-03 において、データベースの概念を根本的に変更しています。
従来の単一データベースモデルからマルチソースデータベースモデルへと移行し、これに伴い後方互換性のない破壊的変更が導入されました。
詳細は以下の公式ドキュメントをご確認いただきたいのですが、ここでは私が実際に触ってみてつまづいたところをまとめていきます。
Upgrading to Version 2025-09-03
Notion has released API version 2025-09-03 , introducing support for multi-source databases, which requires updates to existing integrations due to non-backward compatibility, including changes to API operations and endpoints. Users must update their integrations to use data_source_id instead of dat...
主要な変更点
APIエンドポイントの移行
Most API operations that used
database_idnow require adata_source_id
- 従来:
databases.query({ database_id }) - 新仕様:
dataSources.query({ data_source_id })
新しい @notionhq/client v5.2.1 では databases オブジェクトに query メソッドが存在しないため、型エラーになることが発生します。
GitHub Actions から actions/github-script を用いて Notion へのアクセスを行おうとした結果、以下のような型エラーが発生しました。
import type { Client } from '@notionhq/client';
export type NotionClient = Client;
// プロパティ 'query' は型 '{ retrieve: (args: WithAuth<GetDatabasePathParameters>) => Promise<GetDatabaseResponse>; create: (args: WithAuth<CreateDatabaseBodyParameters>) => Promise<...>; update: (args: WithAuth<...>) => Promise<...>; }' に存在しません。
export type NotionDatabaseQueryResult = Awaited<
ReturnType<NotionClient['databases']['query']>
>;このように修正すれば型エラーは発生しなくなります。
import type { Client } from '@notionhq/client';
export type NotionClient = Client;
export type NotionDataSourceQueryResult = Awaited<
ReturnType<NotionClient['dataSources']['query']>
>;IDの取得方法の変更
従来のデータベース ID の取得方法は、290779d04d0280548d2be29e12530de6 の部分を設定すればよかったのですが、新しくデータソース ID という概念が登場しました。
実際にデータベースを開いて、データベース設定 → "データベースを管理する" → "⋯" → "データソース ID をコピー"で取得できます。
データソース ID は 290779d0-4d02-808a-a37f-000b48c16318 のようなハイフン付きの ID が取得可能です。
以下のようなコードで取得したデータソースへアクセスが可能です。
const notionToken = process.env.NOTION_TOKEN;
const dataSourceId = process.env.NOTION_DATA_SOURCE_ID;
const notion = new Client({ auth: notionToken });
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
page_size: 5,
});実装時の注意点
開発時は Claude Code で Context7 等のドキュメント検索ツールを使用していましたが、まだドキュメントの修正が追いついておらず、取得される情報は旧 API バージョンに基づいている場合が多かったです。
特に以下の点に注意する必要があります。
- 例示されている
databases.queryは現在の最新 SDK では利用できない database_idパラメータはdata_source_idに置き換える必要がある
参考資料
Upgrading to Version 2025-09-03
Notion has released API version 2025-09-03 , introducing support for multi-source databases, which requires updates to existing integrations due to non-backward compatibility, including changes to API operations and endpoints. Users must update their integrations to use data_source_id instead of dat...
FAQs: Version 2025-09-03
Commonly asked questions about data sources and how to migrate to Notion's API version 2025-09-03
