NotionDB
About
NotionDB is an object modelling tool designed to interface with Notion. It is a tool to allows developers to easily spin up a cloud-based database using Notion Databases. Notion Databases consist of a series of Notion Pages (database rows) with various Properties (database columns).
NotionDB leverages the official Notion API and provides developers with easy-to-use classes and helper functions to easily retrieve, write, update, and delete data.
Why use Notion as a database?
- On top of the standard primitive types, Notion provides advanced types such as Dates with Time (start and end), People, URLs, Emails, Phone Numbers, Formulas, Relations, Rollups, and more.
- Notion provides great facilities for Filtering (compound and/or filtering and nested filtering) and multi-level Sorting. This makes querying and sorting through data seamless for developers.
- To visualize the data, the Notion user interface can display the database data in various views such as Table, Board, Timeline, Calendar, List, and Gallery views.
- Being able to access and write data to a Notion Database from a server-side environment opens up endless opportunities to interface Notion with other databases, services, and APIs.
Open source
The project is Open Source and can be viewed on GitHub & NPM.
Features
Databases
- Get all Databases associated with an integration key.
- Get a single Database by Database ID or Database Notion URL.
- Create a Database using a Schema of Properties (column definitions).
Users
- Get all Users from a Database.
- Get a single User by User ID.
Pages
- Get all Pages from a Database.
- Get a single Page by Page ID or Page Notion URL.
- Filter down and Sort Pages from a Database using Notion's powerful Filter and Sort tools.
- Create a Page (a database row) inside a Database.
- Delete a Page from a Database.
- Restore a deleted Page from a Database.
Blocks
- Get all supported children Blocks from a Page.
Technologies used
- Notion API - REST API endpoints.
- Node.js - Server backend environment.
- TypeScript - Written 100% in TypeScript.
Examples
Create a products database
1const { NotionDB } = require("notiondb");
2const { NotionId } = require("notiondb/models");
3const { SchemaObject, PropertySchema } = require("notiondb/schema");
4
5const notionDb = new NotionDB(process.env.NOTION_INTEGRATION_TOKEN);
6const schemaObjects = [
7 new SchemaObject("product_id", "title"),
8 new SchemaObject("name", "rich_text"),
9 new SchemaObject("category", "select"),
10 new SchemaObject("price", "number"),
11 new SchemaObject("picture", "rich_text"),
12 new SchemaObject("last_modified", "last_edited_time"),
13];
14const schema = new PropertySchema(schemaObjects);
15const database = await notionDb.databases.create(
16 new NotionId(process.env.PARENT_PAGE),
17 "Products",
18 schema
19);
20console.log(database.object);Result:
Create a new page (record)
1const { NotionDB } = require("notiondb");
2const { NotionId } = require("notiondb/models");
3
4const notionDb = new NotionDB(process.env.NOTION_INTEGRATION_TOKEN);
5const database = await notionDb.databases.get(
6 new NotionId(process.env.PRODUCTS_DATABASE)
7 );
8
9const page = await database.pages.create({
10 product_id: "P-0019",
11 name: "Chocolate",
12 category: "Snacks",
13 price: 1.59,
14 picture: "🍫",
15});
16
17console.log(page.object);Result:
Get all Products that are "Cooked Foods" AND less than $2 from the Database (Sort by product_id).
1const { NotionDB } = require("notiondb");
2const { NotionId } = require("notiondb/models");
3const {
4 SelectFilter,
5 NumberFilter,
6 CompoundFilter,
7} = require("notiondb/models/filter");
8const { PropertySort } = require("notiondb/models/sort");
9
10const notionDb = new NotionDB(process.env.NOTION_INTEGRATION_TOKEN);
11const database = await notionDb.databases.get(
12 new NotionId(process.env.PRODUCTS_DATABASE)
13);
14
15const categoryFilter = new SelectFilter("category", "equals", "Cooked Food");
16const priceFilter = new NumberFilter("price", "less_than", 2);
17const compoundFilter = new CompoundFilter(
18 [categoryFilter, priceFilter],
19 "and"
20);
21const productIdSort = new PropertySort("product_id", "ascending");
22
23const pages = await database.pages.getMany({
24 filter: compoundFilter,
25 sorts: [productIdSort],
26});
27console.log(pages.map((p) => p.object.properties));