NEAT supports two data modeling modes: additive and rebuild. Deployment behavior in Cognite Data Fusion (CDF) depends on which mode you use. Changes are classified into three severity levels:
- SAFE: No impact on existing data or functionality
- WARNING: Allowed with caution (changes may have implications, for example, adding a constraint can cause ingestion pipelines to fail if they don’t comply with the constraint)
- BREAKING: Not applied to CDF
Why it matters
Choosing the right mode protects your data and applications. Additive mode is intended for production environments
where stability is crucial, while rebuild mode is designed for development/sandbox environments where you can iterate quickly
delete and recreate models so you try out and do breaking changes. Rebuild is not suitable for production because
it deletes the containers and data, which can lead to data loss.
The sections below describe each mode and list the allowed and disallowed changes per severity level.
NEAT considers only changes to data model components (DMS schema components) in the same space as the data model. Changes outside that space are ignored to prevent accidental modifications to data models owned or managed by other teams.
Additive mode
Additive mode provides:
- Forward compatibility: Existing applications work with the updated model without changes.
- Incremental deployment: Changes apply gradually for controlled evolution.
- Production suitability: Best for production environments where stability and forward compatibility matter.
The table below lists allowed and disallowed changes in additive mode:
| Severity | Operation | Change description | Example |
|---|
| SAFE | Create | Data model | - |
| SAFE | Create | View | Entire views, new properties, filters |
| SAFE | Create | Container | Entire containers, new properties, indexes and constraints |
| SAFE | Create | New enums to existing enum properties | - |
| SAFE | Update | Data model metadata | Name, description, version |
| SAFE | Update | Data model’s view order | - |
| SAFE | Update | View metadata | Name, description, version |
| SAFE | Update | Container metadata | Name, description |
| SAFE | Update | Property metadata | Name, description |
| SAFE | Update | Enums metadata | Name, description |
| WARNING | Update | View filters | - |
| WARNING | Update | Edge type | - |
| WARNING | Update | Source property for reverse connection | Also known as through in CDF API |
| WARNING | Remove | Container constraints | - |
| WARNING | Remove | Container indexes | - |
| WARNING | Update | Mutability of container properties | - |
| WARNING | Update | Auto-increment of container properties | - |
| WARNING | Update | Default value of container properties | - |
| WARNING | Update | Max count of listable properties | - |
| WARNING | Remove | Container property unit | Removing meter from a property |
| WARNING | Add | Container property unit | Adding meter to a property that did not have a unit before |
| BREAKING | Delete | Existing data model | - |
| BREAKING | Delete | View reference from the data model | - |
| BREAKING | Delete | Existing view | - |
| BREAKING | Add | Implements to an existing view | - |
| BREAKING | Delete | Property from an existing view | - |
| BREAKING | Update | Mapping of view (property) to container (property) | - |
| BREAKING | Update | Direct/reverse connection value type | Also known as source in CDF API |
| BREAKING | Update | Edge source of properties | Setting new view as source of properties |
| BREAKING | Update | Edge direction | - |
| BREAKING | Update | Connection type | From edge to direct connection |
| BREAKING | Update | What container is used for | Switching usedFor from node to edge |
| BREAKING | Update | Value type of container property | From text to integer |
| BREAKING | Update | Container constraint definitions | uniqueness constraint property bySpace cannot be changed |
| BREAKING | Update | Container index definitions | Adding or removing properties to which the index applies |
| BREAKING | Update | Nullability of container properties | - |
| BREAKING | Update | Container property unit | Changing from meter to kilometer |
| BREAKING | Update | maxTextSize of text properties | - |
| BREAKING | Delete | Enum values from existing enum properties | - |
Rebuild mode
Rebuild mode allows every change because the entire model is deleted and recreated. Use it for development or testing where no existing data or applications depend on the model. Deployment fails if containers contain data—NEAT does not remove data accidentally.
To delete existing data intentionally, set drop_data=True when deploying: neat.physical_data_model.write.cdf(dry_run=False, drop_data=True).
Further reading
