Alpha flags reference

Alpha flags let you enable and try new Neat features while they are in early access, before they’re promoted to stable Neat releases without the flag. New features are released in minor versions (for example 1.2, 1.3); alpha flags can be released in patch versions (for example 1.2.1, 1.2.2).

Do not use alpha flags in production without thorough testing. The features they enable are not stable and may behave unexpectedly, change without notice, or be removed in future releases.

`enable_experimental_validators`

New validation rules in Neat are first released as experimental validators. This flag gives you early access to all of them.

from cognite.neat import NeatSession, NeatConfig, get_cognite_client

# Create client and config
client = get_cognite_client(".env")
config = NeatConfig.create_predefined()

# Enable the alpha flag
config.alpha.enable_experimental_validators = True

neat = NeatSession(client, config)

neat.physical_data_model.read.excel("my_data_model.xlsx")

# Experimental validator findings appear alongside standard findings
neat.issues

`enable_fix_validation_issues`

Neat can automatically fix issues reported by performance validators (NEAT-DMS-PERFORMANCE-XXX). This flag turns that on so Neat applies fixes during the read operation. You must also enable enable_experimental_validators, because these validators are still experimental.

Set config.alpha.enable_experimental_validators = True as well when using enable_fix_validation_issues.

from cognite.neat import NeatSession, NeatConfig, get_cognite_client

# Create client and config
client = get_cognite_client(".env")
config = NeatConfig.create_predefined()

# Enable the alpha flags (both are required for fix functionality)
config.alpha.enable_experimental_validators = True
config.alpha.enable_fix_validation_issues = True

neat = NeatSession(client, config)


neat.physical_data_model.read.excel("my_data_model.xlsx", fix=True)

In the preceding code, Neat automatically fixes any performance validation issues as it reads my_data_model.xlsx. For example, for reverse direct relationships Neat adds an index on the target so reverse lookups perform well in Cognite Data Fusion (CDF).

`enable_solution_model_creation`

Many organizations use one main data model as the source of truth for shared concepts. For a specific use case or project you can create a solution model that references the main model but includes only the concepts you need. The .create() method does that: it creates a new model that references an existing one. For example, to create a solution model with only assets and time series from the CogniteCore data model:

from cognite.neat import NeatSession, NeatConfig, get_cognite_client

# Create client and config
client = get_cognite_client(".env")
config = NeatConfig.create_predefined()

# Enable the alpha flag
config.alpha.enable_solution_model_creation = True

neat = NeatSession(client, config)

# With this flag enabled, you can create a solution model from an existing model.
# Use the Neat syntax for referencing views in the data model: <space>:<externalId>(version=<version>).
neat.physical_data_model.create(
    space="cdf_cdm",
    external_id="CogniteCore",
    version="v1",
    views=["cdf_cdm:CogniteAsset(version=v1)", "cdf_cdm:CogniteTimeSeries(version=v1)"]
)

# Writing the new model to file.
neat.physical_data_model.write.excel("my_solution_model.xlsx")

When you run the preceding code, Neat creates a new data model and writes it to my_solution_model.xlsx. The new model includes only the CogniteAsset and CogniteTimeSeries views from CogniteCore. Properties that reference view types outside that selection are excluded.

`enable_cdf_analysis`

Neat is used for data model development and can also analyze the data models in your CDF project. The following code runs an analysis of all data models and data modeling resources in the project your NeatSession is connected to.

from cognite.neat import NeatSession, NeatConfig, get_cognite_client

# Create client and config
client = get_cognite_client(".env")
config = NeatConfig.create_predefined()

# Enable the alpha flag
config.alpha.enable_cdf_analysis = True

neat = NeatSession(client, config)

# neat.cdf is now available
neat.cdf.analyze()

neat.issues

For example, Neat reports empty spaces — spaces with no containers, views, data models, or instances.

`enable_datamodel_file_selection`

Neat expects one data model when reading into a NeatSession. When reading YAML from a directory (Cognite Toolkit format), the directory may contain multiple data model files. This flag lets you choose which one to read by passing its path to the data_model_file parameter of read.yaml().

from cognite.neat import NeatSession, NeatConfig, get_cognite_client
from pathlib import Path

# Create client and config
client = get_cognite_client(".env")
config = NeatConfig.create_predefined()

# Enable the alpha flag
config.alpha.enable_datamodel_file_selection = True

neat = NeatSession(client, config)

# Specify the data model YAML file explicitly
neat.physical_data_model.read.yaml(
    "my_module/data_modeling",
    format="Toolkit",
    data_model_file=Path("my_module/data_modeling/my_selected.DataModel.yaml")
)

