Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท API and Integrations

Querying Databases with the API

Learn the JSON shape of Notion database queries: property filters, compound and/or filters, sorts, page_size, and cursor pagination, with a runnable stand-in.

A database query is the API's most-used call. You send a filter and sorts in JSON, Notion returns matching pages (rows) in batches, and you follow a cursor to get the rest. The structure mirrors the filter and sort menus in the app, so if you know views, you already know the ideas.

The real API cannot be reached from this site. To make the logic runnable, this lesson includes a small stand-in query engine in JavaScript that understands a subset of the same JSON shape. It is not the real thing, and edge cases in the real API (rich text, relations, formulas) are richer. Confirm exact filter types in Notion's reference for your API version.

The request

You POST to the database's query endpoint with an optional body:

JSON
{
  "filter": {
    "and": [
      { "property": "Status", "status": { "equals": "In progress" } },
      { "property": "Priority", "select": { "equals": "High" } }
    ]
  },
  "sorts": [
    { "property": "Due", "direction": "ascending" }
  ],
  "page_size": 25
}

Key points:

  • A property filter names the property, then a key for the property's type (select, status, number, checkbox, date, title, rich_text, people, relation, ...), then a condition.
  • Conditions depend on the type. Examples: equals, does_not_equal, contains, starts_with, is_empty, is_not_empty for text; greater_than, less_than for numbers; before, after, on_or_after, past_week for dates; equals: true for checkboxes.
  • Compound filters use and or or with a list of filters. They can nest.
  • sorts is a list; the first has priority. A sort may name a property or a timestamp (created_time, last_edited_time).
  • page_size is up to 100. The default is 100.

The response and pagination

The response is a list:

JSON
{
  "object": "list",
  "results": [ { "object": "page", "id": "...", "properties": { } } ],
  "has_more": true,
  "next_cursor": "abc123"
}

If has_more is true, send the same query again with "start_cursor": "<next_cursor>". Repeat until has_more is false. Forgetting this is the classic bug: scripts that "work" in testing with ten rows and silently drop everything past the first hundred in production.

Stand-in: a query engine

The code below evaluates a simplified filter against plain objects. Rows are flattened ({Status: "Done"}) instead of the real nested property JSON, so you can concentrate on the logic.

JS Stand-in: filter, sort, paginate

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The loop at the bottom is the pagination pattern you will use in real code.

Reading property values

Real rows are nested and typed. A Select value is at page.properties.Priority.select?.name, and a title is an array of rich-text pieces. The helper below turns a real-shaped sample into a flat object. The sample is hand-written.

JS Stand-in: flatten properties

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note the ?.: a Select can be empty, in which case select is null.

Tips for real queries

  1. Filter on the server side with the API's filter. Fetching everything and filtering in your code wastes your rate limit.
  2. Ask for what you need. Smaller page_size for a quick check; 100 for bulk.
  3. Sort on a stable property, so pagination does not skip or repeat rows when data changes. created_time is stable.
  4. Remember relations and rollups return IDs or computed values, not full pages; fetch related pages with a second call when needed.
  5. Cache results that change rarely, so you do not re-query on every request.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. How do you fetch the next batch of results?

    When has_more is true, send the same query with start_cursor set to the returned next_cursor.
  2. 2. How do you combine two filter conditions that must both be true?

    Compound filters use and or or around a list of conditions.
  3. 3. A Select property can be empty. What is a safe way to read its name in JavaScript?

    An empty select is null, so optional chaining avoids an error.

Summary

  • Query with POST and a body of filter, sorts and page_size.
  • Filters name a property and a type-specific condition; combine with and and or.
  • Follow next_cursor while has_more is true.
  • Properties are typed and nested; flatten them with a small helper and handle empty values.

Next: Creating Pages and Blocks with the API