はじめに
hkob の雑記録の第441回目(通算15日目)は、Working with views の説明記事の前半を翻訳していきます。元のページはこちらです。
また、View API はかなり規模が大きいので、notion_ruby_mapping への実装は少し時間がかかりそうです。ここまでの markdown 対応、block の position 対応、heading_4 対応までを v4.0.0 としてリリースしておきました。
ビューの扱い方
Notion API を使ってデータベースビューを設定・管理する方法を説明します。
Views API の利用には API バージョン 2025-09-03 以降が必要です。インテグレーションが古いバージョンを使っている場合は、移行手順として アップグレードガイド を参照してください。
概要
データベースビュー を使うと、同じデータをさまざまな形で表示できます。たとえば、テーブル、ボード、カレンダー、タイムライン、ギャラリー、リスト、フォーム、チャート、マップ、ダッシュボードなどです。各ビューは、独自のフィルター、ソート、レイアウト設定を持てるため、単一のデータベースでも多様なワークフローに対応できます。
Notion API はビューを「第一級リソース」として扱います。つまり、UI でユーザーが作成するのと同じビュー設定（プリセット）を、インテグレーション側からプログラムで管理できます。これにより、ワークスペースの初期構築、移行ツールの作成、ビュー設定の自動化などのユースケースが可能になります。
このガイドでは、次を学びます:
構造
ビューは、データベース 内の単一の データソース に紐づきます。ビューは、そのデータソース内のページをどうフィルタし、どう並べ替え、どう表示するかを定義します。
ビューオブジェクトは次のような形です:
{ "object": "view", "id": "a3f1b2c4-5678-4def-abcd-1234567890ab", "parent": { "type": "database_id", "database_id": "248104cd-477e-80fd-b757-e945d38000bd" }, "data_source_id": "248104cd-477e-80af-bc30-000bd28de8f9", "name": "High priority items", "type": "table", "filter": { "property": "Priority", "select": { "equals": "High" } }, "sorts": [ { "property": "Last ordered", "direction": "descending" } ], "quick_filters": { "Status": { "status": { "equals": "In progress" } } }, "configuration": { "type": "table", "properties": [ { "property_id": "title", "visible": true, "width": 300 }, { "property_id": "abc1", "visible": true, "width": 200 }, { "property_id": "def2", "visible": false } ], "group_by": { "type": "status", "property_id": "ghi3", "group_by": "group", "sort": { "type": "manual" } }, "wrap_cells": false, "frozen_column_index": 1, "show_vertical_lines": true }, "created_time": "2026-01-15T10:30:00.000Z", "last_edited_time": "2026-01-20T14:22:00.000Z", "created_by": { "object": "user", "id": "e7f3a4b2-1234-5678-9abc-def012345678" }, "last_edited_by": { "object": "user", "id": "e7f3a4b2-1234-5678-9abc-def012345678" }, "url": "https://www.notion.so/example/248104cd477e80fdb757e945d38000bd?v=a3f1b2c45678" }
主なフィールド:
type— レイアウト種別。table,board,list,calendar,timeline,gallery,form,chart,map,dashboardのいずれか。data_source_id— このビューが対象にするデータソース（どのコレクションの上にあるか）。1つのデータベースに複数のデータソースを持てますが、各ビューは必ず1つのデータソースを対象にします。ダッシュボードビューではnullです（ダッシュボードは複数のウィジェットビューを含み、それぞれがデータソースを持つため）。filterとsorts— データソースクエリの filter と sort と同じ形。quick_filters— ビューのフィルターバーに表示されるプロパティ単位のフィルターのマップ。キーはプロパティ名または ID、値はフィルター条件（プロパティフィルターと同形だがpropertyフィールドを除いたもの）。クイックフィルター を参照。configuration— ビュー種別ごとに異なる表示設定。typeをキーにした判別共用体で、ビュー種別ごとのスキーマは ビュー設定 を参照。このフィールドは、カスタム設定がない場合null。parent— 常にデータベース。ビューは親データベースを通じて取得・管理します。dashboard_view_id— ダッシュボードに属するウィジェットビューの場合のみ存在し、親のダッシュボードビュー ID を参照します。
既定の挙動
API で データベースを作成 すると、Notion は自動で次を用意します:
- データベースコンテナ配下に データソース を1つ
- そのデータソース上の、"Default view" という名前の テーブルビュー を1つ
そのため、新規に作成されたデータベースは、すぐに使用できます（ページを入れるデータソースと、それを表示するビューがある）。
curl -X POST https://api.notion.com/v1/databases \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Content-Type: application/json" \ -H "Notion-Version: 2026-03-11" \ --data '{ "parent": { "type": "page_id", "page_id": "YOUR_PAGE_ID" }, "title": [{ "type": "text", "text": { "content": "My Database" } }], "is_inline": false }'
データベース作成後は、ビュー一覧 で既定ビューを見つけ、必要に応じて追加のビューを作成できます。
ビューの一覧取得
ビューを見つけるには list エンドポイント を使います。ビューの親 database_id または、ビューが参照している data_source_id で絞り込めます。
データベースで絞る
database_id を渡して、特定のデータベースブロック配下のビューを列挙します。
curl -X GET "https://api.notion.com/v1/views?database_id=DATABASE_ID" \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Notion-Version: 2026-03-11"
データソースで絞る
data_source_id を渡して、指定データソース（コレクション）を参照する全ビューを列挙します。これには、ワークスペース内の別ページにあるリンクドビューも含まれます。
curl -X GET "https://api.notion.com/v1/views?data_source_id=DATA_SOURCE_ID" \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Notion-Version: 2026-03-11"
結果は、インテグレーションのアクセス権限でフィルタされます。インテグレーションがアクセスできないページ上のビューは除外されます。
どちらの形式でも、ページネーションされた「ビュー参照」のリストが返ります:
{ "object": "list", "results": [ { "object": "view", "id": "a3f1b2c4-5678-4def-abcd-1234567890ab" }, { "object": "view", "id": "b4e2c3d5-6789-5ef0-bcde-2345678901bc" } ], "next_cursor": null, "has_more": false }
list エンドポイントは最小限の参照（object と id のみ）を返します。フィルター、ソート、設定などの詳細を得るには、各ビューを個別に取得してください。
ビューの取得
ID を指定して ビューを取得 すると、フィルター、ソート、レイアウト設定などを含む完全な設定を確認できます。
curl -X GET https://api.notion.com/v1/views/VIEW_ID \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Notion-Version: 2026-03-11"
レスポンスは完全な ビューオブジェクト です。
ビューの作成
ターゲットのデータソース、名前、ビュー種別を指定して新しいビューを作成します。さらに、database_id（データベースのトップレベルビューとして作成）、view_id（既存ダッシュボードにウィジェットとして追加）、create_database（ページ上にリンクドデータベースビューを作成）のいずれか1つを必ず指定します。必要に応じて、フィルター、ソート、configuration を含められます。完全なパラメータは ビュー作成 を参照してください。
database_id と data_source_id は別 ID です。database_id はデータベースコンテナの ID（データベース取得 が返す ID）です。data_source_id はそのデータベース内の特定データソースの ID（データベースの data_sources 配列から取得）です。ほとんどのデータベースは単一データソースですが、両方の ID が必要です。
curl -X POST https://api.notion.com/v1/views \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Content-Type: application/json" \ -H "Notion-Version: 2026-03-11" \ --data '{ "database_id": "DATABASE_ID", "data_source_id": "DATA_SOURCE_ID", "name": "Recent orders", "type": "table", "filter": { "property": "Last ordered", "date": { "past_week": {} } }, "sorts": [ { "property": "Last ordered", "direction": "descending" } ], "configuration": { "type": "table", "properties": [ { "property_id": "title", "visible": true, "width": 300 }, { "property_id": "abc1", "visible": true, "width": 200 } ], "wrap_cells": true } }'
レスポンスは、全フィールドが埋まった新しい ビューオブジェクト です。
データベース内のビューは、別データベースが所有するデータソースのページを表示するよう設定できます。Notion ではこれを リンクドデータベース（linked view）と呼びます。たとえば、Tasks / Projects / Bugs のフィルタ済みビューを1つのダッシュボードに置く、といった用途に便利です。 API での主な要件は、インテグレーションが「データソースを所有するデータベース」と「ビューを作成する側のデータベース」の両方にアクセスできることです。
複数の select 値でフィルタする
select プロパティを複数値（例: Priority が "Low" または "Medium"）でフィルタするには、or の複合フィルタを使って equals 条件を並べます。
{ "filter": { "or": [ { "property": "Priority", "select": { "equals": "Low" } }, { "property": "Priority", "select": { "equals": "Medium" } } ] } }
API は select / status のフィルタ値を、プロパティの設定済みオプションと照合して検証します。status プロパティでは、グループ名（例: "To-do", "In progress", "Complete"）も受け付けます。値が既存のオプション／グループに一致しない場合、利用可能な値を列挙した説明的なエラーを返します。
必須パラメータ
| パラメータ | 説明 |
|---|---|
data_source_id |
このビューが対象にするデータソースの ID。データベースオブジェクトの data_sources 配列から取得します。 |
name |
ビューの表示名。 |
type |
ビューのレイアウト。table, board, list, calendar, timeline, gallery, form, chart, map, dashboard。 |
任意パラメータ
| パラメータ | 説明 |
|---|---|
database_id |
ビューを作成するデータベース ID。view_id と create_database と排他的。 |
view_id |
ウィジェットとして追加するダッシュボードビュー ID。database_id と create_database と排他的。 |
create_database |
既存データソースを参照するリンクドデータベースビューをページ上に作成。詳細は リンクドデータベースビューの作成。database_id と view_id と排他的。 |
filter |
適用する フィルターオブジェクト。データソースクエリと同形。 |
sorts |
ソートオブジェクト の配列。 |
quick_filters |
ビューのフィルターバー用 クイックフィルター のマップ。 |
configuration |
ビュー設定 オブジェクト。内部の type はビュー type と一致が必要。 |
position |
新しいビューをビュータブバーのどこに配置するか。database_id 指定時のみ有効。ビューの位置 を参照。既定は末尾に追加。 |
placement |
ダッシュボード内のウィジェット配置。view_id 指定時のみ有効。ウィジェット配置 を参照。既定は末尾に新しい行を作成。 |
database_id, view_id, create_database のいずれかを 必ず1つ 指定する必要があります。database_id はデータベースのトップレベルビュー作成、view_id は既存ダッシュボードへのウィジェット追加（詳細は ダッシュボードビュー）、create_database はページ上のリンクドビュー作成（リンクドデータベースビューの作成）です。
データソース ID の見つけ方
データベース ID がある場合は、データベース取得 を呼び出します。レスポンスの data_sources 配列に、各データソースの id と name が含まれます。
さまざまなビュー種別の作成
グルーピング、カバー画像、プロパティ設定を含むボードビュー作成例:
curl -X POST https://api.notion.com/v1/views \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Content-Type: application/json" \ -H "Notion-Version: 2026-03-11" \ --data '{ "database_id": "DATABASE_ID", "data_source_id": "DATA_SOURCE_ID", "name": "Task board", "type": "board", "configuration": { "type": "board", "group_by": { "type": "status", "property_id": "STATUS_PROPERTY_ID", "group_by": "group", "sort": { "type": "manual" } }, "cover": { "type": "page_cover" }, "cover_size": "medium", "card_layout": "compact" } }'
ビューの位置
トップレベルのデータベースビュー（database_id）を作成する場合、position パラメータでビュータブバー上の位置を制御できます。type で判別する共用体です。
| 種別 | フィールド | 説明 |
|---|---|---|
start |
type |
新しいビューを最初のタブにします。 |
end |
type |
新しいビューを最後のタブにします（既定）。 |
after_view |
type, view_id |
指定ビューの直後に配置します。 |
{ "position": { "type": "start" } }
{ "position": { "type": "after_view", "view_id": "EXISTING_VIEW_ID" } }
position は database_id 指定時のみ有効で、view_id（ダッシュボードウィジェット作成）では使えません。
リンクドデータベースビューの作成
create_database パラメータで、既存データソースを参照する軽量なリンクドデータベースビューをページ上に作成できます。指定ページ上に「データベースコンテナ」が新規作成され、その中に指定データソース上の単一ビューが置かれます。これは UI の「リンクドビュー」を挿入するのに相当します。
これは POST /v1/databases（新しいスキーマとデータソースを持つ独立データベースを作る）とは異なります。create_database は既存データソースを指すため、新しいスキーマは作られません。
curl -X POST https://api.notion.com/v1/views \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Content-Type: application/json" \ -H "Notion-Version: 2026-03-11" \ --data '{ "create_database": { "parent": { "type": "page_id", "page_id": "TARGET_PAGE_ID" } }, "data_source_id": "EXISTING_DATA_SOURCE_ID", "name": "Tasks overview", "type": "table" }'
create_database のフィールド:
| フィールド | 必須 | 説明 |
|---|---|---|
parent |
はい | リンクドデータベースの親ページ。{ "type": "page_id", "page_id": "..." }。 |
position |
いいえ | 親ページ内の配置。{ "type": "after_block", "block_id": "..." } で特定ブロックの後に配置できます。参照先ブロックは親ページ直下の子である必要があります。既定は末尾に追加。 |
create_database ではフォームやダッシュボードを含め、すべてのビュー種別がサポートされます。ダッシュボードは空のレイアウトで作られるため、view_id を使って別途ウィジェットビューを追加します。
インテグレーションは、ターゲットページ（新しいコンテナを作る場所）と、参照されるデータソースを所有するデータベースの両方にアクセスできる必要があります。
ビューの更新
ビューを更新 して、名前、フィルター、ソート、設定を変更できます。全フィールドは任意で、変更したいものだけを含めます。
curl -X PATCH https://api.notion.com/v1/views/VIEW_ID \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Content-Type: application/json" \ -H "Notion-Version: 2026-03-11" \ --data '{ "name": "Completed this month", "filter": { "and": [ { "property": "Status", "status": { "equals": "Done" } }, { "property": "Completed date", "date": { "this_month": {} } } ] }, "sorts": [ { "property": "Completed date", "direction": "descending" } ], "configuration": { "type": "table", "group_by": null, "properties": [ { "property_id": "title", "visible": true, "width": 400 }, { "property_id": "abc1", "visible": true }, { "property_id": "def2", "visible": false } ] } }'
ビューの filter / sorts / 設定フィールドを消すには null を設定します。例は null で設定をクリア を参照してください。
ビューの削除
ID を指定して ビューを削除 すると、データベースのビュー一覧から永久に削除されます。
curl -X DELETE https://api.notion.com/v1/views/VIEW_ID \ -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \ -H "Notion-Version: 2026-03-11"
レスポンスは、識別用の最小フィールド（object, id, parent, type）のみを含む部分ビューオブジェクトです。削除されたため、フィルターやソートなどの完全な詳細は含まれません。
ビューの削除は API からは元に戻せません。データベースのビュー一覧にも表示されなくなります。
データベースは必ず少なくとも1つのビューを持つ必要があります。最後の1つを削除しようとすると validation_error になります。データベース自体を削除するには、代わりに update database で in_trash を true に設定してください。
ビュー設定
ビューオブジェクトの configuration は、種別ごとの表示設定（列幅、グルーピング、カバー画像、サブタスクなど）を制御します。type をキーにした判別共用体で、トップレベルの type と一致する必要があります。
configuration は、ビューの 作成 と 更新 の両方で指定できます。null を許容するフィールドは null を渡すとクリアできます。
ビュー種別ごとの機能対応
ここからビューごとの細かい設定になるので省略します。
