Notion

Connect a Notion workspace to ingest its databases into your organization as datasets you can query alongside the rest of your data.

Connect your Notion workspace

1. From your organization, open Integrations in the sidebar. Find Notion (in the Docs category) and click Connect.

2. Notion's consent screen opens. Select the databases you want OSO to ingest, or pages that contain databases, then allow access. Plain pages without a database have nothing to ingest. Notion's consent screen can't be limited to databases, so it's up to you to pick them. You'll be redirected back to Integrations, where a "Connected Notion" notification confirms the connection. If something goes wrong, you'll see "Couldn't connect Notion" instead — try again.

You can connect more than one Notion workspace. To add another, click Manage on the Notion row and then Add workspace.

Share databases with the integration

important

OSO ingests databases, and can only see what you share with the integration. Anything you didn't select on the consent screen is invisible to it and won't be ingested. A plain page with no database inside produces nothing to ingest.

To share more databases after connecting, either:

• Open the database, or a page that contains it, in Notion, open the page menu (⋯), choose Connections, and add the OSO integration. Sharing a page also shares everything nested under it, including databases.
• Or click Add workspace in the Manage dialog to go through Notion's consent screen again and pick more databases.

If the data source picker is empty when you create an ingestion, no database is shared with the integration yet: only plain pages, or nothing, have been shared. Share a database as above, then click Refresh in the dialog, which checks again without reopening it. Newly shared items can take a moment to appear in the picker.

Create an ingestion

Each connected workspace ingests through a single dataset.

1. On the Integrations page, click Manage on the Notion row. Each connected workspace is listed under Workspaces.

2. Click Add ingestion next to the workspace.

3. In the Add a Notion ingestion dialog, set the Dataset name. A valid name is suggested from your workspace name; use lowercase letters, numbers and underscores, starting with a letter.

4. Under Data sources, choose what to ingest:

   • All shared data sources — every data source shared with the integration is ingested, including ones you share later. The dialog lists what is currently shared, and you can't add the ingestion while nothing is shared.
   • Specific data sources — tick the data sources you want from the list. Each entry shows the data source's title, with its database's title underneath. Select at least one.

5. Click Add ingestion.

The dataset is created and starts syncing right away. It's listed in the same dialog, and its sync status is visible in the Data Catalog.

A Notion database can contain several data sources. Each data source becomes its own table, so one database may produce more than one.

Change which data sources are ingested

In the Manage dialog, click the pencil icon (Edit data sources) on the ingestion's row, adjust the selection, and click Save data sources. The dataset itself keeps its name. A data source you picked earlier that is no longer shared with the integration is dropped from the selection when you edit.

Troubleshooting the data source list

• This Notion workspace needs reconnecting — Notion rejected this workspace's connection. Click Add workspace in the Manage dialog to authorize the workspace again, then reopen the ingestion dialog.
• Notion is unavailable — OSO couldn't load your data sources from Notion. Click Refresh to try again in a moment.

What the tables look like

Every data source is stored as a table with one row per page. The table is named after the data source's title. If two data sources share a title, the later one gets a short id suffix, and a data source keeps the table name it was first given.

Each table has these columns, followed by one column per Notion property:

Column	Contents
id	The page's Notion id
url	The page's Notion URL
created_time	When the page was created
last_edited_time	When the page was last edited
archived	Whether Notion reports the page as archived
in_trash	Whether Notion reports the page as in the trash

How properties are stored:

• Simple properties (text, numbers, checkboxes, selects, dates and similar) become plain values.
• Rollups, files and other complex types are stored as JSON text.
• A date range adds a <name>_end column holding the end of the range.
• Relation values are capped at Notion's limit of 25 per cell, and the run log warns when values were cut off. People values may also be cut off at 25, without a warning, because Notion doesn't report it.
• A property whose name clashes with a system column, or with another property once names are normalized, gets a suffix.

How data is refreshed

Every run fully refreshes the tables, so edits, new pages and trashed pages are all reflected on the next run. If a data source you ingest is no longer shared with the integration, it's skipped and the run log shows a warning.

If Notion rejects the connection during a run, the run fails and asks you to reconnect Notion. Use Add workspace in the Manage dialog to authorize the workspace again.

Limitations

• Page body content isn't ingested. Only the page's properties are stored, not the blocks inside the page.
• Only the dataset's creator can edit it. Other members of your organization can't change its data sources.

Remove an ingestion or disconnect a workspace

• Delete an ingestion. In the Manage dialog, click the trash icon on the ingestion's row and confirm Delete this ingestion?. This deletes the dataset and stops future syncs. The workspace stays connected, so you can add an ingestion again later.
• Disconnect a workspace. Click the disconnect icon on the workspace's row and confirm Disconnect Notion?. This removes the connection and deletes the workspace's Notion ingestion datasets along with the data already ingested. You can reconnect and set the workspace up again at any time.

Neither action changes anything in Notion itself. To stop OSO's access completely, you can also remove the OSO integration under Connections in your Notion settings.