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.

npm i notion-query-builder

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

import nob from 'npm:notion-query-builder'

As your filter queries become more complex, so does the size of the JSON you'll write for them. Large unwieldy blocks of JSON are always a hassle to reason about and maintain - often, solutions to manage this data utimately leads to code bloat.

node-query-builder offers a simple and easy-to-use API to write filters and conditions programatically, reducing the effort and amount of code required by many factors.

To get started, here's a high level overview of the library:

• filters and conditions are functions which combine to construct a query.
• Usually, filters take conditions as arguments but special filters may take other filters as arguments
• To use with the client, the constructed query needs to return its JSON output. This is usually done by calling the toJSON() method.

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

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

Full API documentation and examples can be found at https://jimleuk.github.io/notion-query-builder/.

This library aims to match closely with the official Notion API. As such, please also refer to the official Notion API documentation. For any inconsistencies, please raise a ticket in the project's issue tracker.

These conditions take native data types as arguments.

These filters take conditions as arguments.

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

The Sort() function will switch between propertySort and TimestampSort depending on the field given. Sort Direction is optional and defaults to descending.

Run unit tests.

npm test

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

MIT

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/