Documentation Index
Fetch the complete documentation index at: https://mintlify.com/makenotion/notion-sdk-js/llms.txt
Use this file to discover all available pages before exploring further.
Overview
In the Notion SDK, databases are containers that hold one or more data sources. To query the contents of a database, you need to query its data sources using notion.dataSources.query().
The databases namespace does not have a query method. Instead, use notion.dataSources.query() to retrieve pages and data from within a database.
Getting Data Source IDs
First, retrieve the database to get its data source IDs:
const database = await notion.databases.retrieve({
database_id: '897e5a76-ae52-4b48-a6d4-0b46543ebcda'
})
const dataSourceId = database.data_sources[0].id
Querying a Data Source
Once you have a data source ID, query it using notion.dataSources.query():
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
property: 'Status',
select: {
equals: 'In Progress'
}
},
sorts: [
{
property: 'Created',
direction: 'descending'
}
]
})
console.log(response.results)
Filtering Examples
Filter by text property
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
property: 'Name',
rich_text: {
contains: 'project'
}
}
})
Filter by select property
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
property: 'Status',
select: {
equals: 'Complete'
}
}
})
Filter by multi-select property
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
property: 'Tags',
multi_select: {
contains: 'urgent'
}
}
})
Filter by date property
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
property: 'Due Date',
date: {
on_or_after: '2024-01-01'
}
}
})
Filter by checkbox property
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
property: 'Done',
checkbox: {
equals: true
}
}
})
Filter by number property
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
property: 'Priority',
number: {
greater_than: 5
}
}
})
Compound filters with AND
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
and: [
{
property: 'Status',
select: {
equals: 'In Progress'
}
},
{
property: 'Priority',
number: {
greater_than: 3
}
}
]
}
})
Compound filters with OR
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
or: [
{
property: 'Status',
select: {
equals: 'Urgent'
}
},
{
property: 'Due Date',
date: {
on_or_before: '2024-12-31'
}
}
]
}
})
Filter by created time
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
timestamp: 'created_time',
created_time: {
past_week: {}
}
}
})
Sorting Examples
Sort by property ascending
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
sorts: [
{
property: 'Name',
direction: 'ascending'
}
]
})
Sort by property descending
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
sorts: [
{
property: 'Created',
direction: 'descending'
}
]
})
Sort by timestamp
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
sorts: [
{
timestamp: 'last_edited_time',
direction: 'descending'
}
]
})
Multiple sorts
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
sorts: [
{
property: 'Priority',
direction: 'descending'
},
{
property: 'Name',
direction: 'ascending'
}
]
})
let hasMore = true
let startCursor = undefined
while (hasMore) {
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
start_cursor: startCursor,
page_size: 100
})
console.log(`Retrieved ${response.results.length} pages`)
hasMore = response.has_more
startCursor = response.next_cursor
}
const { iteratePaginatedAPI } = require('@notionhq/client')
for await (const page of iteratePaginatedAPI(
notion.dataSources.query,
{ data_source_id: dataSourceId }
)) {
console.log(page.id)
}
Complete Example
const { Client } = require('@notionhq/client')
const notion = new Client({ auth: process.env.NOTION_TOKEN })
async function queryDatabase() {
const database = await notion.databases.retrieve({
database_id: 'database-id'
})
const dataSourceId = database.data_sources[0].id
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter: {
and: [
{
property: 'Status',
select: {
equals: 'In Progress'
}
},
{
property: 'Due Date',
date: {
on_or_after: new Date().toISOString()
}
}
]
},
sorts: [
{
property: 'Priority',
direction: 'descending'
},
{
property: 'Due Date',
direction: 'ascending'
}
],
page_size: 50
})
console.log(`Found ${response.results.length} matching pages`)
for (const page of response.results) {
console.log(`- ${page.id}`)
}
}
queryDatabase()
Additional Options
Filter properties
Limit which properties are returned in the response:
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
filter_properties: ['Name', 'Status', 'Due Date']
})
Include/exclude archived pages
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
archived: false
})
Include/exclude trashed pages
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
in_trash: false
})
Filter by result type
const response = await notion.dataSources.query({
data_source_id: dataSourceId,
result_type: 'page'
})
