Alpha flags - Cognite Docs

Alpha flags enable experimental Cognite Toolkit behavior that may change or be removed without notice. Enable them only after testing and when you’re willing to accept breaking changes. Product release status for Cognite Data Fusion is described in release states and availability; toolkit flags are a separate CLI mechanism.

The Cognite Toolkit uses alpha flags to enable experimental functionality that we often plan to support in the next minor release. By default, alpha flags aren’t enabled. To enable them, you must update the cdf.toml file. For example, to enable the alpha-rules alpha flag, add the following to your cdf.toml file:

[alpha_flags]
alpha-rules = true

Cognite Toolkit versioning and releases

The Cognite Toolkit uses semantic versioning to manage versions as major, minor, and patch (for example, 0.3.17).

A major version increases with breaking changes in the CLI or the format of modules and configuration files. Installing a new major toolkit version may require updating your configuration files or modules.
Minor versions increase with new features and patch versions with bug fixes.

As long as the major version is 0, breaking changes may happen between minor versions. Introducing new functionality in stable versions can lead to new bugs. Alpha flags allow you to selectively enable new functionality, minimizing the risk of introducing new bugs. The state of alpha flags varies, with some planned for future releases and others being experimental, requiring further testing.

Alpha flag: alpha-rules

Status: experimental Available from: 0.8.213

[alpha_flags]
alpha-rules = true

When you run cdf build, the Cognite Toolkit validates the configurations against a set of rules. For example, one rule requires that all referenced resources are part of the build or already exist in CDF. If a view references a container, the Cognite Toolkit checks that the container is part of the build or already exists in CDF. New rules are added over time and become part of a stable minor release. The alpha-rules flag lets you turn those rules on before that release so you can test your configurations.

Alpha flag: import-cmd

Status: experimental

[alpha_flags]
import-cmd = true

This flag enables the cdf import command. The only subcommand available is transformation-cli. The command converts the transformation-cli manifest files to the Cognite API (Toolkit) format. Use this, for example, if you have transformations managed by the transformation-cli and want to convert them to the Cognite Toolkit format.

Alpha flag: infield

Status: experimental Available from: 0.5.10

[alpha_flags]
infield = true

This flag enables the infield configuration resource. See cdf.toml for more information about the infield configuration resource.

Alpha flag: migrate

Status: experimental Available from: 0.5.45

[alpha_flags]
migrate = true

This flag enables the cdf migrate command. This command enables you to migrate asset-centric resources, Charts, Canvas, legacy InField config / data, 3D models, and legacy 360° Images to the Cognite Core Data Model (CDM). See the Migration plugin section for more information about its capabilities and limitations.

Alpha flag: records-migrate

Status: experimental Available from: 0.7.239

[alpha_flags]
records-migrate = true

This flag enables the cdf migrate events-to-records command. This command enables you to migrate events to records in CDF. See the Migration plugin section for more information about its capabilities and limitations.

Alpha flag: infield-location-split

Status: experimental Available from: 0.8.187

[alpha_flags]
infield-location-split = true

This flag enables location-split in the cdf migrate infield-data and cdf migrate infield-source-data commands. Location-split separates InField data migration so you can untangle shared legacy instance spaces.

Alpha flag: create

Status: experimental Available from: 0.7.3

[alpha_flags]
create = true

This flag enables the create subcommand under the dev plugin, which allows you to create resource YAML files from the CLI. To use this subcommand, you need to enable the dev plugin. Once enabled, you can create resource YAML files with cdf dev create. To get more information about the subcommand, use the --help flag.

cdf dev create --help

Alpha flag: data-products

Status: experimental Available from: 0.7.207

[alpha_flags]
data-products = true

This flag enables data product resources, rule sets, and rule set versions in the Cognite Toolkit. When enabled, you can add data_products/ YAML files for DataProduct and DataProductVersion. You can also add rulesets/ YAML files for RuleSet and RuleSetVersion. Then build and deploy the files with cdf build and cdf deploy.

Alpha flag: custom-apps

Status: experimental Available from: 0.8.82

[alpha_flags]
custom-apps = true

This flag enables App and AppVersion resource types for deploying Cognite Flows custom apps via the CDF app-hosting API. When enabled, add YAML files under apps/ and deploy them with cdf build and cdf deploy. See the YAML Reference Library for configuration details.

Alpha flag: api

Status: experimental Available from: 0.8.202

[alpha_flags]
api = true

This flag enables a new command cdf api that allows you to run API calls against CDF directly from the CLI.

Alpha flag: modules-list-json

Status: experimental Available from: 0.7.107

[alpha_flags]
modules-list-json = true

This flag enables the --format flag to the cdf modules list command, with this flag you can output json instead of the default table format. This is useful for machine-readable output.

Alpha flag: cdf-group-emails

Status: planned for 0.10.0

[alpha_flags]
cdf-group-emails = true

This flag enables you to specify members by email address in a CDF group resource. When you enable this flag, you set the following in your your.Group.yaml file:

