Skip to content

Query

query

Provides an interactive query builder for Notion databases.

NCEndpointCall: TypeAlias = Callable[..., Any | Awaitable[Any]] module-attribute

T = TypeVar('T', bound=Page | Database) module-attribute

CheckboxCondition

Represents checkbox criteria in Notion.

does_not_equal: bool | None = None class-attribute instance-attribute

equals: bool | None = None class-attribute instance-attribute

CompoundFilter

Represents a compound filter in Notion.

and_: list[SerializeAsAny[QueryFilter]] | None = Field(None, alias='and') class-attribute instance-attribute

model_config = ConfigDict(populate_by_name=True) class-attribute instance-attribute

or_: list[SerializeAsAny[QueryFilter]] | None = Field(None, alias='or') class-attribute instance-attribute

Condition

Base class for all conditions in Notion.

CreatedTimeFilter

Represents a created_time filter in Notion.

created_time: DateCondition instance-attribute

timestamp: TimestampKind = TimestampKind.CREATED_TIME class-attribute instance-attribute

DBQuery

Query object in Notion for querying a database

sorts: list[DBSort] | None = None class-attribute instance-attribute

DBQueryBuilder(endpoint: NCEndpointCall, db_id: str)

Query builder to query a database.

Notion API: https://developers.notion.com/reference/post-search

query: DBQuery instance-attribute

execute(**nc_params: int | str) -> Iterator[Page]

filter(condition: QueryFilter) -> DBQueryBuilder

Add the given filter to the query.

sort(sort_orders: DBSort | list[DBSort]) -> DBQueryBuilder

Add the given sort elements to the query.

DBSort

Sort instruction when querying a database

direction: SortDirection instance-attribute

property: str instance-attribute

DateCondition

Represents date criteria in Notion.

after: date | datetime | None = None class-attribute instance-attribute

before: date | datetime | None = None class-attribute instance-attribute

equals: date | datetime | None = None class-attribute instance-attribute

is_empty: bool | None = None class-attribute instance-attribute

is_not_empty: bool | None = None class-attribute instance-attribute

next_month: EmptyObject | None = None class-attribute instance-attribute

next_week: EmptyObject | None = None class-attribute instance-attribute

next_year: EmptyObject | None = None class-attribute instance-attribute

on_or_after: date | datetime | None = None class-attribute instance-attribute

on_or_before: date | datetime | None = None class-attribute instance-attribute

past_month: EmptyObject | None = None class-attribute instance-attribute

past_week: EmptyObject | None = None class-attribute instance-attribute

past_year: EmptyObject | None = None class-attribute instance-attribute

this_week: EmptyObject | None = None class-attribute instance-attribute

EmptyObject

FilesCondition

Represents files criteria in Notion.

is_empty: bool | None = None class-attribute instance-attribute

is_not_empty: bool | None = None class-attribute instance-attribute

FormulaCondition

Represents formula criteria in Notion.

checkbox: CheckboxCondition | None = None class-attribute instance-attribute

date: DateCondition | None = None class-attribute instance-attribute

number: NumberCondition | None = None class-attribute instance-attribute

string: TextCondition | None = None class-attribute instance-attribute

IdCondition

Represents ID criteria in Notion.

does_not_equal: float | int | None = None class-attribute instance-attribute

equals: float | int | None = None class-attribute instance-attribute

greater_than: float | int | None = None class-attribute instance-attribute

greater_than_or_equal_to: float | int | None = None class-attribute instance-attribute

less_than: float | int | None = None class-attribute instance-attribute

less_than_or_equal_to: float | int | None = None class-attribute instance-attribute

LastEditedTimeFilter

Represents a last_edited_time filter in Notion.

last_edited_time: DateCondition instance-attribute

timestamp: TimestampKind = TimestampKind.LAST_EDITED_TIME class-attribute instance-attribute

MultiSelectCondition

Represents a multi_select criteria in Notion.

contains: str | None = None class-attribute instance-attribute

does_not_contain: str | None = None class-attribute instance-attribute

is_empty: bool | None = None class-attribute instance-attribute

is_not_empty: bool | None = None class-attribute instance-attribute

NumberCondition

Represents number criteria in Notion.

does_not_equal: float | int | None = None class-attribute instance-attribute

equals: float | int | None = None class-attribute instance-attribute

greater_than: float | int | None = None class-attribute instance-attribute

greater_than_or_equal_to: float | int | None = None class-attribute instance-attribute

is_empty: bool | None = None class-attribute instance-attribute

is_not_empty: bool | None = None class-attribute instance-attribute

less_than: float | int | None = None class-attribute instance-attribute

less_than_or_equal_to: float | int | None = None class-attribute instance-attribute

