A filter is a single condition used to specify and limit the entries returned from a database query. Database queries can be filtered by page property values. The API supports filtering by the following property types: rich_text, phone_number, number, checkbox, select, multi-select, date, people, files, relation, status, and formula. You may also filter a database by created_time or last_edited_time, even if these aren't present as properties on the database.
Property filter object
Each database property filter object must contain a property key and a key corresponding with the type of the database property identified by property. The value is an object containing a type-specific filter condition.
Property | Type | Description |
|---|---|---|
|
| The name or ID of the property to filter on. |
Here is an example of a filter on a database property of type text.
{
"filter": {
"property": "Landmark",
"rich_text": {
"contains": "Bridge"
}
}
}
Timestamp filter object
A timestamp filter object must contain a timestamp key corresponding to the type of timestamp and a key matching that timestamp type which contains a date filter condition.
Property | Type | Description |
|---|---|---|
|
| The type of timestamp to filter on. Possible values are: |
Here's an example of a filter on the created timestamp:
{
"filter": {
"timestamp": "created_time",
"created_time": {
"past_week": {}
}
}
}
Compound filter object
A compound filter object combines several filter objects together using a logical operator and or or. A compound filter can even be combined within a compound filter, but only up to two nesting levels deep.
The compound filter object contains one of the following keys:
Property | Type | Description |
|---|---|---|
| array of filter objects or compound filter objects. | Returns pages when any of the filters inside the provided array match. |
| array of filter objects or compound filter objects. | Returns pages when all of the filters inside the provided array match. |
Here is an example of a compound filter that combines two filter objects. The result of this filter will be one that satisfies the checkbox filter and the number filter.
{
"filter": {
"and": [
{
"property": "Seen",
"checkbox": {
"equals": false
}
},
{
"property": "Yearly visitor count",
"number": {
"greater_than": 1000000
}
}
]
}
}
Here is example of a compound filter that combines a single filter object with another compound filter object:
{
"filter": {
"or": [
{
"property": "Description",
"rich_text": {
"contains": "fish"
}
},
{
"and": [
{
"property": "Food group",
"select": {
"equals": "🥦Vegetable"
}
},
{
"property": "Is protein rich?",
"checkbox": {
"equals": true
}
}
]
}
]
}
}
Type-specific filter conditions
Text filter condition
A text filter condition can be applied to database properties of types "title", "rich_text", "url", "email", and "phone_number".
Property | Type | Description | Example value |
|---|---|---|---|
|
| Only return pages where the page property value matches the provided value exactly. |
|
|
| Only return pages where the page property value does not match the provided value exactly. |
|
|
| Only return pages where the page property value contains the provided value. |
|
|
| Only return pages where the page property value does not contain the provided value. |
|
|
| Only return pages where the page property value starts with the provided value. |
|
|
| Only return pages where the page property value ends with the provided value. |
|
|
| Only return pages where the page property value is empty. |
|
|
| Only return pages where the page property value is present. |
|
Number filter condition
A number filter condition can be applied to database properties of type "number".
Property | Type | Description | Example value |
|---|---|---|---|
|
| Only return pages where the page property value matches the provided value exactly. |
|
|
| Only return pages where the page property value does not match the provided value exactly. |
|
|
| Only return pages where the page property value is greater than the provided value. |
|
|
| Only return pages where the page property value is less than the provided value. |
|
|
| Only return pages where the page property value is greater than or equal to the provided value. |
|
|
| Only return pages where the page property value is less than or equal to the provided value. |
|
|
| Only return pages where the page property value is empty. |
|
|
| Only return pages where the page property value is present. |
|
Checkbox filter condition
A checkbox filter condition can be applied to database properties of type "checkbox".
Property | Type | Description | Example value |
|---|---|---|---|
|
| Only return pages where the page property value matches the provided value exactly. |
|
|
| Only return pages where the page property value does not match the provided value exactly. |
|
Select filter condition
A select filter condition can be applied to database properties of type "select".
Property | Type | Description | Example value |
|---|---|---|---|
|
| Only return pages where the page property value matches the provided value exactly. |
|
|
| Only return pages where the page property value does not match the provided value exactly. |
|
|
| Only return pages where the page property value is empty. |
|
|
| Only return pages where the page property value is present. |
|
Multi-select filter condition
A multi-select filter condition can be applied to database properties of type "multi_select".
Property | Type | Description | Example value |
|---|---|---|---|
|
| Only return pages where the page property value contains the provided value. |
|
|
| Only return pages where the page property value does not contain the provided value. |
|
|
| Only return pages where the page property value is empty. |
|
|
| Only return pages where the page property value is present. |
|
Status filter condition
A status filter condition can be applied to database properties of type "status".
Property | Type | Description | Example value |
|---|---|---|---|
|
| Only return pages where the page property value matches the provided value exactly. |
|
|
| Only return pages where the page property value does not match the provided value exactly. |
|
|
| Only return pages where the page property value is empty. |
|
|
| Only return pages where the page property value is present. |
|
Date filter condition
A date filter condition can be applied to database properties of types "date", "created_time", and "last_edited_time".
Property | Type | Description | Example value |
|---|---|---|---|
| string (ISO 8601 date) | Only return pages where the page property value matches the provided date exactly. If a date is provided, the comparison is done against the start and end of the UTC date. If a date with a time is provided, the comparison is done with millisecond precision. Note that if no timezone is provided, the default is UTC. |
|
| string (ISO 8601 date) | Only return pages where the page property value is before the provided date. If a date with a time is provided, the comparison is done with millisecond precision. Note that if no timezone is provided, the default is UTC. |
|
| string (ISO 8601 date) | Only return pages where the page property value is after the provided date. If a date with a time is provided, the comparison is done with millisecond precision. Note that if no timezone is provided, the default is UTC. |
|
| string (ISO 8601 date) | Only return pages where the page property value is on or before the provided date. If a date with a time is provided, the comparison is done with millisecond precision. Note that if no timezone is provided, the default is UTC. |
|
|
| Only return pages where the page property value is empty. |
|
|
| Only return pages where the page property value is present. |
|
| string (ISO 8601 date) | Only return pages where the page property value is on or after the provided date. If a date with a time is provided, the comparison is done with millisecond precision. Note that if no timezone is provided, the default is UTC. |
|
|
| Only return pages where the page property value is within the past week. |
|
|
| Only return pages where the page property value is within the past month. |
|
|
| Only return pages where the page property value is within the past year. |
|
|
| Only return pages where the page property value is within the next week. |
|
|
| Only return pages where the page property value is within the next month. |
|
|
| Only return pages where the page property value is within the next year. |
|
People filter condition
A people filter condition can be applied to database properties of types "people", "created_by", and "last_edited_by".
Property | Type | Description | Example value |
|---|---|---|---|
|
| Only return pages where the page property value contains the provided value. |
|
|
| Only return pages where the page property value does not contain the provided value. |
|
|
| Only return pages where the page property value is empty. |
|
|
| Only return pages where the page property value is present. |
|
Files filter condition
A files filter condition can be applied to database properties of type "files".
Property | Type | Description | Example value |
|---|---|---|---|
|
| Only return pages where the page property value is empty. |
|
|
| Only return pages where the page property value is present. |
|
Relation filter condition
A relation filter condition can be applied to database properties of type "relation".
Property | Type | Description | Example value |
|---|---|---|---|
|
| Only return pages where the page property value contains the provided value. |
|
|
| Only return pages where the page property value does not contain the provided value. |
|
|
| Only return pages where the page property value is empty. |
|
|
| Only return pages where the page property value is present. |
|
Rollup filter condition
A rollup filter condition can be applied to database properties of type "rollup". Rollups which evaluate to arrays accept a filter with an any, every, or none condition; rollups which evaluate to numbers accept a filter with a number condition; and rollups which evaluate to dates accept a filter with a date condition.
Rollups which evaluate to arrays accept any kind of property in
Property | Type | Description | Example value |
|---|---|---|---|
|
| For a rollup property which evaluates to an array, return the pages where any item in that rollup fits this criterion. The criterion itself can be any other property type. |
|
|
| For a rollup property which evaluates to an array, return the pages where every item in that rollup fits this criterion. The criterion itself can be any other property type. |
|
|
| For a rollup property which evaluates to an array, return the pages where no item in that rollup fits this criterion. The criterion itself can be any other property type. |
|
|
| For a rollup property which evaluates to an number, return the pages where the number fits this criterion. |
|
|
| For a rollup property which evaluates to an date, return the pages where the date fits this criterion. |
|
Formula filter condition
A formula filter condition can be applied to database properties of type "formula".
Property | Type | Description |
|---|---|---|
|
| Only return pages where the result type of the page property formula is |
|
| Only return pages where the result type of the page property formula is |
|
| Only return pages where the result type of the page property formula is |
|
| Only return pages where the result type of the page property formula is |