drop model freshness as top level model property (in favor of config freshness) (#11731) (#11736)

* Begin testing that model freshness can't be set as a top level model property

* Remove ability to specify freshness as top level property of models

* Add come comments to calculate_node_config for better readability

* Drop `freshness` as a top level property of models, and let `patch_node_config` handle merging config freshness

Model freshness hasn't been released in a minor release yet, not been documented. Thus
it is safe to remove the top level property of freshness on models. Freshness will instead
be set, and gotten, from the model config. Additionally our way of calculating the
config model freshness only got the top level `+freshness` from dbt_project.yml (ignoring
any path specific definitions). By instead using the built in `calculate_node_config` (which
is eventually called by `patch_node_config`), we get all path specific freshness config handling
and it also handles the precedence of `dbt_project.yml` specification, schema file specification,
and sql file specification.

* add changie doc

(cherry picked from commit 091ba5f)

Co-authored-by: Quigley Malcolm <[email protected]>

Author: github-actions[bot]

.changes/unreleased/Fixes-20250616-085600.yaml

@@ -0,0 +1,6 @@
+kind: Fixes
+body: "Remove model freshness property support in favor of config level support"
+time: 2025-06-16T08:56:00.641553-05:00
+custom:
+  Author: QMalcolm
+  Issue: "11713"

core/dbt/artifacts/resources/v1/model.py

@@ -114,7 +114,6 @@ class Model(CompiledResource):
     defer_relation: Optional[DeferRelation] = None
     primary_key: List[str] = field(default_factory=list)
     time_spine: Optional[TimeSpine] = None
-    freshness: Optional[ModelFreshness] = None
 
     def __post_serialize__(self, dct: Dict, context: Optional[Dict] = None):
         dct = super().__post_serialize__(dct, context)

core/dbt/context/context_config.py

@@ -141,17 +141,21 @@ def initial_result(self, resource_type: NodeType, base: bool) -> T: ...
 
     def calculate_node_config(
         self,
+        # this is the config from the sql file
         config_call_dict: Dict[str, Any],
         fqn: List[str],
         resource_type: NodeType,
         project_name: str,
         base: bool,
+        # this is the config from the schema file
         patch_config_dict: Optional[Dict[str, Any]] = None,
     ) -> BaseConfig:
         own_config = self.get_node_project(project_name)
 
         result = self.initial_result(resource_type=resource_type, base=base)
 
+        # builds the config from what was specified in the runtime_config, which generally
+        # comes from the project's dbt_project.yml file.
         project_configs = self._project_configs(own_config, fqn, resource_type)
         for fqn_config in project_configs:
             result = self._update_from_config(result, fqn_config)

core/dbt/contracts/graph/unparsed.py

@@ -225,7 +225,6 @@ class UnparsedModelUpdate(UnparsedNodeUpdate):
     versions: Sequence[UnparsedVersion] = field(default_factory=list)
     deprecation_date: Optional[datetime.datetime] = None
     time_spine: Optional[TimeSpine] = None
-    freshness: Optional[Dict[str, Any]] = None
 
     def __post_init__(self) -> None:
         if self.latest_version:

core/dbt/parser/schemas.py

@@ -18,12 +18,7 @@
 )
 
 from dbt.artifacts.resources import RefArgs
