{"record":{"id":"5f6537aeeee5f99d","repo":"dbt-labs/dbt-core","slug":"strategy-strategy-requires-a-non-empty-unique","errorCode":null,"errorMessage":"'{strategy}' strategy requires a non-empty 'unique_key'.","messagePattern":"'(.+?)' strategy requires a non-empty 'unique_key'\\.","errorType":"validation","errorClass":"AdapterError","httpStatus":null,"severity":"error","filePath":"crates/dbt-adapter/src/metadata/clickhouse/mod.rs","lineNumber":912,"sourceCode":") -> AdapterResult<()> {\n    let err = |msg: String| Err(AdapterError::new(AdapterErrorKind::Configuration, msg));\n    if !matches!(\n        strategy,\n        \"legacy\" | \"append\" | \"delete_insert\" | \"insert_overwrite\" | \"microbatch\"\n    ) {\n        return err(format!(\n            \"The incremental strategy '{strategy}' is not valid for ClickHouse.\"\n        ));\n    }\n    if matches!(strategy, \"delete_insert\" | \"microbatch\") && !has_lw_deletes {\n        return err(format!(\n            \"'{strategy}' strategy requires lightweight deletes, but the required setting \\\n             '{ND_MUTATION_SETTING}' could not be enabled on this ClickHouse server \\\n             (see the warnings logged at connection time).\"\n        ));\n    }\n    if matches!(strategy, \"delete_insert\" | \"microbatch\") && !has_unique_key {\n        return err(format!(\n            \"'{strategy}' strategy requires a non-empty 'unique_key'.\"\n        ));\n    }\n    if !matches!(strategy, \"delete_insert\" | \"microbatch\") && has_predicates {\n        return err(format!(\n            \"Cannot apply incremental predicates with '{strategy}' strategy.\"\n        ));\n    }\n    if strategy == \"insert_overwrite\" && !has_partition_by {\n        return err(format!(\n            \"'{strategy}' strategy requires non-empty 'partition_by'. Current partition_by is None.\"\n        ));\n    }\n    if strategy == \"insert_overwrite\" && has_unique_key {\n        return err(format!(\n            \"'{strategy}' strategy does not support unique_key.\"\n        ));\n    }","sourceCodeStart":894,"sourceCodeEnd":930,"githubUrl":"https://github.com/dbt-labs/dbt-core/blob/0267ce9170576975b76b64ce856b2e5848e96617/crates/dbt-adapter/src/metadata/clickhouse/mod.rs#L894-L930","documentation":"delete_insert and microbatch incremental strategies on ClickHouse identify which rows to replace during the incremental run, so a non-empty unique_key is mandatory. validate_incremental_strategy raises this Configuration error when either strategy is selected without one.","triggerScenarios":"Configuring incremental_strategy='delete_insert' or 'microbatch' on a ClickHouse model without setting unique_key, or setting unique_key to an empty value/empty list.","commonSituations":"Copying a model config from an append-only model that never needed unique_key; removing unique_key during a refactor while keeping the strategy; misunderstanding that microbatch also requires a key.","solutions":["Add a non-empty unique_key to the model config (a column name or list of column names)","Verify the key columns actually uniquely identify rows, or the delete/insert will duplicate data","If no natural key exists, switch incremental_strategy to 'append'"],"exampleFix":"// before\n{{ config(materialized='incremental', incremental_strategy='delete_insert') }}\n// after\n{{ config(materialized='incremental', incremental_strategy='delete_insert', unique_key='id') }}","handlingStrategy":"validation","validationCode":"if matches!(cfg.incremental_strategy.as_str(), \"delete_insert\" | \"microbatch\") {\n    assert!(!cfg.unique_key.as_ref().map_or(true, |k| k.is_empty()), \"unique_key required\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set unique_key when a delete-based strategy is used","Verify key columns form a real unique constraint in source data","Keep unique_key and incremental_strategy in the same config block to avoid drift"],"tags":["clickhouse","dbt","configuration","unique-key"],"backgroundTag":"missing-required-config-field","analyzedSha":"0267ce9170576975b76b64ce856b2e5848e96617","analyzedAt":"2026-09-07T21:53:39.732Z","contentChangedAt":"2026-09-07T21:53:39.732Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}