Database
database ¶
Functionality for working with Notion databases and data sources.
In API version 2025-09-03+: - DataSource: Contains schema (properties) and pages (formerly 'database') - Database: Container that can hold multiple data sources (new concept)
DC_co = TypeVar('DC_co', bound=(obj_blocks.Database | obj_blocks.DataSource), covariant=True) module-attribute ¶
DataContainer(*args: Any, **kwargs: Any) ¶
Base class for presentation-related functionality in data sources and databases.
cover: AnyFile | None property ¶
Return the cover of this data source as file.
description: Text | None property writable ¶
Return the description of this data source as rich text.
icon: AnyFile | Emoji | CustomEmoji | BuiltInIcon | None property ¶
Return the icon of this data source as file or emoji.
title: str | Text | None property writable ¶
Return the title of this data source as rich text.
DataSource(*args: Any, **kwargs: Any) ¶
A Notion data source.
A data source contains the schema (properties) and pages. This object always represents an original data source, not a linked one.
API reference: https://developers.notion.com/reference/data-source
database_id: UUID property ¶
Return the id of the database container that holds this data source.
The container is transparent in the hierarchy (parent/ancestors skip it), but it is what a mention or the public URL of this data source actually points to, so its id is exposed here. Use session.get_db(ds.database_id) to retrieve the container Database object itself.
db_parent: NotionEntity | WorkspaceType | None property ¶
Alias of parent: the parent of this data source's (transparent) database container.
description: Text | None property writable ¶
Return the description of this data source as rich text.
is_ds: bool property ¶
Return whether the object is a data source.
is_empty: bool property ¶
Return whether the data source is empty.
is_inline: bool property writable ¶
Return whether the data source's database is displayed inline on its parent page.
is_locked: bool property writable ¶
Return whether this data source's database is locked for editing.
parent: NotionEntity | WorkspaceType | None property ¶
Return the parent of this data source.
The 2025-09-03 API nests every data source inside a database container. That container is transparent in the high-level API: a data source presents as a child of the page (or workspace) that holds its database. The parent is therefore resolved from database_parent (the database's parent) rather than the immediate parent ref (the container database).
query: Query property ¶
Return a Query object to build and execute a data source query.
schema: type[Schema] property writable ¶
Schema of the data source.
url: str property ¶
Return the public URL of this data source's database.
__bool__() -> bool ¶
Overwrite default behaviour.
__len__() -> int ¶
Return the number of pages in this data source.
__repr__() -> str ¶
__str__() -> str ¶
create_page(**kwargs: Any) -> Page ¶
Create a page with properties according to the schema within the corresponding data source.
delete() -> Self ¶
Delete this data source.
get_all_pages() -> View ¶
Retrieve all pages and return a view.
move(database: Database) -> Self ¶
Move this data source to a different parent database.
Reassigns the data source from its current container database to database. Cached children of the old and new parent are invalidated so the hierarchy reflects the move.
reload(*, rebind_schema: bool = True) -> Self ¶
Reload this data source.
If rebind_schema is True, the schema will be rebound to the current data source. Otherwise, the schema will set to the reflected schema of the current data source.
restore() -> Self ¶
Restore this data source.
to_markdown() -> str ¶
Return the reference to this data source as Markdown.
Database(*args: Any, **kwargs: Any) ¶
A Notion database - a collection that can contain multiple data sources.
API reference: https://developers.notion.com/docs/working-with-databases
data_sources: SList[DataSource] property ¶
Return all data sources in this database.
Trashed data sources are excluded: Notion keeps them in the container's raw list even after they are moved to the trash, so they are filtered out here (use restore_ds() to bring one back).
is_db: bool property ¶
Check if this is a database (always True for Database objects).
is_inline: bool property writable ¶
Return whether the database is inline.
is_locked: bool property writable ¶
Return whether the database is locked for editing.
is_wiki: bool property ¶
Return whether the database is a wiki.
public_url: str | None property ¶
Return the public URL of this database, if available.
query: Query property ¶
Return a Query object of the database if it has a single data source.
url: str property ¶
Return the public URL of this database.
__eq__(other: object) -> bool ¶
Compare Database objects.
__hash__() -> int ¶
Hash the Database object.
__repr__() -> str ¶
__str__() -> str ¶
create_ds(*, schema: type[Schema] | None = None, title: str | None = None) -> DataSource ¶
Add a new data source to this database.
In case a title and a schema are provided, the title overrides the schema's db_title. If no schema is given, a default single-title schema is used. Use delete_ds() to remove one again.
delete() -> Self ¶
Delete (move to trash) this database and all of its data sources.
delete_ds(ds: DataSource) -> DataSource ¶
Remove (move to trash) a single data source from this database.
The data source's siblings and the database container itself are left untouched. To delete the whole database (and all its data sources), use delete(). Restore a removed data source with restore_ds().
get_all_pages() -> SList[View] ¶
Retrieve all pages of all databases as a list of views.
reload() -> Self ¶
Reload this database from Notion, refreshing its data sources and metadata.
restore() -> Self ¶
Restore this database from trash.
restore_ds(ds: DataSource) -> DataSource ¶
Restore a data source previously removed from this database with delete_ds().
to_markdown() -> str ¶
Return the reference to this database as Markdown.