-from dbt.artifacts.resources.v1.model import (
-    CustomGranularity,
-    ModelFreshness,
-    TimeSpine,
-    merge_model_freshness,
-)
+from dbt.artifacts.resources.v1.model import CustomGranularity, TimeSpine
 from dbt.clients.checked_load import (
     checked_load,
     issue_deprecation_warnings_for_failures,
@@ -766,8 +761,6 @@ def parse_patch(self, block: TargetBlock[NodeTarget], refs: ParserRef) -> None:
         deprecation_date: Optional[datetime.datetime] = None
         time_spine: Optional[TimeSpine] = None
 
-        freshness: Optional[ModelFreshness] = None
-
         if isinstance(block.target, UnparsedModelUpdate):
             deprecation_date = block.target.deprecation_date
             time_spine = (
@@ -785,37 +778,6 @@ def parse_patch(self, block: TargetBlock[NodeTarget], refs: ParserRef) -> None:
                 else None
             )
 
-            try:
-                project_freshness_dict = self.project.models.get("+freshness", None)
-                project_freshness = (
-                    ModelFreshness.from_dict(project_freshness_dict)
-                    if project_freshness_dict and "build_after" in project_freshness_dict
-                    else None
-                )
-            except ValueError:
-                fire_event(
-                    Note(
-                        msg="Could not validate `freshness` for `models` in 'dbt_project.yml', ignoring.",
-                    ),
-                    EventLevel.WARN,
-                )
-                project_freshness = None
-
-            model_freshness_dict = block.target.freshness or None
-            model_freshness = (
-                ModelFreshness.from_dict(model_freshness_dict)
-                if model_freshness_dict and "build_after" in model_freshness_dict
-                else None
-            )
-
-            config_freshness_dict = block.target.config.get("freshness", None)
-            config_freshness = (
-                ModelFreshness.from_dict(config_freshness_dict)
-                if config_freshness_dict and "build_after" in config_freshness_dict
-                else None
-            )
-            freshness = merge_model_freshness(project_freshness, model_freshness, config_freshness)
-
         patch = ParsedNodePatch(
             name=block.target.name,
             original_file_path=block.target.original_file_path,
@@ -832,7 +794,6 @@ def parse_patch(self, block: TargetBlock[NodeTarget], refs: ParserRef) -> None:
             constraints=block.target.constraints,
             deprecation_date=deprecation_date,
             time_spine=time_spine,
-            freshness=freshness,
         )
         assert isinstance(self.yaml.file, SchemaSourceFile)
         source_file: SchemaSourceFile = self.yaml.file
@@ -1122,7 +1083,6 @@ def patch_node_properties(self, node, patch: "ParsedNodePatch") -> None:
         # These two will have to be reapplied after config is built for versioned models
         self.patch_constraints(node, patch.constraints)
         self.patch_time_spine(node, patch.time_spine)
-        node.freshness = patch.freshness
         node.build_contract_checksum()
 
     def patch_constraints(self, node: ModelNode, constraints: List[Dict[str, Any]]) -> None:

tests/functional/artifacts/expected_manifest.py

@@ -383,7 +383,6 @@ def expected_seeded_manifest(project, model_database=None, quote_model=False):
                 "version": None,
                 "latest_version": None,
                 "time_spine": None,
-                "freshness": None,
                 "doc_blocks": [],
             },
             "model.test.second_model": {
@@ -494,7 +493,6 @@ def expected_seeded_manifest(project, model_database=None, quote_model=False):
                 "version": None,
                 "latest_version": None,
                 "time_spine": None,
-                "freshness": None,
                 "doc_blocks": [],
             },
             "seed.test.seed": {
@@ -1055,7 +1053,6 @@ def expected_references_manifest(project):
                 "latest_version": None,
                 "constraints": [],
                 "time_spine": None,
-                "freshness": None,
                 "doc_blocks": [],
             },
             "model.test.ephemeral_summary": {
@@ -1133,7 +1130,6 @@ def expected_references_manifest(project):
                 "latest_version": None,
                 "constraints": [],
                 "time_spine": None,
-                "freshness": None,
                 "doc_blocks": ["doc.test.ephemeral_summary"],
             },
             "model.test.view_summary": {
@@ -1207,7 +1203,6 @@ def expected_references_manifest(project):
                 "latest_version": None,
                 "constraints": [],
                 "time_spine": None,
-                "freshness": None,
                 "doc_blocks": ["doc.test.view_summary"],
             },
             "seed.test.seed": {
@@ -1709,7 +1704,6 @@ def expected_versions_manifest(project):
                 "version": 1,
                 "latest_version": 2,
                 "time_spine": None,
-                "freshness": None,
                 "doc_blocks": [],
             },
             "model.test.versioned_model.v2": {
@@ -1792,7 +1786,6 @@ def expected_versions_manifest(project):
                 "version": 2,
                 "latest_version": 2,
                 "time_spine": None,
-                "freshness": None,
                 "doc_blocks": [],
             },
             "model.test.ref_versioned_model": {
@@ -1852,7 +1845,6 @@ def expected_versions_manifest(project):
                 "version": None,
                 "latest_version": None,
                 "time_spine": None,
-                "freshness": None,
                 "doc_blocks": [],
             },
             "test.test.unique_versioned_model_v1_first_name.6138195dec": {

tests/functional/model_config/test_freshness_config.py

@@ -22,9 +22,10 @@
   - name: my_source
     database: "{{ target.database }}"
     schema: "{{ target.schema }}"
-    freshness:
-      warn_after: {count: 24, period: hour}
-      error_after: {count: 48, period: hour}
+    config:
+      freshness:
+        warn_after: {count: 24, period: hour}
+        error_after: {count: 48, period: hour}
     loaded_at_field: _loaded_at
     tables:
       - name: source_table
@@ -35,16 +36,18 @@
     description: Model with no freshness defined
   - name: model_b
     description: Model with only model freshness defined
-    freshness:
-      build_after:
-        count: 1
-        period: day
-        updates_on: all
+    config:
+      freshness:
+        build_after:
+          count: 1
+          period: day
+          updates_on: all
   - name: model_c
     description: Model with only source freshness defined
-    freshness:
-      warn_after: {count: 24, period: hour}
-      error_after: {count: 48, period: hour}
+    config:
+      freshness:
+        warn_after: {count: 24, period: hour}
+        error_after: {count: 48, period: hour}
     loaded_at_field: _loaded_at
     tables:
       - name: source_table

tests/unit/contracts/graph/test_manifest.py

@@ -98,7 +98,6 @@
         "defer_relation",
         "time_spine",
         "batch",
-        "freshness",
     }
 )
 

