> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Import model, field type mapping, refresh cadence, and limits for the Notion data source in Adriel.

## Introduction

Notion is a workspace tool where teams keep structured data in databases — project trackers, content calendars, and pipeline boards. The Adriel Notion connector imports rows from a single Notion database into one Adriel data source: each page in the database becomes a row, and the database's properties become the available fields. Notion property types are mapped onto metric and breakdown shapes so those rows can be charted alongside marketing-platform sources.

As a file/storage connector, the available fields are not a fixed catalog — they are derived from the selected database's properties. Data types are mapped from Notion property types to Adriel field types: numeric properties become metrics, while text, select, and date properties serve as breakdowns.

To connect this data source, see [How to connect Notion to Adriel](/data-sources/g-n/notion/how-to-connect).

## Data refresh strategy

Notion data is fetched **on demand** — fresh data is pulled from Notion each time the dashboard is visited. There is no scheduled cache refresh; every query paginates through the database's pages at request time, so results always reflect the current state of the Notion database.

Because there is no cache, changes made in Notion (edited rows, renamed properties, new columns) appear on the next dashboard load without a sync delay. The trade-off is that large databases re-paginate on every load.

<Note>
  **Live querying, not cached**

  Unlike cached connectors, Notion is queried live at dashboard view time. No scheduled refresh occurs, and the connection is not kept warm between requests (`timeSecToKeepConnection = 0`); each dashboard load re-issues the query against the Notion API.
</Note>

## Architecture levels

Workspace (integration) → Database → Page (row).

* The connection is authorized against a Notion workspace through an internal integration.
* One Adriel data source binds to exactly one Notion database.
* Each page inside that database becomes one row in the data source.

Only databases the integration has been added to appear in the database picker. To expose a second database, create a second data source on the same connection.

## Date range limits

There is no platform-imposed date range limit. Query bounds are defined by the source database's contents and by the widget's date-range control applied to the date property mapped during setup. A database with no date property is treated as a single snapshot set — all rows are returned regardless of the dashboard date range.

## Import model

The connector reads a single Notion database through the Notion REST API v1 (`Notion-Version: 2022-06-28`). The import runs in two stages: database selection at setup, and per-property parsing at query time.

**Database selection.** During data-source setup, the connector lists available databases with a paginated `POST /search` lookup filtered to `object: database` (`page_size: 100`), skipping any database without a title. The selected database is stored as a combined `<name>:<id>` asset value; one data source is created per selected database.

**Row fetch.** At query time the connector paginates through the database's pages with `POST /databases/{id}/query`, using Notion's cursor-based pagination (`start_cursor` / `has_more`, default `page_size: 100`). It walks every page of results on each query — there is no incremental caching. Only the v1 row-query path is active (`executeQueryV2` is disabled).

**Property parsing.** Field headers are rebuilt from the live database schema on every query, so a property renamed or retyped in Notion propagates on the next load. Each property value is normalized to a flat cell by its Notion type — for example, a `date` value renders as `start` or `start ~ end`, `multi_select` values are joined into a single string, and `title` and `rich_text` segments are concatenated.

## Filters

Date-range filtering is pushed into the Notion query as a **server-side** `filter` on the mapped date property, so Notion returns only the pages within range. All other widget filters are applied **client-side** after the rows are returned. On large databases this means non-date filters do not reduce the number of pages Notion paginates through.

## Field type mapping

Notion has no fixed metric or breakdown catalog. The available fields are the properties of the selected database, resolved from the live schema at query time. Field names are prefixed with `notion:` internally.

<Note>
  **How to read the columns**

  The **Data type** column uses the platform's ten-value vocabulary: **Number**, **Currency**, **Percentage**, **Ratio**, **Duration**, **Date**, **Text**, **URL**, **Array**, **Boolean**. The **Field role** column indicates whether the field serves as a metric, a breakdown, or both.
</Note>

Each Notion property type maps to an Adriel field type as follows.

