Skip to content

Query

query

Provides an interactive query builder for Notion databases.

logger = logging.getLogger(__name__) 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[QueryFilter] | None = Field(None, alias='and') class-attribute instance-attribute

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

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

CreatedTimeFilter

Represents a created_time filter in Notion.

created_time: DateCondition instance-attribute

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

build(value) classmethod

Create a new CreatedTimeFilter using the given constraint.

DBQuery

Query object in Notion for querying a database

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

DBQueryBuilder(endpoint, db_id: str)

Query builder to query a database.

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

query: DBQuery = DBQuery() instance-attribute

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: Any | None = None class-attribute instance-attribute

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

next_year: Any | 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: Any | None = None class-attribute instance-attribute

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

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

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

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

build(value) classmethod

Create a new LastEditedTimeFilter using the given constraint.

MultiSelectCondition

Represents a multi_select criteria in Notion.

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

does_not_contains: 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.

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

property: str 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

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: NCEndpoint, **params: str | None)

General query builder for the Notion search & database query API

endpoint: NCEndpoint = endpoint instance-attribute

params: dict[str, str] = {param: valuefor (param, value) in params.items() if value is not None} instance-attribute

query: Query instance-attribute

execute()

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

first()

Execute the current query and return the first result only.

limit(count: int)

Limit the number of results to the given count.

start_at(cursor_id: UUID)

Set the start cursor to a specific page ID.

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

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, 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 = SearchQuery() instance-attribute

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

SortDirection

Sort direction options.

ASCENDING = 'ascending' class-attribute instance-attribute

DESCENDING = 'descending' 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

TimestampKind

Possible timestamp types.

CREATED_TIME = 'created_time' class-attribute instance-attribute

LAST_EDITED_TIME = 'last_edited_time' class-attribute instance-attribute