Schema Versions
Data Share tables are organized into versioned schemas (e.g. v1_0). Each
version defines a stable contract — the set of tables, columns, and their data types.
Your queries reference a specific schema version, allowing you to gradually adopt the new version.
What Changes Without a New Version
The following changes can happen within an existing schema version and will not break your
queries:
- New columns added to existing tables
- New tables added to the schema
- Bug fixes to column values (e.g. correcting a calculation)
What Triggers a New Version
A new schema version is released when a change would break existing queries:
- Removing a column from a table
- Renaming a column
- Changing a column’s data type
- Changing row granularity (e.g. a table starts returning more rows per entity)
- Changing the meaning of a column’s values (e.g. a score changing from 0–100 to 0.0–1.0)
When this happens, a new schema version is created and the previous version continues to work
during a deprecation period.
Schema changes announcements
Schema changes will be published as a change log in the documentation website, along with email comminication.
Deprecation Policy
When a schema version is deprecated:
| Step | What Happens | Timeline |
|---|
| Announcement | Deprecation notice communicated with migration guidance | Day 0 |
| Overlap period | Both old and new versions are available and kept up to date | 30 days |
| Frozen period | Deprecated version is retained but no longer refreshed with new data | 30 days |
| Removal | Deprecated version is removed | After 60 days |
Once the frozen period begins, the deprecated schema version will stop receiving data
updates. Migrate your queries to the new version before the frozen period starts to avoid
working with stale data.
Column Deprecation
Individual columns may also be deprecated within a version. When a column is deprecated:
- The column continues to return data during the deprecation period.
- A notice is published in the documentation change log.
- After 30 days, the column may return
NULL or be removed in the next schema version.
