cover-image

NotionDB

🧐 About

NotionDB is an object modelling tool designed to interface with Notion. It is a tool to allow 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 off 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

🧩 Examples

Create a Products Database using a Schema

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:

image-30346aa66e7a454e77fe3ee4be7f393084dc226e-640x358-gif

Create a new Page (record) in the Products Database

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:

image-f45a9c9f05e008a186afafd54383bac60ff03918-640x370-gif

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));

Result:

image-623033a06106f4b0ea364bc4ff2f511ab6490eba-640x388-gif