Skip to main content

​
Overview

When your source data changes, Permutive can detect and apply certain types of schema updates to existing imports. This guide explains how to action those updates — including adding new columns — and how to resolve common schema-related errors.
Prerequisites:
  • An active Connectivity source connection
  • An existing import configured against that source
  • Access to Sources > Imports in the Permutive Dashboard

​
Supported Schema Changes

Not all schema changes can be applied to an existing import. Before actioning an update, check whether your change is supported.
Supported changes:
  • Adding new columns to an existing source schema
  • Widening a column’s data type (e.g. expanding the range or precision of a type)
Not currently supported:
  • Removing or deleting columns
  • Renaming columns
  • Narrowing a column’s data type
  • Changing the order of columns
If you’ve made an unsupported change, either revert to the previous working version, or create a new import from that table — you can delete the existing import if it’s no longer needed. See Troubleshooting below.

​
Steps

1

Trigger a schema refresh

Permutive automatically checks for schema changes when a connection is resynced or when a new import is created. If the change hasn’t been detected yet, trigger a manual refresh:
  1. Go to Sources > Imports
  2. Select the relevant import
  3. On the import details page, click Refresh
The refresh status will show as In Progress, Completed, or Error on the import details page.
2

Review and accept the detected changes

Once new columns are detected, a notification or banner will appear on the import details page.
  1. Open the change details to view the new columns available
  2. Accept the columns you want to bring into Permutive, or dismiss the notification if no action is needed
You don’t need to accept all new columns. Select only those relevant to your use case, or dismiss the notification entirely if none are needed.
3

Verify the import

After accepting changes, allow time for data to be ingested against the new columns. Check the import details page to confirm the update completed successfully.If data isn’t appearing after a reasonable period, see Troubleshooting below.

​
Troubleshooting

  1. Check the resync status — on the import details page, confirm whether the resync shows as Completed, In Progress, or Error. If still in progress, wait before taking further action.
  2. Wait for ingestion — data can take some time to appear after a schema update is applied.
  3. Check your source — confirm the new columns are present and correctly defined in your data warehouse or lake.
  4. Check for unsupported changes — if you’ve also renamed or removed a column, this may be blocking the update.
  1. Check the resync status — look for an error on the import details page. The error message should indicate the type of issue.
  2. Check your source schema — verify the columns are correctly defined in your data warehouse tool.
  3. Revert and re-apply — revert the change at source, re-apply it, then trigger a refresh or resync in Permutive.
  4. Check for unsupported changes — confirm you haven’t also made a change listed under Supported Schema Changes.
Solution: If none of the above resolves the issue, contact Permutive Support with the error message and the name of the affected import.
Narrowing a column’s data type is not supported on an existing import.Solution:
  1. Apply the updated schema to a new table in your warehouse
  2. Delete the existing import in Permutive (if it’s no longer needed, as this will impact associated cohorts)
  3. Create a new import pointing to the new table
Note: widening a column type is supported and can be accepted via the schema change flow above.
Removing columns is not currently supported on an existing import.Solution:
  1. Delete the existing import in Permutive (if it’s no longer needed, as this will impact associated cohorts)
  2. Create a new import against the updated schema
Permutive has detected a mismatch between the schema it has on record and what it can read from your source.Solution: Revert any recent changes made to the schema in your data warehouse, then trigger a resync from the import details page. If the resync status shows as Error, contact Permutive Support.
The source table or schema this import points to can no longer be found.Solution:
  1. Review the change in your warehouse and restore or recreate the table or schema as needed
  2. If needed, delete the import in Permutive and create a new one pointing to the correct location
Solution:
  1. Revert any recent changes at source
  2. Re-apply the changes
  3. Trigger a resync in Permutive from the import details page
If the issue persists, delete the import and create a new one. Contact Permutive Support if the error continues.

​
Next Steps

Sources Overview

Learn more about managing source connections and schemas

Creating an Import

Set up a new import from a source connection