# Databases, Data Sources, and Pages

Use this reference for database containers, data source schemas, page creation, and schema updates.

## Core Mental Model

Notion API version `2025-09-03` separates databases and data sources:

```text
parent page
  database container
    data source/table with schema
      row pages
```

Use `get_database(database_id)` to retrieve the container and its `data_sources`. Use `get_data_source(data_source_id)` to retrieve the actual table schema.

## Retrieve a Database and Schema

```python
database = helper.get_database(database_id)
data_source_id = database["data_sources"][0]["id"]
schema = helper.get_data_source(data_source_id)
properties = schema["properties"]
```

## Search

```python
pages = helper.notion_search_db("roadmap", filter_object_type="page")
data_sources = helper.notion_search_db("tasks", filter_object_type="data_source")
```

`filter_object_type` must be `"page"` or `"data_source"`.

## Create a Database

Schema properties use empty objects or type configuration:

```python
properties = {
    "Name": {"title": {}},
    "Status": {
        "select": {
            "options": [
                {"name": "Not Started", "color": "red"},
                {"name": "In Progress", "color": "yellow"},
                {"name": "Done", "color": "green"},
            ]
        }
    },
    "Due": {"date": {}},
    "Notes": {"rich_text": {}},
}

database = helper.create_database(
    parent_page_id=parent_page_id,
    database_title="Project Tasks",
    initial_data_source_properties=properties,
    initial_data_source_title="Tasks",
)
data_source_id = database["initial_data_source"]["id"]
```

## Create a Page in a Data Source

Page property values contain content, not schema definitions:

```python
page = helper.new_page_to_data_source(
    data_source_id,
    {
        "Name": {"title": [{"text": {"content": "Draft launch notes"}}]},
        "Status": {"select": {"name": "In Progress"}},
        "Due": {"date": {"start": "2026-08-20"}},
        "Notes": {"rich_text": [{"text": {"content": "Owner: docs team"}}]},
    },
)
```

Use `markdown=` to create the page body through Notion's native markdown API:

```python
page = helper.new_page_to_data_source(
    data_source_id,
    {"Name": {"title": [{"text": {"content": "Markdown task"}}]}},
    markdown="# Task Notes\n\n- [ ] Draft\n- [ ] Review",
)
```

## Update a Data Source

```python
helper.update_data_source(
    data_source_id,
    properties={
        "Priority": {
            "select": {
                "options": [
                    {"name": "Low", "color": "gray"},
                    {"name": "High", "color": "red"},
                ]
            }
        },
        "Old Name": {"name": "New Name"},
    },
)
```

Use `{"Property Name": None}` to remove a property. Provide at least one update field: `properties`, `title`, `icon`, `in_trash`, or `parent`.

## Trash and Restore Pages

```python
helper.trash_page(page_id)
helper.restore_page(page_id)
```
