Config

Configuration data classes exported from cognite_data_quality for validation and deployment:

• DataModelConfig — identifies a CDF data model (space, external_id, version)
• RecordsConfig — configures Records API output (stream_id, rule_set_id, rule_set_version)
• DeploymentSettings — loaded from settings.yaml for deployment

Pass DataModelConfig and RecordsConfig to run_validation(). DeploymentSettings is used by deploy_validation_infrastructure() and can also be loaded manually with load_settings().

See Config (TOML and view config) for credentials and view YAML. For how rules are stored, see Rule sources.

cognite_data_quality.DataModelConfig

Bases: BaseModel

Identifies a CDF Data Model used during instance validation.

Attributes:

Name	Type	Description
space	str	CDF space that contains the data model.
external_id	str	External ID of the data model.
version	str	Version string of the data model.

Source code in cognite_data_quality/_config.py

class DataModelConfig(BaseModel):
    """Identifies a CDF Data Model used during instance validation.

    Attributes:
        space: CDF space that contains the data model.
        external_id: External ID of the data model.
        version: Version string of the data model.
    """

    space: str
    external_id: str
    version: str

cognite_data_quality.RecordsConfig

Bases: BaseModel

Records API coordinates and rule set metadata for a validation run.

Attributes:

Name	Type	Description
stream_id	str | None	External ID of the Records API stream to ingest into. Set to None to skip Records API ingestion.
rule_set_id	str	Identifier for the SHACL rule set being applied (written to every record).
rule_set_version	str	Version string of the rule set (written to every record).
data_domain_external_id	str | None	Optional data domain tag written to each record for filtering in the validation dashboard.
records_space	str	CDF DMS space that hosts the validation records container. Default: "dataQuality".
records_container	str	External ID of the DMS container that stores records. Default: "DataQualityValidationRecord".
use_instance_space	bool	Write each record into the same space as the validated instance instead of records_space. Default: False.
record_space	str | None	Explicit destination space, overriding records_space when use_instance_space is False.

Source code in cognite_data_quality/_records.py

class RecordsConfig(BaseModel):
    """Records API coordinates and rule set metadata for a validation run.

    Attributes:
        stream_id: External ID of the Records API stream to ingest into.
            Set to ``None`` to skip Records API ingestion.
        rule_set_id: Identifier for the SHACL rule set being applied
            (written to every record).
        rule_set_version: Version string of the rule set (written to every
            record).
        data_domain_external_id: Optional data domain tag written to each
            record for filtering in the validation dashboard.
        records_space: CDF DMS space that hosts the validation records
            container. Default: ``"dataQuality"``.
        records_container: External ID of the DMS container that stores
            records. Default: ``"DataQualityValidationRecord"``.
        use_instance_space: Write each record into the same space as the
            validated instance instead of *records_space*. Default: ``False``.
        record_space: Explicit destination space, overriding *records_space*
            when *use_instance_space* is ``False``.
    """

    stream_id: str | None = None
    rule_set_id: str
    rule_set_version: str
    data_domain_external_id: str | None = None
    records_space: str = Field(default="dataQuality")
    records_container: str = Field(default="DataQualityValidationRecord")
    use_instance_space: bool = Field(default=False)
    record_space: str | None = Field(default=None)
    stream_type: str = Field(default="BasicArchive")

cognite_data_quality.DeploymentSettings

Bases: BaseModel

Top-level deployment settings loaded from settings.yaml.

Attributes:

Name	Type	Description
function	FunctionSettings | None	Cognite Function settings. Auto-populated with defaults if omitted from the YAML file.
workflow	WorkflowSettings	Workflow settings for instance validation workflows.
timeseries_workflow	WorkflowSettings | None	Separate workflow settings for time series workflows. Falls back to workflow when None.
trigger	TriggerSettings	Data-change trigger settings for instance validation.
records	RecordsSettings	Default Records API coordinates (space, container, stream).
shacl_rules	ShaclRulesSettings | None	Location settings for SHACL rule files.
timeseries	TimeSeriesSettings | None	Time series config directory settings. None if no time series validation is configured.
rule_engine_result_sync	RuleEngineResultSyncSettings | None	RuleEngineResult listener config directory settings. None if no listener workflows are configured.
partition_retries	int	Maximum partition retry attempts managed by the orchestrator function (no CDF API limit). Default: 3.
function_code_dataset_external_id	str | None	Dataset for function code zip uploads. Required when CDF enforces dataset-scoped file access.
config_source	Literal['dataproduct']	Must be "dataproduct" (only supported value since 0.4.0). Local YAML/TTL files publish to the DataProduct and RuleSet APIs. Each view's dataproducts list controls which DataProducts it is included in. Use external_dataproducts to consume pre-existing DPs.
external_dataproducts	list[ExternalDataProductRef]	Pre-existing DataProducts in CDF (created by others) to deploy validation workflows for. No local view configs or TTL files are needed — the deploy function fetches the DataProduct from CDF and deploys workflows directly.
config_space	str | None	DMS space for state and settings containers (DataQualitySettings, OrchestrationState, etc.). When None (default), falls back to records.space.

Source code in cognite_data_quality/deploy.py

