データベース エントリのフィルタ

データベースにクエリを実行する場合、指定された条件に基づいて返されるエントリを制限するfilterオブジェクトをリクエストの本文で送信できます。

たとえば、次のクエリは、"Task completed"　checkboxのプロパティ値がtrue であるエントリへの応答を制限します。

cURL

curl -X POST 'https://api.notion.com/v1/databases/897e5a76ae524b489fdfe71f5945d1af/query' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H 'Notion-Version: 2022-06-28' \
  -H "Content-Type: application/json" \
--data '{
  "filter": {
    "property": "Task completed",
    "checkbox": {
        "equals": true
   }
  }
}'

フィルター オブジェクト

各オブジェクトには次のfilterフィールドが含まれます。

フィールド	タイプ	説明	例の値
property	string	データベースに表示されるプロパティの名前、またはプロパティ ID。	"Task completed"
checkbox date files formula multi_select number people phone_number relation rich_text select status timestamp	object	クエリのタイプ固有のフィルター条件。この表のフィールド列にリストされているタイプのみがサポートされています。対応するオブジェクト値の詳細については、タイプ固有のフィルター条件 を参照してください。	"checkbox": { "equals": true }

チェックボックス フィルター オブジェクトの例

{
  "filter": {
    "property": "Task completed",
    "checkbox": {
      "equals": true
    }
  }
}

👍

フィルター オブジェクトは、Notion UI のデータベース フィルター オプションを模倣しています。

タイプ固有のフィルター条件

チェックボックス

フィールド	タイプ	説明	例の値
equals	boolean	checkbox プロパティ値が指定された値と正確に一致するかどうか。 値が完全に一致するすべてのデータベース エントリを返すか除外します。	false
does_not_equal	boolean	checkbox プロパティ値が提供された値と異なるかどうか。 値が異なるすべてのデータベース エントリを返すか除外します。	true

チェックボックスのフィルタ条件の例

{
  "filter": {
    "property": "Task completed",
    "checkbox": {
      "does_not_equal": true
    }
  }
}

日付

📘

after、before、equals, on_or_before、およびon_or_afterフィールドの場合、時刻を含む日付文字列が指定されている場合、比較はミリ秒の精度で行われます。

タイムゾーンが指定されていない場合、タイムゾーンはデフォルトで UTC になります。

日付フィルター条件を使用して、dateプロパティ値のcreated_time型とlast_edited_timeのタイムスタンププロパティの型を制限できます。

条件には以下のフィールドが含まれます。

フィールド	タイプ	説明	例の値
after	string( ISO 8601 日付)	日付プロパティ値と比較する値。 date プロパティ値が指定された日付より後のデータベース エントリを返します。	"2021-05-10" "2021-05-10T12:00:00" "2021-10-15T12:00:00-07:00"
before	string( ISO 8601 日付)	日付プロパティ値と比較する値。 date プロパティ値が指定された日付より前のデータベース エントリを返します。	"2021-05-10" "2021-05-10T12:00:00" "2021-10-15T12:00:00-07:00"
equals	string( ISO 8601 日付)	日付プロパティ値と比較する値。 date プロパティ値が指定された日付であるデータベース エントリを返します。	"2021-05-10" "2021-05-10T12:00:00" "2021-10-15T12:00:00-07:00"
is_empty	true	日付プロパティ値と比較する値。 date プロパティ値にデータが含まれていないデータベース エントリを返します。	true
is_not_empty	true	日付プロパティ値と比較する値。 date プロパティ値が空でないデータベース エントリを返します。	true
next_month	object（空）	日付プロパティの値が翌月に含まれるデータベース エントリに結果を制限するフィルタ。	{}
next_week	object（空）	日付プロパティの値が翌週のデータベース エントリに結果を制限するフィルタ。	{}
next_year	object（空）	日付プロパティの値が翌年にあるデータベース エントリに結果を制限するフィルタ。	{}
on_or_after	string( ISO 8601 日付)	日付プロパティ値と比較する値。 date プロパティ値が指定された日付以降のデータベース エントリを返します。	"2021-05-10" "2021-05-10T12:00:00" "2021-10-15T12:00:00-07:00"
on_or_before	string( ISO 8601 日付)	日付プロパティ値と比較する値。 date プロパティ値が指定された日付以前のデータベース エントリを返します。	"2021-05-10" "2021-05-10T12:00:00" "2021-10-15T12:00:00-07:00"
past_month	object（空）	dateプロパティ値が過去 1 か月以内のデータベース エントリに結果を制限するフィルタ。	{}
past_week	object（空）	dateプロパティ値が過去 1 週間以内のデータベース エントリに結果を制限するフィルタ。	{}
past_year	object（空）	dateプロパティ値が過去 1 年以内のデータベース エントリに結果を制限するフィルタ。	{}
this_week	object（空）	dateプロパティ値が今週であるデータベース エントリに結果を制限するフィルタ。	{}

