When your database schema changes

Astrato semantic layers refer to tables, columns, and database functions in your data connection. If one of those database objects changes after the semantic layer was created, the Semantic Layer Editor checks the referenced sources and helps you repair the draft before it can affect published content.

What Astrato checks

When you open a remotely stored semantic layer, Astrato starts a background source check unless a check of the same referenced sources ran within the last hour, even if it did not complete. You can click the source status icon in the header to run a fresh check at any time. A manual check ignores the one-hour reuse interval.

Astrato checks only database objects already used by the semantic layer. New tables or columns are not imported automatically.

Field names and physical source names are case-sensitive. YEAR and Year remain separate columns, including when a field has a different semantic name or display label. Source checks and table rebinding match the physical source exactly. A change in case is a possible rename to review; Astrato does not silently change the stored source spelling.

What happens after a change

• Changed column datatypes are applied to a new semantic-layer draft revision. Return types that can be determined safely are recalculated. The change is never published automatically.
• A confirmed missing table or column remains visible and is marked as missing. Publishing is blocked so you can use validation and lineage to find and repair affected dimensions, measures, joins, and filters.
• If Astrato cannot tell whether an object was removed or your current credentials cannot see it, the result is Sources unverified. Astrato does not mark the object as deleted or alter the draft.
• If the metadata service is busy or rate-limits a large check, affected tables also remain unverified. They are not reported as missing, and another check can retry them later.
• Database functions are listed as not checked.

The check continues in the backend if you close the browser. Its result is available when the next authorized user opens the semantic layer. Astrato does not store your OAuth token or other database credentials for later checks.

A table marked Not listed in the data picker is different: the connection’s table list left it out. When you looked it up by its exact name, its columns were read, so it exists and nothing needs repairing. When it is marked only because a table in your model reads it, nothing has checked it yet: look it up by its exact name, or run the source check, to find out whether it is still there.

BigQuery reports a missing table

When BigQuery reports that a source table was not found, the source check names the physical table in the issue and marks the semantic table as missing, including strikethrough styling in the table browser. Your table definition and fields remain in the model so you can repair the reference. Check whether the table was removed, moved, or renamed, and verify the connection’s access. A permission error or a timeout remains unverified rather than marking the table missing.

Repairing a missing source

First decide whether the object was removed, renamed, or hidden by database permissions.

1. If the object should still exist, restore it or correct the user’s database access, then run the source check again.
2. If a table was renamed, open the broken table and choose its replacement source table or schema. Astrato keeps the semantic table name and does not delete unmatched semantic fields.
3. If a column was renamed, open the broken field and select the replacement source column. Astrato updates the physical source and datatype while keeping the semantic field name and references.
4. If the object was intentionally removed, use validation and lineage to repair its dependants, then remove the obsolete semantic object.
5. Resolve all remaining validation errors before publishing the new revision.

Changing a database object back to its previous name and datatype also repairs it: restore the database object, run a fresh check, and Astrato clears the missing marker after verification.