class DeploymentSettings(BaseModel):
    """Top-level deployment settings loaded from ``settings.yaml``.

    Attributes:
        function: Cognite Function settings. Auto-populated with defaults
            if omitted from the YAML file.
        workflow: Workflow settings for instance validation workflows.
        timeseries_workflow: Separate workflow settings for time series
            workflows.  Falls back to *workflow* when ``None``.
        trigger: Data-change trigger settings for instance validation.
        records: Default Records API coordinates (space, container, stream).
        shacl_rules: Location settings for SHACL rule files.
        timeseries: Time series config directory settings. ``None`` if no
            time series validation is configured.
        rule_engine_result_sync: RuleEngineResult listener config directory
            settings. ``None`` if no listener workflows are configured.
        partition_retries: Maximum partition retry attempts managed by the
            orchestrator function (no CDF API limit). Default: 3.
        function_code_dataset_external_id: Dataset for function code zip
            uploads.  Required when CDF enforces dataset-scoped file access.
        config_source: Must be ``"dataproduct"`` (only supported value since 0.4.0).
            Local YAML/TTL files publish to the DataProduct and RuleSet APIs.
            Each view's ``dataproducts`` list controls which DataProducts it is
            included in.  Use ``external_dataproducts`` to consume pre-existing DPs.
        external_dataproducts: Pre-existing DataProducts in CDF (created by
            others) to deploy validation workflows for.  No local view configs
            or TTL files are needed — the deploy function fetches the
            DataProduct from CDF and deploys workflows directly.
        config_space: DMS space for state and settings containers
            (``DataQualitySettings``, ``OrchestrationState``, etc.).
            When ``None`` (default), falls back to ``records.space``.
    """

    function: FunctionSettings | None = None
    workflow: WorkflowSettings
    timeseries_workflow: WorkflowSettings | None = None
    trigger: TriggerSettings
    records: RecordsSettings = Field(default_factory=RecordsSettings)
    shacl_rules: ShaclRulesSettings | None = None
    timeseries: TimeSeriesSettings | None = None
    rule_engine_result_sync: RuleEngineResultSyncSettings | None = None
    partition_retries: int = Field(default=3, description="Orchestrator partition retry limit (no CDF API constraint)")
    function_code_dataset_external_id: str | None = Field(
        default=None,
        description="Dataset for function code uploads. Required if CDF enforces dataset-scoped file access.",
    )
    config_source: Literal["dataproduct"] = Field(
        default="dataproduct",
        description="Config source: publishes SHACL to RuleSet API and views to DataProduct API.",
    )
    external_dataproducts: list[ExternalDataProductRef] = Field(
        default_factory=list,
        description=(
            "Pre-existing DataProducts in CDF to deploy workflows for. "
            "Rules and DataProduct structure must already exist (created externally). "
            "Use version='latest' to auto-pick the newest published version."
        ),
    )
    config_space: str | None = Field(
        default=None,
        description=(
            "DMS space that hosts state and settings containers "
            "(DataQualitySettings, OrchestrationState, FunctionValidationState, etc.). "
            "Defaults to records.space when not set."
        ),
    )
    runtime_credentials: RuntimeCredentialsSettings | None = Field(
        default=None,
        description=(
            "Optional credential groups for runtime resources. "
            "When omitted, deployment client credentials are used as fallback."
        ),
    )
    validation_lock: ValidationLockSettings = Field(default_factory=ValidationLockSettings)
    stream_retention_lead_time: str = Field(
        default="P1D",
        description="ISO-8601 lead time before stream expiry for stream_retention_guard (default P1D).",
    )
    stream_retention_guard_cron: str | None = Field(
        default=None,
        description=(
            "Optional cron override for dq-stream-retention-guard. When omitted, deploy "
            "uses per-project night-window jitter (01:00-04:59 UTC)."
        ),
    )
    atlas_rule_authoring: AtlasRuleAuthoringSettings = Field(
        default_factory=AtlasRuleAuthoringSettings,
        description=(
            "Opt-in Atlas AI rule-authoring agent/skill deploy from the cognite-data-quality wheel. Default disabled."
        ),
    )

    @property
    def effective_config_space(self) -> str:
        """Space for state/settings containers. Falls back to records.space if config_space is unset."""
        return self.config_space or (self.records.space if self.records else "dataQuality")

    @field_validator("config_source", mode="before")
    @classmethod
    def reject_yaml_config_source(cls, value: object) -> object:
        if value == "yaml":
            raise ValueError(
                "config_source: yaml was removed in cognite-data-quality 0.4.0. "
                "Use config_source: dataproduct (default), publish local TTL/view YAML to "
                "RuleSet/DataProduct APIs, and/or list pre-existing DataProducts under "
                "external_dataproducts. See docs/usage/deploy.md and GitHub issue #260."
            )
        return value

    def model_post_init(self, __context) -> None:
        """Ensure function settings are populated with defaults if not provided."""
        if self.function is None:
            self.function = FunctionSettings()

effective_config_space property

Space for state/settings containers. Falls back to records.space if config_space is unset.

model_post_init(__context)

Ensure function settings are populated with defaults if not provided.

Source code in cognite_data_quality/deploy.py

def model_post_init(self, __context) -> None:
    """Ensure function settings are populated with defaults if not provided."""
    if self.function is None:
        self.function = FunctionSettings()