tests/unit/parser/test_parser.py

@@ -309,22 +309,29 @@ def assertEqualNodes(node_one, node_two):
 models:
     - name: my_model
       description: A description of my model
-      freshness:
-        build_after: {count: 4, period: day, updates_on: all}
       config:
         freshness:
-          build_after: {count: 1, period: day, updates_on: any}
+          build_after: {count: 1, period: day, updates_on: all}
 """
 
-SINGLE_TABLE_MODEL_FRESHNESS_ONLY_DEPEND_ON = """
+SINGLE_TABLE_MODEL_TOP_LEVEL_FRESHNESS = """
 models:
     - name: my_model
       description: A description of my model
       freshness:
-        build_after:
+        build_after: {count: 1, period: day, updates_on: any}
+"""
+
+SINGLE_TABLE_MODEL_FRESHNESS_ONLY_DEPEND_ON = """
+models:
+    - name: my_model
+      description: A description of my model
+      config:
+        freshness:
+          build_after:
             updates_on: all
             period: hour
-            count: 0
+            count: 5
 """
 
 
@@ -738,7 +745,7 @@ def setUp(self):
         my_model_node = MockNode(
             package="root",
             name="my_model",
-            config=mock.MagicMock(enabled=True),
+            config=ModelConfig(enabled=True),
             refs=[],
             sources=[],
             patch_path=None,
@@ -771,10 +778,23 @@ def test__parse_model_freshness(self):
 
         assert self.parser.manifest.nodes[
             "model.root.my_model"
-        ].freshness.build_after == ModelBuildAfter(
+        ].config.freshness.build_after == ModelBuildAfter(
             count=1, period="day", updates_on=ModelFreshnessUpdatesOnOptions.all
         )
 
+    def test__parse_model_ignores_top_level_freshness(self):
+        block = self.file_block_for(SINGLE_TABLE_MODEL_TOP_LEVEL_FRESHNESS, "test_one.yml")
+        self.parser.manifest.files[block.file.file_id] = block.file
+        dct = yaml_from_file(block.file, validate=True)
+        self.parser.parse_file(block, dct)
+        self.assert_has_manifest_lengths(self.parser.manifest, nodes=1)
+
+        # we can't use hasattr because the model node is a mock, and checking with hasattr will add it to the mock
+        assert "freshness" not in self.parser.manifest.nodes["model.root.my_model"].__dir__()
+
+        # should be None because nothing set it
+        assert self.parser.manifest.nodes["model.root.my_model"].config.freshness is None
+
     def test__parse_model_freshness_depend_on(self):
         block = self.file_block_for(SINGLE_TABLE_MODEL_FRESHNESS_ONLY_DEPEND_ON, "test_one.yml")
         self.parser.manifest.files[block.file.file_id] = block.file
@@ -783,8 +803,8 @@ def test__parse_model_freshness_depend_on(self):
         self.assert_has_manifest_lengths(self.parser.manifest, nodes=1)
         assert self.parser.manifest.nodes[
             "model.root.my_model"
-        ].freshness.build_after == ModelBuildAfter(
-            count=0, period="hour", updates_on=ModelFreshnessUpdatesOnOptions.all
+        ].config.freshness.build_after == ModelBuildAfter(
+            count=5, period="hour", updates_on=ModelFreshnessUpdatesOnOptions.all
         )
 
     def test__read_basic_model_tests_wrong_severity(self):