| Notion property type                       | Adriel field type | Data type | Field role                                                       |
| ------------------------------------------ | ----------------- | --------- | ---------------------------------------------------------------- |
| `number`                                   | `number`          | Number    | Metric                                                           |
| `formula` (numeric result)                 | `number`          | Number    | Metric                                                           |
| `rollup` (numeric result)                  | `number`          | Number    | Metric                                                           |
| `formula` (non-numeric result)             | `any`             | Text      | Breakdown                                                        |
| `rollup` (non-numeric result)              | `any`             | Text      | Breakdown                                                        |
| `date`, `created_time`, `last_edited_time` | `date`            | Date      | Breakdown; enables date-range filtering when mapped during setup |
| `title`, `rich_text`                       | `string`          | Text      | Breakdown                                                        |
| `select`, `status`                         | `string`          | Text      | Breakdown (single value)                                         |
| `multi_select`                             | `string`          | Text      | Breakdown (values joined into one string)                        |
| `people`, `created_by`, `last_edited_by`   | `string`          | Text      | Breakdown (user names)                                           |
| `url`, `phone_number`                      | `string`          | Text      | Breakdown                                                        |
| `checkbox`                                 | `string`          | Text      | Breakdown (rendered as `"true"` / `"false"`)                     |
| `files`                                    | `string`          | Text      | Breakdown (file names, joined)                                   |
| `unique_id`                                | `string`          | Text      | Breakdown (numeric ID rendered as text)                          |
| `relation`                                 | not imported      | —         | —                                                                |

<Note>
  **Relation properties are not imported**

  Relation property values are skipped during parsing and do not appear as usable data. To surface a related record's value, add a `rollup` on the relation in Notion and import that rollup instead.
</Note>

### Adriel-added fields

The connector does not add synthetic fields on top of the database. Every field derives directly from a Notion property; the database's own properties are the complete field list.

### Aggregation defaults

Aggregation defaults are assigned when the header is built, based on the Notion property type.

| Notion property type                                  | Default aggregation                         |
| ----------------------------------------------------- | ------------------------------------------- |
| `formula` (numeric result), `rollup` (numeric result) | `sum`                                       |
| `number`                                              | None — the aggregation is chosen per widget |
| All other types                                       | None                                        |

## Limitations

Based on the current connector:

* **Databases only, not free-form pages.** Only structured Notion databases (pages-as-rows) are supported. Free-form pages with heading and paragraph content but no schema are not. CSV exports and page block content are not read.
* **One database per data source.** Multiple databases require multiple data sources on the same connection.
* **Per-page integration access.** Only databases the integration has been added to as a member appear in the picker. Granting access to a new database requires inviting the integration to that page or database in Notion.
* **Relation properties are not imported** — use a rollup to surface related values.
* **Multi-select is stored as a joined string.** Individual tag values are concatenated into one text cell; slice on them with string-contains filters rather than exact match.
* **Rollup date results are not returned.** A rollup whose result is a date resolves to an empty value.
* **Live re-pagination on every load.** With no cache, large databases issue many sequential requests per dashboard load and can be slow to render.
* **Rate limited.** Requests to the Notion API are rate limited to an average of three requests per second, with occasional bursts beyond that average allowed ([Notion API request limits](https://developers.notion.com/reference/request-limits)).
* **No token refresh.** Authentication uses a static internal-integration API key; the connector does not rotate or refresh it. If the token is revoked in Notion, the data source must be re-authorized (see the paired how-to).
* **Native combination requires shared breakdowns.** Notion data can only be combined with other connector types natively when they share the same breakdowns; otherwise configure Blend Data settings.

## API references

* [Notion API overview](https://developers.notion.com/docs/getting-started)
* [Query a database (POST /databases/{id}/query)](https://developers.notion.com/reference/post-database-query)
* [Database property values](https://developers.notion.com/reference/property-value-object)
* [Search (POST /search)](https://developers.notion.com/reference/post-search)
* [Authorization (internal integrations)](https://developers.notion.com/docs/authorization)

## See also

* [How to connect Notion](/data-sources/g-n/notion/how-to-connect) (paired how-to)
* [Airtable data reference](/data-sources/a-f/airtable/data-reference) — alternative structured-data platform
* [Google Sheets data reference](/data-sources/g-n/google-sheets/data-reference) — alternative spreadsheet platform