Querying

Updated June 15, 2021 9:37 PM

NotionQL allows you to query for database properties and blocks on pages in your Notion Workspace. You will be able to query any databases within the pages you allow NotionQL to access when connecting your Notion Workspace.

Currently the GraphQL endpoint only supports querying your Notion Workspace but support for mutations is coming soon.

Databases

NotionQL generates two GraphQL queries for each Notion Database.

  • singular, camel-cased query that finds a specific page in the database. The query uses the same name as the database's title and takes in the page ID. If the schema's title is a plural noun, NotionQL attempts to use its singular form.
  • plural, camel-cased query that returns all pages in the database. If possible, the query uses the plural form of the singular query name.

Each field (database title and properties) undergo the following sanitization:

  1. Camel-casing and deburr-ing
  2. Removing special characters
  3. Adding an underscore for fields that start with a number

Examples

Simple Field Name

Golden State WarriorsgoldenStateWarriors

Fields with Diacritical Marks

Golden Ståte WårriorsgoldenStateWarriors

Fields with Special Characters

Golden State Warriors 😀goldenStateWarriors

Fields with Leading Numbers

69 Golden State Warriors_69GoldenStateWarriors

Fields with Only Special Charactes

😀😀😀😀😀_

Blocks

The Notion API currently only supports text-like blocks, limiting what types of blocks NotionQL can return. Currently, NotionQL supports the following block types:

  • paragraph
  • bulleted_list_item
  • numbered_list_item
  • toggle
  • to_do

Markdown

Blocks include a markdown field which automatically converts the Rich Text Object into markdown.

There are a few weird edge cases:

  • Annotations like bold or strikethrough will only apply on the text and not leading or trailing whitespace. For example, This statement ~~doesn't exist~~ in the middle → This statement ~~doesn't exist~~ in the middle.
  • Annotations applied to whitespace will be ignored. This differs than Notion's markdown exporter. For example, exporting This → ← is italic would export This → ← is italic from NotionQL but This →**← is italic in Notion.