Skip to content

Databases API

Databases are containers that hold multiple data sources in Notion API 2025-09-03.

Overview

The Databases API provides methods to:

  • Retrieve database metadata and data sources list
  • Create new databases with initial data source
  • Update database-level properties (title, icon, cover)

For querying data or managing schema, use the Data Sources API.

Legacy Note: databases.query

As of Notion-Version 2025-09-03, databases.query is considered legacy and is not available when the client uses the latest version header. Attempting to call it will emit a warning and raise an error. Please use dataSources.query instead.

If you must call the legacy endpoint for compatibility, explicitly set an older version when constructing the client (not recommended):

client = NotionAsyncClient(
    auth="secret_xxx",
    options={"notion_version": "2022-06-28"}
)
# Then:
# await client.databases.query({...})

Methods

retrieve

Retrieve a database with its metadata and data sources list.

async def retrieve(
    params: RetrieveDatabaseParameters,
    *,
    auth: AuthParam | None = None
) -> NotionDatabase

Parameters:

  • params.database_id (str): Database ID
  • auth (optional): Override authentication token

Returns: NotionDatabase object containing:

  • Database metadata (title, icon, cover, etc.)
  • data_sources array with IDs and names

Example:

from notion_py_client import NotionAsyncClient

async with NotionAsyncClient(auth="secret_xxx") as client:
    db = await client.databases.retrieve(
        {"database_id": "db_abc123"}
    )

    print(f"Title: {db.title}")
    print(f"Created: {db.created_time}")

    # List data sources
    for ds in db.data_sources:
        print(f"- {ds['name']} (ID: {ds['id']})")

Tip: Extract a database ID from a URL

from notion_py_client.utils import extract_database_id

db_id = extract_database_id(
    "https://notion.so/workspace/DB-abc123def456789012345678901234ab?v=viewid"
)
db = await client.databases.retrieve({"database_id": db_id})

create

Create a new database with an initial data source.

async def create(
    params: CreateDatabaseParameters,
    *,
    auth: AuthParam | None = None
) -> NotionDatabase

Parameters:

  • params.parent: Parent page or workspace
  • params.title: Database title (RichText array)
  • params.initial_data_source: Initial data source configuration
  • properties: Schema definition
  • name (optional): Data source name

Returns: Created NotionDatabase

Example:

async with NotionAsyncClient(auth="secret_xxx") as client:
    db = await client.databases.create({
        "parent": {
            "type": "page_id",
            "page_id": "parent_page_id"
        },
        "title": [
            {"type": "text", "text": {"content": "Project Tracker"}}
        ],
        "initial_data_source": {
            "name": "Main Data",
            "properties": {
                "Name": {
                    "title": {}
                },
                "Status": {
                    "select": {
                        "options": [
                            {"name": "Not Started", "color": "gray"},
                            {"name": "In Progress", "color": "blue"},
                            {"name": "Done", "color": "green"}
                        ]
                    }
                },
                "Due Date": {
                    "date": {}
                }
            }
        }
    })

    print(f"Created database: {db.id}")

update

Update database-level properties.

async def update(
    params: UpdateDatabaseParameters,
    *,
    auth: AuthParam | None = None
) -> NotionDatabase

Parameters:

  • params.database_id (str): Database ID to update
  • params.title (optional): New title
  • params.icon (optional): New icon
  • params.cover (optional): New cover image
  • params.is_inline (optional): Inline display setting
  • params.parent (optional): New parent

Note: To update data source properties, use dataSources.update() instead.

Returns: Updated NotionDatabase

Example:

async with NotionAsyncClient(auth="secret_xxx") as client:
    db = await client.databases.update({
        "database_id": "db_abc123",
        "title": [
            {"type": "text", "text": {"content": "Updated Title"}}
        ],
        "icon": {
            "type": "emoji",
            "emoji": "📊"
        }
    })

    print(f"Updated: {db.title}")

Common Patterns

Get Database Schema

To access the schema (properties), retrieve the data source:

async with NotionAsyncClient(auth="secret_xxx") as client:
    # 1. Get database and data sources
    db = await client.databases.retrieve(
        {"database_id": "db_abc123"}
    )

    # 2. Get schema from first data source
    if db.data_sources:
        ds = await client.dataSources.retrieve(
            data_source_id=db.data_sources[0]["id"]
        )

        # Access properties
        for name, config in ds.properties.items():
            print(f"{name}: {config.type}")

List All Data Sources

async with NotionAsyncClient(auth="secret_xxx") as client:
    db = await client.databases.retrieve(
        {"database_id": "db_abc123"}
    )

    # Retrieve full details for each data source
    for ds_ref in db.data_sources:
        ds = await client.dataSources.retrieve(
            data_source_id=ds_ref["id"]
        )
        print(f"Data Source: {ds_ref['name']}")
        print(f"  Properties: {list(ds.properties.keys())}")

Type Reference

from notion_py_client.responses.database import NotionDatabase

# Database object structure
database: NotionDatabase = {
    "object": "database",
    "id": "db_abc123",
    "title": [...],
    "icon": {...},
    "cover": {...},
    "created_time": "2025-01-01T00:00:00.000Z",
    "created_by": {...},
    "last_edited_time": "2025-01-02T00:00:00.000Z",
    "last_edited_by": {...},
    "parent": {...},
    "archived": false,
    "is_inline": false,
    "public_url": "https://...",
    "data_sources": [
        {"id": "ds_abc123", "name": "Main Data"},
        {"id": "ds_def456", "name": "Archive"}
    ]
}