Notion-query-builder

Notion-query-builder is an opinionated filter query builder written in Typescript for use with the official Notion javascript client.

Note: This software is not affliated with Notion Labs, Inc. Issues and/or support should relating to this library be directed to the project's issue tracker.

Prerequisites

Compatibility	Version Id
Notion API	2022-06-28
Notion JS SDK	v2.2.3+
Javascript	ES2019+

Installation

NodeJS

npm i notion-query-builder

// or alternatively, [yarn|pnpm] add notion-query-builder

Deno

import nob from 'https://deno.land/x/notion-query-builder/mod.ts'

Usage

This library serves as a utility to write compact yet manageable queries for the Notion API - it is not a replacement for the client. It does this by doing the following:

You do not write JSON directly. This avoids large JSON objects clogging up your code, needing to remember structure and repetitive work.
You instead use 3 components - builders, queries and conditions - to construct your query and only provide the values.
You can use the components separately or mix with raw JSON if you prefer.

Once you have your query built, you execute the builder to output the JSON which defines your filter. This JSON is then used with the official client.

import { Client } from '@notionhq/client';
import nob from 'notion-query-builder';

const notion = new Client({ auth: process.env.NOTION_API_KEY });

const myFilter = nob.filterQuery([
  nob.checkboxFilter('Published', nob.equal(true)),
  nob.multiSelectFilter('Tags', nob.contains(['A', 'B']))
]);

const response = await notion.databases.query({
  database_id: databaseId,
  filter: myFilter.toJson()
});

console.log(myFilter.toJson())

{
  "and": [
    {
      "property": "Published",
      "checkbox": {
        "equals": true
      }
    },
    {
      "property": "Tags",
      "multi_select": {
        "contains": "A"
      }
    },
    {
      "property": "Tags",
      "multi_select": {
        "contains": "B"
      }
    }
  ]
}

API Quick Reference

This library's method namings aims to match closely with the official Notion API. As such, please also refer to the official Notion API documentation.

Full documentation can be found here.

Conditions

These conditions take native data types as arguments.

method	alias	example
equal	`eq`,`equal`,`equals`,`is`,`be`	`nob.equal('hello world')`
notEqual	`neq`,`notEqual`,`notEquals`,`isnt`,`isNot`	`nob.notEqual('hello world')`
contain	`contain`,`contains`,`has`,`include`,`includes`	`nob.contain('hello world')`
notContain	`notContain`,`notContains`,`doesNotContain`,`hasNot`,`exclude`,`excludes`,	`nob.notContain('hello world')`
startsWith	`startsWith`	`nob.startsWith('hello')`
endsWith	`endsWith`	`nob.endsWith('world')`
greaterThan	`gt`,`greaterThan`,`moreThan`	`nob.greaterThan(9999)`
greaterThanOrEqualTo	`gte`,`greaterThanOrEqualTo`,`moreThanOrEqualTo`	`nob.greaterThanOrEqualTo(9999)`
lessThan	`lt`,`lessThan`	`nob.lessThan(9999)`
lessThanOrEqualTo	`lte`,`lessThanOrEqualTo`	`nob.lessThanOrEqualTo(9999)`
empty	`empty`,`isEmpty`,`notExist`	`nob.empty()`
NotEmpty	`notEmpty`,`isNotEmpty`,`exists`	`nob.notEmpty()`
before	`before`	`nob.before('2023-01-01)`, `nob.before(new Date(2023,0,1))`
onOrBefore	`onOrBefore`	`nob.onOrBefore('2023-01-01)`
after	`after`	`nob.after('2023-01-01)`, `nob.after(new Date(2023,0,1))`
onOrAfter	`onOrAfter`	`nob.onOrAfter('2023-01-01)`
pastWeek	`pastWeek`	`nob.pastWeek()`
pastMonth	`pastMonth`	`nob.pastMonth()`
pastYear	`pastYear`	`nob.pastYear()`
thisWeek	`thisWeek`	`nob.thisWeek()`
nextWeek	`nextWeek`	`nob.nextWeek()`
nextMonth	`nextMonth`	`nob.nextMonth()`
nextYear	`nextYear`	`nob.nextYear()`

Term Level Filters

These filters take conditions as arguments.

method	example
textFilter	`nob.textFilter('name', nob.contains('notion'), 'title')`
numberFilter	`nob.numberFilter('age', nob.gte(12))`
checkboxFilter	`nob.checkboxFilter('name', nob.eq(true))`
selectFilter	`nob.selectFilter('name', nob.eq('notion'))`
multiSelectFilter	`nob.multiSelectFilter('name', nob.eq('notion'))`
statusFilter	`nob.statusFilter('status', nob.eq(['todo', 'in progress']))`
dateFilter	`nob.dateFilter('name', nob.before('2023-01-01))`
peopleFilter	`nob.peopleFilter('name', nob.eq('notion'))`
filesFilter	`nob.filesFilter('name', nob.eq('notion'))`
relationFilter	`nob.relationFilter('name', nob.eq('notion'))`

Queries and Sepcial Filters

These queries and special filters take term level filters as arguments.

method	example
filterQuery	`nob.filterQuery(nob.textQuery('name', nob.eq('notion'))`
rollupFilter	`nob.rollupFilter('every', nob.numberFilter('age', nob.gte(10)))`
formulaFilter	`nob.formulaFilter('number', nob.numberFilter('age', nob.gte(10))`
compoundFilter	`nob.compoundFilter().and(nob.textFilter('name', nob.eq('notion'))).or(nob.numberFilter('age', nob.gte(10)))`

Sort

Only one function but will switch between propertySort and TimestampSort depending on the field given. Direction is optional and defaults to descending.

methods	examples
sort	`nob.sort('age')`, `nob.sort('age', 'ascending)`, `nob.sort('created_time', 'ascending)`

Tests

Run unit tests

npm test

Credits

notion-query-builder is inspired by elastic-builder and the countless hours it has saved writing ElasticSearch queries.

Licence

MIT

Donate

A random charity appears!

Young Women's Trust

Young Women’s Trust offers support to young women aged 18 to 30, who are living on low or no pay and want to build a better future, through Work It Out. Work It Out is a free service that offers coaching and personalised feedback on CV and job applications.

Org: Young Women's Trust, reg. charity no. 217868

Donate: https://www.youngwomenstrust.org/donate/