About data modeling modes

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).

Configure and deploy

About data modeling modes

Why it matters

Additive mode

Rebuild mode

Further reading

​Why it matters

​Additive mode

​Rebuild mode

​Further reading

Why it matters

Additive mode

Rebuild mode

Further reading