Notion API filter exclusion of formula, rollup, and relation properties forces client-side filtering

Architectural Patterns for Scale

Because the Notion API returns a 400 error when filtering on formula, rollup, or relation properties, teams dealing with datasets larger than a few thousand pages typically move away from real-time API querying in favor of Data Mirroring.

External Indexing (The Mirror Pattern)

The most reliable pattern for maintaining low latency is synchronizing Notion data to an external indexed database (such as PostgreSQL, MongoDB, or Elasticsearch). In this architecture:

• Ingestion: A background worker polls the Notion API or listens to webhooks to sync changes.
• Materialization: Computed values (formulas/rollups) are calculated and stored as static values in the external database.
• Querying: The client application queries the external database, which supports full indexing and complex filtering, returning only the necessary Notion Page IDs.

Relation-Based Pre-Filtering

For relation properties specifically, you can reduce the payload size by performing a two-step query:

1. Query the target database to find pages matching your criteria and collect their Page IDs.
2. Query the source database using a filter on the relation property, passing the collected IDs as a list of values.

Runtime Detection of Filterable Properties

There is currently no dedicated metadata endpoint to check if a property type has become filterable. The only reliable way to detect this at runtime is to attempt a scoped query (e.g., a query with a limit of 1) using the property in a filter. If the API returns a 400 error, the property remains unsupported. If it returns a 200, the feature has been deployed.

Consistency Risks in Client-Side Joins

Querying a target database and then joining those results with a source database on the client side introduces Eventual Consistency risks. Because these are separate HTTP requests, the following can occur:

• Race Conditions: A page may be deleted or its relation modified between the first and second request, leading to "orphaned" IDs or missing results.
• Pagination Drift: If pages are added or moved during the pagination process of a large join, you may skip records or encounter duplicates.

To mitigate this, treat client-side joins as "best effort" and implement a validation step to handle null or missing references gracefully.

Verification Command

To confirm your current API version's behavior, attempt a query against a formula property using curl:

curl -X POST https://api.notion.com/v1/databases/{database_id}/query \
  -H "Authorization: Bearer {token}" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  --data '{"filter": {"property": "Your Formula Property", "formula": {"string_contains": "Value"}}}'

A 400 Bad Request confirms that the property is not filterable.