Notion Databases Explained + API Changes (New Notion Data Model)
Traditionally in Notion, a "database" meant what software developers call a "table" - a collection of records with a primary key and various properties (columns).
As of August 2025, Notion has updated this terminology in both the UI and API. Now:
A database is a container that can hold multiple collections of structured data
A data source is what was previously called a database (a table with pages and properties)
The new hierarchical structure looks like this:
Database
Contains one or more
data sourcesor linked views of data sourcesEach data source contains zero or more
pages(records)
There are two types of data sources within a database:
Source data sources: Original tables that, if deleted, remove all data
Linked views: References to data sources that, if deleted, only remove the view while preserving the original data source
Views can display your data in various formats (table, gallery, list, feed, board, etc.).
Source: Notion documentation
Practical Implications
Practically, here are relevant changes (i.e, changes that affect how to think about and work in Notion):
One database can contain multiple data sources, which facilitates organization in Notion. For example, when building a CRM (customer relationship management) system, you can create a single
Database, called, say, “CRM”, composed of multipleData Sources, for example: Contacts, Companies, Deals, Interactions.This way, all of the crm-related data sources are stored under one “roof” (the database), which fosters clarity and facilitates permissions management and page-level access rules.
You can easily move a
data sourceout of a database to make it independent (i.e., part of a new database) or move it under a separate existing database. Making a data source independent is especially relevant when you want to share that data source to the web or with specific people, without using the new page-level access rules. That’s because a database that contains multiple data sources doesn’t allow sharing a single data source to the web or with specific users (unless using page-level access rules).The Notion API reflects this new structure since September 3rd 2025. There is a new Notion API version you can use: version 2025-09-03. The previous API version is still supported, and it is best to keep it for a period of time while you transition your Notion workspace and/or automations into the new paradigm. The new API version introduces breaking changes for databases, that’s why it’s worth it to proceed with caution, and only implement it after you’ve ensured your Notion workspace has transitioned into the use of data sources, if you decide so.
The main breaking change is that if you create a database with multiple data sources, the API endpoints and structure changes. So, previous API calls that worked would stop working. If, instead, you keep one data source per database, the API calls using the old version will continue working as before.
One database can contain both “root” data sources and “linked views” of them. I find this can create confusion, because it is not readily apparent how to distinguish the two especially when the data source title is hidden. I personally like to only keep root data sources together, and linked views together. Not mix the two. So, if a database contains a source data source, i ensure it only contains source data sources, and never linked views of data sources. If a database contains a linked view of a data source, I ensure there are only linked views of data sources in that database, and not source data sources.
Want to work together to build your custom operating system? Submit your interest here.