日付フィルター条件の例

{
  "filter": {
    "property": "Due date",
    "date": {
      "on_or_after": "2023-02-08"
    }
  }
}

ファイル

フィールド	タイプ	説明	例の値
is_empty	true	files filesプロパティ値にデータが含まれていないかどうか。 プロパティ値が空のすべてのデータベース エントリを返します。	true
is_not_empty	true	filesプロパティ値にデータが含まれているかどうか。 設定されたfilesプロパティ値を持つすべてのエントリを返します。	true

サンプルファイルのフィルター条件

{
  "filter": {
    "property": "Blueprint",
    "files": {
      "is_not_empty": true
    }
  }
}

方式

formulaフィルター条件オブジェクトのプライマリ フィールドは、数式の結果の型と一致します。たとえば、 checkboxを計算する数式プロパティをフィルタリングするには、checkbox値としてチェックボックス フィルタ条件を含むフィールドを含むformulaフィルタ条件オブジェクトを使用します。

フィールド	タイプ	説明	例の値
checkbox	object	式の結果を比較するためのチェックボックス フィルター条件。 式の結果が指定された条件に一致するデータベース エントリを返します。	チェックボックスのフィルター条件を参照してください。
date	object	式の結果を比較する日付フィルター条件。 式の結果が指定された条件に一致するデータベース エントリを返します。	日付フィルター条件を参照してください。
number	object	数式の結果を比較する数値フィルター条件。 式の結果が指定された条件に一致するデータベース エントリを返します。	番号フィルター条件を参照してください。
string	object	式の結果を比較するリッチ テキスト フィルター条件。 式の結果が指定された条件に一致するデータベース エントリを返します。	リッチ テキストフィルター条件を参照してください。

数式フィルター条件の例

{
  "filter": {
    "property": "One month deadline",
    "formula": {
      "date":{
          "after": "2021-05-10"
      }
    }
  }
}

複数選択

フィールド	タイプ	説明	例の値
contains	string	複数選択プロパティ値を比較する値。 指定された文字列が複数選択値に含まれるデータベース エントリを返します。	"Marketing"
does_not_contain	string	複数選択プロパティ値に対する値。 指定された文字列が複数選択値に含まれていないデータベース エントリを返します。	"Engineering"
is_empty	true	複数選択プロパティの値が空かどうか。 複数選択値にデータが含まれていないデータベース エントリを返します。	true
is_not_empty	true	複数選択プロパティ値が空でないかどうか。 複数選択値にデータが含まれるデータベース エントリを返します。	true

複数選択フィルター条件の例

{
  "filter": {
    "property": "Programming language",
    "multi_select": {
      "contains": "TypeScript"
    }
  }
}

番号