name: your-group
...
members: emails
memberEmails:
- bob@cognite.com
- alice@cognite.com

The Cognite Toolkit will then resolve the email addresses to the CDF user IDs when you run cdf deploy.

Alpha flag: multi-configs

Status: experimental Available from: 0.9.9

[alpha_flags]
multi-configs = true

This flag lets cdf build read several config.[env].yaml files. Pass --config-yaml once for each file. For example:

cdf build --config-yaml config.siteA.yaml --config-yaml config.shared.yaml

Each config file must use the same environment.project and environment.validation-type. These fields are described in the environment section of config.[env].yaml. variables and environment.selected stay separate in each file, so you can build the same module with different variable values. Use several config files for one CDF project to keep each config.[env].yaml smaller and easier to maintain. For more information, see Building multiple config files.

Alpha flag: config-include

Status: experimental Available from: 0.9.70

[alpha_flags]
config-include = true

This flag lets one config.[env].yaml file list other configuration YAML files in include. The Cognite Toolkit merges those files into the file that lists them. Use include to merge files into one configuration. Use multi-configs when each file should keep its own environment.selected and variables. The Cognite Toolkit applies these rules:

environment.selected is the union of the modules listed in selected across all files.
Any other environment field must match the main file wherever an included file sets it. An included file can omit environment when it only defines variables.
The Cognite Toolkit merges variables mappings. Nested mappings combine, so each file can add its own keys. Setting the same key path in more than one file is an error.

Each path in include is relative to the directory of the file that lists it. The path must be a .yaml or .yml file in that directory or a subdirectory. For example, define shared variables in a separate file without an environment section:

config.shared.yaml

variables:
  shared_variable: value

Then include that file in your environment configuration file:

config.dev.yaml

include:
  - config.shared.yaml

environment:
  name: dev
  project: my-dev-project
  validation-type: dev
  selected:
    - modules/core/

For more information, see Including configuration files.

Alpha flag: git-diff-select

Status: experimental Available from: 0.9.21

[alpha_flags]
git-diff-select = true

This flag lets you select modules to build and deploy from your Git history. When enabled, set selection-type: git-diff, set validation-type to dev, set deploy-branch, and specify selected modules in your config.[env].yaml file. The Cognite Toolkit requires environment.selected to be set and only builds modules that are an intersection between the environment.selected modules and the changed modules detected by git diff. The Cognite Toolkit accepts selection-type: git-diff only when validation-type is dev. For more information, see Selecting changed modules with git diff.

Alpha flag: deploy-protection

Status: experimental Available from: 0.9.26

[alpha_flags]
deploy-protection = true

This flag puts a lock on each module so team members deploy that module one at a time. When enabled, set deploy-protection: protected and set deploy-branch in your config.[env].yaml file. For more information, see Protecting deployments from concurrent overwrites.

Alpha flag: neat

Status: experimental Available from: 0.9.50

[alpha_flags]
neat = true

This flag enables support for NEAT format in data models. When enabled, you can add .NEAT.yaml files under data_modeling/. To learn more about the NEAT format, see NEAT format for data models.

Alpha flag: v010

Status: experimental Available from: 0.9.23

[alpha_flags]
v010 = true

This flag enables all features planned for Cognite Toolkit version 0.10.0. Features planned for 0.10.0 are continuously added to this flag as they are developed. Currently, enabling v010 includes the following:

CDF groups by email: Enables specifying members by email address in CDF group resources (same functionality as cdf-group-emails).
Container index and constraint updates: Supports deleting and modifying container indexes and constraints. The Cognite Toolkit deletes and recreates modified indexes and constraints.
Removal of --drop and --drop-data flags: Removes --drop and --drop-data from cdf deploy. Use cdf clean instead.
Replacement of cdf repo with cdf init: Removes the cdf repo command and replaces it with cdf init.

​Cognite Toolkit versioning and releases

​Alpha flag: alpha-rules

​Alpha flag: import-cmd

​Alpha flag: infield

​Alpha flag: migrate

​Alpha flag: records-migrate

​Alpha flag: infield-location-split

​Alpha flag: create

​Alpha flag: data-products

​Alpha flag: custom-apps

​Alpha flag: api

​Alpha flag: modules-list-json

​Alpha flag: cdf-group-emails

​Alpha flag: multi-configs

​Alpha flag: config-include

​Alpha flag: git-diff-select

​Alpha flag: deploy-protection

​Alpha flag: neat

​Alpha flag: v010

Cognite Toolkit versioning and releases

Alpha flag: alpha-rules

Alpha flag: import-cmd

Alpha flag: infield

Alpha flag: migrate

Alpha flag: records-migrate

Alpha flag: infield-location-split

Alpha flag: create

Alpha flag: data-products

Alpha flag: custom-apps

Alpha flag: api

Alpha flag: modules-list-json

Alpha flag: cdf-group-emails

Alpha flag: multi-configs

Alpha flag: config-include

Alpha flag: git-diff-select

Alpha flag: deploy-protection

Alpha flag: neat

Alpha flag: v010