Update data source properties

Add, rename, remove, or change properties in a data source schema.

Use Update a data source to change its schema. This changes the properties for all pages in that data source. To change one page’s values, use Update page.

First, retrieve the data source to get its current property IDs and settings. Choose an operation below and send its JSON body to PATCH /v1/data_sources/{data_source_id}. Your connection needs access to the data source and update content capabilities.

Add a property

Add a new key to properties and provide the type’s settings. This example adds a number and a date property. Existing properties that you omit stay unchanged.

Request body

{
  "properties": {
    "Estimate": { "number": { "format": "number" } },
    "Due date": { "date": {} }
  }
}

See Property schemas for every type and its settings.

Remove a property

Set the property entry to null. This removes the column for all pages in the data source. To clear a value on one page instead, use Update page.

By ID

{
  "properties": {
    "oldP": null
  }
}

Rename a property

Set name on the existing entry. Its ID stays the same. Prefer the ID if another user might rename the property while your connection is running.

By ID

{
  "properties": {
    "estM": { "name": "Hours" }
  }
}

To update a property’s description, include it beside the type’s settings. Omit description to keep the current one, or send null to clear it.

Update property type

Supply the new type’s settings under the existing name or ID.

Change Estimate to a number

{
  "properties": {
    "Estimate": { "number": { "format": "number" } }
  }
}

Changing a type can make existing values unreadable in the new type. Check the change on a test data source first. The Name property (title) cannot be removed or converted. Other properties cannot become title. Place properties cannot be converted to or from another type.

Select configuration updates

Set select.options to the complete list of options you want to keep. Omitted options are removed. New names add options. Omitting options keeps the current list.

Keep High and add Medium

{
  "properties": {
    "Priority": {
      "description": "How soon this work needs attention.",
      "select": {
        "options": [
          { "id": "ff8e9269-9579-47f7-8f6e-83a84716863c" },
          { "name": "Medium", "color": "yellow", "description": "Schedule after high-priority work." }
        ]
      }
    }
  }
}

Existing select options

Use an existing option’s id or name to retain it. Names match without regard to case or surrounding spaces, so high keeps the existing High option. A retained option keeps its ID and name. You can update its color and description. Omitting either keeps the current value, and null clears the description. The API does not rename existing options; rename them in Notion. New options accept name, optional color, and optional description. See Option fields.

Multi-select configuration updates

Set multi_select.options using the same rules as select. Include every option to retain. This changes the available tags, not the tags selected on one page.

Keep High and add Launch

{
  "properties": {
    "Tags": {
      "description": "Labels used to organize work.",
      "multi_select": {
        "options": [
          { "id": "ff8e9269-9579-47f7-8f6e-83a84716863c" },
          { "name": "Launch", "color": "blue" }
        ]
      }
    }
  }
}

Existing multi-select options

Existing options follow the same ID, name, color, and description rules.

Status configuration updates

Set status.options to the complete list to retain. Use group to place an option in To-do, In progress, or Complete.

Keep In progress and add Shipped

{
  "properties": {
    "Status": {
      "status": {
        "options": [
          { "id": "330aeafb-598c-4e1c-bc13-1148aa5963d3", "group": "In progress" },
          { "name": "Shipped", "color": "green", "group": "Complete" }
        ]
      }
    }
  }
}

Existing status options

Existing options follow the same ID, name, color, and description rules. When you omit group, an existing option keeps its group. A new option uses To-do if that group exists, or the first existing group otherwise.

Removed options are also removed from their groups. To rename, reorder, or change the groups themselves, use Notion. To select an option on a page, write the page’s status value.

Limitations

Keep schema changes within the schema size limit. Changes to synced data sources are restricted. Share related databases with the connection before configuring relations or rollups.

After a change, retrieve the data source again and check the returned names, IDs, and settings. Read a sample page if you changed a property’s type.