フィールド	タイプ	説明	例の値
does_not_equal	number	number プロパティ値を比較するnumber。 number プロパティ値が指定されたnumber と異なるデータベース エントリを返します。	42
equals	number	number プロパティ値を比較するnumber 。 number プロパティ値が指定された数値と同じであるデータベース エントリを返します。	42
greater_than	number	number プロパティ値を比較するnumber。 number プロパティ値が指定されたnumber値を超えるデータベース エントリを返します。	42
greater_than_or_equal_to	number	number プロパティ値を比較するnumber。 number プロパティ値が指定されたnumber値以上のデータベース エントリを返します。	42
is_empty	true	numberプロパティ値が空かどうか。 number プロパティ値にデータが含まれていないデータベース エントリを返します。	true
is_not_empty	true	number プロパティ値が空でないかどうか。 number プロパティ値にデータが含まれるデータベース エントリを返します。	true
less_than	number	number プロパティ値を比較するnumber。 ページ プロパティ値が指定されたnumber値より小さいデータベース エントリを返します。	42
less_than_or_equal_to	number	number プロパティ値を比較するnumber。 ページ プロパティ値が指定されたnumber値以下のデータベース エントリを返します。	42

数値フィルタ条件の例

{
  "filter": {
    "property": "Estimated working days",
    "number": {
      "less_than_or_equal_to": 5
    }
  }
}

人

people、created_by、およびlast_edited_byのデータベース プロパティ タイプに人物フィルター条件を適用できます。

ユーザー フィルター条件には、次のフィールドが含まれます。

フィールド	タイプ	説明	例の値
contains	string(UUIDv4)	people プロパティの値と比較する値。 people プロパティ値に指定されたstring が含まれるデータベース エントリを返します。	"6c574cee-ca68-41c8-86e0-1b9e992689fb"
does_not_contain	string(UUIDv4)	people プロパティの値と比較する値。 people プロパティ値に指定された stringが含まれていないデータベース エントリを返します。	"6c574cee-ca68-41c8-86e0-1b9e992689fb"
is_empty	true	people プロパティ値にデータが含まれていないかどうか。 people プロパティ値にデータが含まれていないデータベース エントリを返します。	true
is_not_empty	true	people プロパティ値にデータが含まれているかどうか。 people プロパティ値が空でないデータベース エントリを返します。	true

人物フィルター条件の例

{
  "filter": {
    "property": "Last edited by",
    "people": {
      "contains": "c2f20311-9e54-4d11-8c79-7398424ae41e"
    }
  }
}

関係

フィールド	タイプ	説明	例の値
contains	string(UUIDv4)	関係プロパティ値を比較する値。 関係プロパティ値に指定された stringが含まれるデータベース エントリを返します。	"6c574cee-ca68-41c8-86e0-1b9e992689fb"
does_not_contain	string(UUIDv4)	関係プロパティ値を比較する値。 関係プロパティ値に指定された stringが含まれていないエントリを返します。	"6c574cee-ca68-41c8-86e0-1b9e992689fb"
is_empty	true	関係プロパティ値にデータが含まれていないかどうか。 関係プロパティ値にデータが含まれていないデータベース エントリを返します。	true
is_not_empty	true	関係プロパティ値にデータが含まれているかどうか。 プロパティ値が空でないデータベース エントリを返します。	true

関係フィルター条件の例

{
  "filter": {
    "property": "✔️ Task List",
    "relation": {
      "contains": "0c1f7cb280904f18924ed92965055e32"
    }
  }
}

リッチテキスト

