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
, 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. |
|
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 |