Skip to main content
When your database schema changes — new tables, renamed columns, removed schemas — your Omni model can fall out of sync. Run a schema refresh to tell Omni about those changes.

​
Requirements

To trigger schema refreshes, you’ll need Modeler or Connection Admin permissions:
  • Modelers can perform schema refreshes on connections with exactly one shared model
  • Connection Admins can refresh schemas on any connection they are an admin of, whether the connection has one or multiple models
Refreshes to multi-model connections affect every shared model on the connection, so they can only be triggered by Connection Admins.

​
Types of schema refreshes

There are two types of schema refreshes: hard and soft.

​
Triggering schema refreshes

Schema refreshes can be triggered manually or automated on a schedule. Kicking off a refresh starts a background job that can take several minutes depending on the size of the database.

​
Manually

Schema refreshes can be triggered on an as-needed basis from the model IDE, from a connection’s settings page, or with the API.
1

Open the model IDE

Navigate to the model IDE.
2

Open the refresh schema dialog

Click Model > Refresh schema.
3

Choose hard or soft refresh

  • Hard refresh of the entire model: leave the schema and table fields blank.
  • Soft refresh of specific schemas and tables: add the objects you want to refresh, individually or with wildcard syntax (e.g., sales_*).
4

Trigger the refresh

Click Refresh schema.
1

Open the connection settings

Navigate to Settings > Connections and open the connection.
2

Open the refresh schema dialog

Click Refresh now.
3

Choose hard or soft refresh

  • Hard refresh of the entire model: leave the schema and table fields blank.
  • Soft refresh of specific schemas and tables: add the objects you want to refresh, individually or with wildcard syntax (e.g., sales_*).
4

Trigger the refresh

Click Refresh schema.
Use the Refresh schema endpoint to manually trigger a refresh.

​
On a schedule

Scheduled refreshes don’t currently support selectively refreshing schemas and tables.
Use scheduled refreshes to automatically pull database changes into your Omni model. You can create refresh schedules in Omni on a connection’s settings page or with the API.
1

Open the connection settings

Navigate to Settings > Connections and open the connection.
2

Open the refresh schedule dialog

Click Create schedule.
3

Define the schedule

Enter a cron string to define the schedule.
Omni uses Amazon Web Services (AWS) syntax for cron expressions. Refer to the AWS documentation for more information and examples.
If your organization has AI enabled, you can use the AI cron generator to create cron expressions from natural language. Click the sparkle icon next to the cron input field and describe your desired schedule, such as “every day at 6am” or “every Monday and Thursday at midnight.”
4

Choose hard or soft refresh

Optional. By default, scheduled refreshes perform soft refreshes. Check the Hard refresh option to create a schedule that discards the existing schema model and rebuilds it from scratch.
5

Create the schedule

Click Schedule.
Use the Create schema refresh schedule endpoint to programmatically create a schedule, and the Update schema refresh schedule to modify it.

​
Requiring branches for schema refreshes

Branch-based schema refreshes can’t be enabled if a connection has multiple models or if connection environments (dynamic connections) are currently in use.
If you prefer to review schema changes before they impact the shared model, enable the connection’s Branch based schema refresh setting. This will force schema refreshes to be performed in an Omni branch before they can be promoted to the shared model. When this setting is enabled:
  • On-demand and scheduled refreshes will be disabled
  • Schema refreshes can only be triggered from the IDE. If you’re not in an existing branch, selecting Model > Refresh schema will prompt you to create a branch first.
  • Only one shared model can exist on the connection. This is enforced continuously, not just at the time you enable the setting. If you try to create a second model using the same connection, it will appear as unavailable in the model creation flow. This restriction exists because a connection’s schema is a single shared resource. Branch-based schema refresh routes schema changes through one model’s branch/pull request workflow, and that only resolves accurately when there is exactly one shared model on the connection. This restriction also applies if Require for system syncs is enabled, as this setting requires branch-based schema refreshes.
    If you need two independently git-managed models backed by the same database, create a second connection pointing at the same database. Each connection gets its own schema and its own single-model branch-based schema refresh pipeline.

​
Resolving broken references

Changes made as a result of a schema refresh may result in broken references in Omni. Use the Content Validator to identify and resolve any issues. If you need to update references after renaming tables in your database, use table migration.