フィールド	タイプ	説明	例の値
contains	string	テキスト プロパティ値を比較するstring。 指定されたstring を含む text プロパティ値を持つデータベース エントリを返します。	"Moved to Q2"
does_not_contain	string	テキスト プロパティ値を比較するstring。 指定されたstring を含まない text プロパティ値を持つデータベース エントリを返します。	"Moved to Q2"
does_not_equal	string	テキスト プロパティ値を比較するstring。 指定されたstring と一致しない text プロパティ値を持つデータベース エントリを返します。	"Moved to Q2"
ends_with	string	テキスト プロパティ値を比較するstring。 指定された stringで終わるテキスト プロパティ値を持つデータベース エントリを返します。	"Q2"
equals	string	テキスト プロパティ値を比較するstring。 指定されたstring に一致するテキスト プロパティ値を持つデータベース エントリを返します。	"Moved to Q2"
is_empty	true	text プロパティ値にデータが含まれていないかどうか。 テキスト プロパティ値が空のデータベース エントリを返します。	true
is_not_empty	true	text プロパティ値にデータが含まれているかどうか。 データを含む text プロパティ値を持つデータベース エントリを返します。	true
starts_with	string	テキスト プロパティ値を比較するstring。 指定されたstring で始まるテキスト プロパティ値を持つデータベース エントリを返します。	「引っ越しました」

リッチ テキスト フィルター条件の例

{
  "filter": {
    "property": "Description",
    "rich_text": {
      "contains": "cross-team"
    }
  }
}

ロールアップ

ロールアップ データベース プロパティは、配列、日付、または数値に評価できます。ロールアップ プロパティのフィルター条件には、rollupキーと、計算値の型に応じた対応するオブジェクト値が含まれています。

arrayロールアップ値のフィルター条件

フィールド	タイプ	説明	例の値
any	object	各ロールアップ プロパティ値を比較する値。他のタイプのフィルター条件にすることができます。 ロールアップ プロパティ値が指定された条件に一致するデータベース エントリを返します。	"rich_text": { "contains": "Take Fig on a walk" }
every	object	各ロールアップ プロパティ値を比較する値。他のタイプのフィルター条件にすることができます。 すべてのロールアップ プロパティ値が指定された条件に一致するデータベース エントリを返します。	"rich_text": { "contains": "Take Fig on a walk" }
none	object	各ロールアップ プロパティ値を比較する値。他のタイプのフィルター条件にすることができます。 指定された条件に一致するロールアップ プロパティ値がないデータベース エントリを返します。	"rich_text": { "contains": "Take Fig on a walk" }

配列ロールアップ フィルター条件の例

{
  "filter": {
    "property": "Related tasks",
    "rollup": {
      "any": {
        "rich_text": {
          "contains": "Migrate database"
        }
      }
    }
  }
}

dateロールアップ値のフィルター条件

ロールアップ値は、Notion UI でプロパティに対して「最早日」、「最新日」、または「日付範囲」の計算が選択されている場合にのみ、dateとして保存されます。

フィールド	タイプ	説明	例の値
date	object	ロールアップ値を比較する日付フィルター条件。 ロールアップ値が指定された条件に一致するデータベース エントリを返します。	日付フィルター条件を参照してください。

日付ロールアップ フィルター条件の例

{
  "filter": {
    "property": "Parent project due date",
    "rollup": {
      "date": {
        "on_or_before": "2023-02-08"
      }
    }
  }
}

numberロールアップ値のフィルター条件

フィールド	タイプ	説明	例の値
number	object	ロールアップ値を比較する数値フィルター条件。 ロールアップ値が指定された条件に一致するデータベース エントリを返します。	番号フィルター条件を参照してください。

数値ロールアップ フィルター条件の例

{
  "filter": {
    "property": "Total estimated working days",
    "rollup": {
      "number": {
        "does_not_equal": 42
      }
    }
  }
}

選択

フィールド	タイプ	説明	例の値
equals	string	select プロパティの値を比較するstring 。 select プロパティ値が指定された文字列と一致するデータベース エントリを返します。	"This week"
does_not_equal	string	select プロパティの値を比較するstring 。 select プロパティの値が指定されたstring と一致しないデータベース エントリを返します。	"Backlog"
is_empty	true	select プロパティ値にデータが含まれていないかどうか。 select プロパティの値が空のデータベース エントリを返します。	true
is_not_empty	true	select プロパティ値にデータが含まれているかどうか。 select プロパティの値が空でないデータベース エントリを返します。	true