PeopleCondition

Represents people criteria in Notion.

contains: UUID | None = None class-attribute instance-attribute

does_not_contain: UUID | None = None class-attribute instance-attribute

is_empty: bool | None = None class-attribute instance-attribute

is_not_empty: bool | None = None class-attribute instance-attribute

PropertyFilter

Represents a database property filter in Notion.

property: str instance-attribute

rollup: RollupCondition | None = None class-attribute instance-attribute

Query

Abstract query object in Notion for searching pages/databases and querying databases

filter: SerializeAsAny[QueryFilter] | None = None class-attribute instance-attribute

page_size: int = MAX_PAGE_SIZE class-attribute instance-attribute

start_cursor: UUID | None = None class-attribute instance-attribute

valid_page_size(value: int) -> int classmethod

Validate that the given page size meets the Notion API requirements

QueryBuilder(endpoint: NCEndpointCall, query: Query, params: Mapping[str, str | None])

General query builder for the Notion search & database query API

endpoint: NCEndpointCall = endpoint instance-attribute

params: dict[str, str] = {k: vfor (k, v) in params.items() if v is not None} instance-attribute

query: Query = query instance-attribute

execute(**nc_params: int | str) -> Iterator[T]

Execute the current query and return an iterator for the results.

QueryFilter

Base class for query filters.

RelationCondition

Represents relation criteria in Notion.

contains: UUID | None = None class-attribute instance-attribute

does_not_contain: UUID | None = None class-attribute instance-attribute

is_empty: bool | None = None class-attribute instance-attribute

is_not_empty: bool | None = None class-attribute instance-attribute

RollupArrayCondition

Represents a rollup array filter in Notion.

checkbox: CheckboxCondition | None = None class-attribute instance-attribute

date: DateCondition | None = None class-attribute instance-attribute

files: FilesCondition | None = None class-attribute instance-attribute

formula: FormulaCondition | None = None class-attribute instance-attribute

multi_select: MultiSelectCondition | None = None class-attribute instance-attribute

number: NumberCondition | None = None class-attribute instance-attribute

people: PeopleCondition | None = None class-attribute instance-attribute

phone_number: TextCondition | None = None class-attribute instance-attribute

relation: RelationCondition | None = None class-attribute instance-attribute

rich_text: TextCondition | None = None class-attribute instance-attribute

select: SelectCondition | None = None class-attribute instance-attribute

unique_id: IdCondition | None = None class-attribute instance-attribute

RollupCondition

Represents rollup criteria in Notion.

any: RollupArrayCondition | None = None class-attribute instance-attribute

date: DateCondition | None = None class-attribute instance-attribute

every: RollupArrayCondition | None = None class-attribute instance-attribute

none: RollupArrayCondition | None = None class-attribute instance-attribute

number: NumberCondition | None = None class-attribute instance-attribute

SearchFilter

Represents a search property filter in Notion.

property: str instance-attribute

value: str instance-attribute

SearchQuery

Query object in Notion for searching pages & databases

sort: SearchSort | None = None class-attribute instance-attribute

SearchQueryBuilder(endpoint: NCEndpointCall, text: str | None = None)

Search query builder to search for pages and databases

By default and not changed by sort, then the most recently edited results are returned first.

Notion API: https://developers.notion.com/reference/post-search

query: SearchQuery instance-attribute

execute(**nc_params: int | str) -> Iterator[T]

filter(*, page_only: bool = False, db_only: bool = False) -> SearchQueryBuilder

Filter for pages or databases only

sort(*, ascending: bool) -> SearchQueryBuilder

Add the given sort elements to the query.

SearchSort

Sort instruction when searching for pages and databases

direction: SortDirection instance-attribute

timestamp: Literal[TimestampKind.LAST_EDITED_TIME] instance-attribute

SelectCondition

Represents select criteria in Notion.

does_not_equal: str | None = None class-attribute instance-attribute

equals: str | None = None class-attribute instance-attribute

is_empty: bool | None = None class-attribute instance-attribute

is_not_empty: bool | None = None class-attribute instance-attribute

TextCondition

Represents text criteria in Notion.

contains: str | None = None class-attribute instance-attribute

does_not_contain: str | None = None class-attribute instance-attribute

does_not_equal: str | None = None class-attribute instance-attribute

ends_with: str | None = None class-attribute instance-attribute

equals: str | None = None class-attribute instance-attribute

is_empty: bool | None = None class-attribute instance-attribute

is_not_empty: bool | None = None class-attribute instance-attribute

starts_with: str | None = None class-attribute instance-attribute

TimestampFilter

Represents a timestamp filter in Notion.

timestamp: TimestampKind instance-attribute