The preceding code reads YAML from the my_module/data_modeling directory, which contains multiple DataModel YAML files. The data_model_file parameter selects which file to read. Without this flag, Neat throws an error when a directory contains more than one DataModel YAML file.

`enable_governed_spaces`

Neat expects containers and views to be in the same space as their data model. On deploy, it skips any containers or views that are in a different space. When you read and validate a data model, Neat checks CDF and flags containers or views that live in another space. Enable enable_governed_spaces to include containers and views from other spaces. Then add the governedSpaces key to the Metadata sheet in your spreadsheet. For example, you can add the following key-value pairs to the Metadata sheet.

Key	Value
space	my_space
externalId	my_data_model
version	v1
governedSpaces	my_other_space,yet_another_space

With this Metadata sheet in my_data_model.xlsx, run the following code. Neat finds containers and views in my_other_space and yet_another_space and adds them to the deployment plan when you deploy to CDF.

from cognite.neat import NeatSession, NeatConfig, get_cognite_client

# Create client and config
client = get_cognite_client(".env")
config = NeatConfig.create_predefined()

# Enable the alpha flag
config.alpha.enable_governed_spaces = True

neat = NeatSession(client, config)

neat.physical_data_model.read.excel("my_data_model.xlsx")

# Neat checks containers and views in governedSpaces against the local model,
# and includes them in the deployment plan
neat.physical_data_model.write.cdf()

Governed spaces help you control who can see which views and containers. For example, you might have an Enterprise data model with all shared concepts and want the data available across the organization, but not every view. Create a solution model per user group that references only the relevant containers from the Enterprise model, and give users access to that solution model instead. Take an asset view in the Enterprise model. An operator might need only a subset of its properties. If they could see both the Enterprise and solution views for that asset, they might be confused. Give them access only to the solution view so they see just the properties they need while still using the underlying Enterprise data.

`enable_plugins`

Enable external plugins to extend Neat’s functionality with custom external plugins for data model reading. When enabled, Neat discovers and loads plugins from installed packages via entry points. Plugins allow you to add custom import methods to the ReadPhysicalDataModel class dynamically.

from cognite.neat import NeatSession, NeatConfig, get_cognite_client

# Create client and config
client = get_cognite_client(".env")
config = NeatConfig.create_predefined()

# Enable the alpha flag
config.alpha.enable_plugins = True

neat = NeatSession(client, config)

# If you have installed a demo plugin: (e.g., neat-excel-plugin,
# https://github.com/cognitedata/neat/tree/main/scripts/external_plugin
# a custom reader method is automatically attached to:
neat.physical_data_model.read.external_excel("my_data_model.xlsx", fix=True)

Creating a plugin requires implementing a dedicated interface and packaging it as a Python package. Here’s an example:

# __init__.py

from pathlib import Path
from typing import ClassVar

# Plugin interface that every external plugin must implement
from cognite.neat._plugin_adapter import PhysicalDataModelReaderPlugin
from cognite.neat._data_model.importers import DMSTableImporter

class ExternalDataModelReaderPlugin(PhysicalDataModelReaderPlugin):
    """Real ExcelDataModelImporter implementation for testing."""
    method_name: ClassVar[str] = "external_excel"

    def configure(self, io: str) -> DMSTableImporter:
        """
        Configures Excel importer.

        Args:
            io (str): Path to the Excel file.
        """
        return DMSTableImporter.from_excel(excel_file=Path(io))


__all__ = ["ExternalDataModelReaderPlugin"]

Make sure to add necessary entry points in pyproject.toml:

...

[project.entry-points."cognite.neat.plugin.data_model.readers"]
external_excel = "my_plugin:ExcelDataModelImporterPlugin"

...

Install your plugin with pip install -e . or uv pip install -e .. Neat will automatically discover and attach it to ReadPhysicalDataModel.

Deploy

`enable_experimental_validators`

`enable_fix_validation_issues`

`enable_solution_model_creation`

`enable_cdf_analysis`

`enable_datamodel_file_selection`

`enable_governed_spaces`

`enable_plugins`

Further reading

​enable_experimental_validators

​enable_fix_validation_issues

​enable_solution_model_creation

​enable_cdf_analysis

​enable_datamodel_file_selection

​enable_governed_spaces

​enable_plugins

​Further reading

`enable_experimental_validators`

`enable_fix_validation_issues`

`enable_solution_model_creation`

`enable_cdf_analysis`

`enable_datamodel_file_selection`

`enable_governed_spaces`

`enable_plugins`

Further reading