system-prompts-and-models-of-ai-tools/NotionAi/notion-ai_20260322/modules/notion/databases/data-source-sqlite-tables.md

Data source SQLite tables (Notion scripting)

Use this doc when you need to query structured data from Notion data sources (databases) using connections.notion.querySql, or when you need to update page properties inside a data source using connections.notion.updatePage.

1) One data source = one SQLite table

• For each Notion data source URL dataSourceUrl, there is a corresponding SQLite table named exactly dataSourceUrl.
• Always double-quote the table name in SQL:
  • SELECT * FROM "dataSourceUrl" LIMIT 10

2) System columns (always present)

Every data source table includes:

• url (TEXT, unique): the page URL for the row (this is the primary identifier you should select).
• createdTime (TEXT): ISO-8601 datetime string for when the page was created.

3) Property columns (how Notion properties map to SQL)

Column naming

• Column names are derived from the Notion property name (as seen in the data source schema). SQLite identifiers are case-insensitive, but you should still use the exact column names shown in the data source's <sqlite-table> definition.
• SQLite identifiers can contain spaces/special characters; always double-quote column names unless they're simple identifiers.
  • Example: "Task Name", "Status", "Due Date"
• If a property name conflicts with a system column name (id, url, createdTime), it is prefixed with userDefined::
  • Example: "userDefined:url"

Which properties become columns?

Only a subset of property types are queryable via SQL. Properties not listed below may not appear as columns; use connections.notion.queryView (or load/view the page) to access them.

Property type → SQL type + semantics

The table contains one or more columns per property:

• Title / Text / URL / Email / Phone: Column type: TEXT. Value: plain string (may be empty or NULL).

• Number: Column type: FLOAT. Value: numeric (or NULL).

• Checkbox: Column type: TEXT. Values: "__YES__" = true, "__NO__" = false, NULL defaults to false.

• Select: Column type: TEXT. Value: one of the configured option names (or NULL).

• Status: Column type: TEXT. Value: one of the configured status option names (or NULL).

• Multi-select: Column type: TEXT. Value: JSON string encoding Array<string> (option names). Use json_each to filter/join:

  • ... WHERE EXISTS (SELECT 1 FROM json_each(t."Tags") WHERE value = 'Important')

• Person: Column type: TEXT. Value: If limit 1: often a JSON string encoding a single user ID. Otherwise: typically a JSON string encoding Array<string> of user IDs. User IDs use the standard Notion user URL format: "URL".

• Files: Column type: TEXT. Value: JSON string encoding Array<string> of file IDs.

• Relation: Column type: TEXT. Value: JSON string encoding related page URLs. Limit 1: often a JSON string of a single page URL. Otherwise: typically a JSON string encoding Array<string> of page URLs. To join, prefer json_each over the relation column when it's an array.

• Created time / Last edited time: Column type: TEXT (required / NOT NULL). Value: ISO-8601 datetime string, automatically set.

• Date: Expands into 3 columns:

  • "date:<Property Name>:start" (TEXT): ISO-8601 date/datetime string
  • "date:<Property Name>:end" (TEXT): ISO-8601 date/datetime string (must be NULL for single-date values)
  • "date:<Property Name>:is_datetime" (INTEGER): 1 for datetime, 0 for date, NULL defaults to 0

• Auto-increment ID: Column type: INTEGER. Value: number (or NULL).

• Created by / Last edited by: Column type: TEXT. Value: user URL string (read-only, automatically set).

• Place / Location: Expands into 5 columns:

  • "place:<Property Name>:address" (TEXT): address string
  • "place:<Property Name>:name" (TEXT): optional place name
  • "place:<Property Name>:latitude" (FLOAT): latitude
  • "place:<Property Name>:longitude" (FLOAT): longitude
  • "place:<Property Name>:google_place_id" (TEXT): optional Google Place ID
  • Do not set the base property key directly; use expanded place: keys.

4) Querying data sources

SQL queries (connections.notion.querySql)

You can query one or more data sources (tables) and join them. Always:

• Include url in your SELECT when possible.
• Double-quote table names and any column names with spaces/special characters.

Example: basic filter

｀｀｀ts const result = await connections.notion.querySql({ dataSourceUrls: ["dataSourceUrl"], query: SELECT url, "Status", "Owner" FROM "dataSourceUrl" WHERE "Status" = ?, params: ["In progress"], }) ｀｀｀

Example: join via relation column (relation stores JSON array of URLs)

｀｀｀ts const result = await connections.notion.querySql({ dataSourceUrls: ["okrs", "teams"], query: SELECT o.url, o."Objective", t."Team Name" FROM "okrs" o JOIN "teams" t ON t.url IN (SELECT value FROM json_each(o."Team")), }) ｀｀｀

View queries (connections.notion.queryView)

Use this when you want "whatever the view shows" and don't need custom SQL.

｀｀｀ts const result = await connections.notion.queryView({ viewUrl: "dataSourceUrl" }) ｀｀｀

5) Updating page properties in a data source

To update a page's properties, use connections.notion.updatePage with a propertyUpdates object.

Rules:

• Use property names that match the data source schema.
• To clear a value, set it to null.
• Do not try to set read-only fields like url / createdTime or computed properties.

Examples:

｀｀｀ts await connections.notion.updatePage({ url: "dataSourceUrl", propertyUpdates: { Title: "New title", Status: "In progress", "Is due": true, Points: 5, Tags: ["Important", "Customer"], }, }) ｀｀｀

｀｀｀ts await connections.notion.updatePage({ url: "okrs", propertyUpdates: { "date:Due Date:start": "2025-01-15", "date:Due Date:end": null, "date:Due Date:is_datetime": 0, }, }) ｀｀｀