> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Alpha flags reference

> Complete reference for Neat alpha feature flags that enable experimental and early-access functionality.

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

<Warning>
  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.
</Warning>

## `enable_experimental_validators`

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

```python wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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.

<Note>
  Set `config.alpha.enable_experimental_validators = True` as well when using `enable_fix_validation_issues`.
</Note>

```python wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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:

```python wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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.

```python wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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()`.

```python wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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.

```python wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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.

```python wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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:

```python wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
# __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`:

```toml theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
...

[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`.

## Further reading

* [NeatConfig reference](/cdf/deploy/neat/reference/config) — Configure your Neat session with data modeling modes and validation rules.
* [Validation rules](/cdf/deploy/neat/validation/index) — Reference for all available validation rules.
* [NeatSession reference](/cdf/deploy/neat/reference/session) — Main interface for working with Neat.