フィルタ条件の選択例

{
  "filter": {
    "property": "Frontend framework",
    "select": {
      "equals": "React"
    }
  }
}

スターテス

フィールド	タイプ	説明	例の値
等しい	String	status プロパティの値を比較する文字列。 status プロパティ値が指定された文字列と一致するデータベース エントリを返します。	"This Week"
等しくない	String	status プロパティの値を比較する文字列。 status プロパティの値が指定された文字列と一致しないデータベース エントリを返します。	"Bcaclog"
is_empty	true	status プロパティ値にデータが含まれていないかどうか。 status プロパティ値が空のデータベース エントリを返します。	True
is_not_empty	True	status プロパティ値にデータが含まれているかどうか。 status プロパティの値が空でないデータベース エントリを返します。	True

ステータス フィルタ条件の例

{
  "filter": {
    "property": "Project status",
    "status": {
      "equals": "Not started"
    }
  }
}

タイムスタンプ

タイムスタンプ フィルター条件を使用して、created_timeまたはlast_edited_time の値に基づいて結果をフィルター処理します。

フィールド	タイプ	説明	例の値
timestamp	created_time last_edited_time	フィルターとして使用するタイムスタンプのタイプを表す定数文字列。	"created_time"
created_time last_edited_time	object	指定されたタイムスタンプをフィルタリングするために使用される日付フィルター条件。	日付フィルター条件を参照してください。

created_time のタイムスタンプ フィルタ条件の例

{
  "filter": {
    "timestamp": "created_time",
    "created_time": {
      "on_or_before": "2022-10-13"
    }
  }
}

🚧

timestampフィルタ条件にプロパティ名は必要ありません。エラーを指定すると、API はエラーをスローします。

複合フィルター条件

複合フィルター条件を使用して、複数の条件に基づいてデータベース クエリの結果を制限できます。これは、Notion UI でのフィルター チェーンを模倣します。

Notion UI のフィルタ チェーンの例

上記の Notion UI のフィルターは、API を介した次の複合フィルター条件と同等です。

JSON

{
  "and": [
    {
      "property": "Done",
      "checkbox": {
        "equals": true
      }
    }, 
    {
      "or": [
        {
          "property": "Tags",
          "contains": "A"
        },
        {
          "property": "Tags",
          "contains": "B"
        }
      ]
    }
  ]
}

複合フィルター条件には、フィルター オブジェクトまたはネストされた複合フィルター オブジェクトの配列である値を持つorキーが含まれます。ネスティングは最大 2 レベルの深さまでサポートされています。and``or

フィールド	タイプ	説明	例の値
and	array	フィルターオブジェクトまたは複合フィルター条件の配列。指定されたすべてのフィルタ条件 に一致するデータベース エントリを返します。	以下の例を参照してください。
or	Array	フィルターオブジェクトまたは複合フィルター条件の配列。指定されたフィルタ条件のいずれか に 一致するデータベース エントリを返します	以下の例を参照してください。

複合フィルター条件の例

チェックボックスと数値プロパティ値の複合フィルター条件の例

{
  "filter": {
    "and": [
      {
        "property": "Complete",
        "checkbox": {
          "equals": true
        }
      },
      {
        "property": "Working days",
        "number": {
          "greater_than": 10
        }
      }
    ]
  }
}

ネストされたフィルター条件の例

{
  "filter": {
    "or": [
      {
        "property": "Description",
        "rich_text": {
          "contains": "2023"
        }
      },
      {
        "and": [
          {
            "property": "Department",
            "select": {
              "equals": "Engineering"
            }
          },
          {
            "property": "Priority goal",
            "checkbox": {
              "equals": true
            }
          }
        ]
      }
    ]
  }
}