fix(bigquery): merge labels instead of clobbering

Merge labels across config levels instead of clobbering, so labels set
for a whole folder in dbt_project.yml combine with model-specific
labels. More specific levels win per label key. Implemented by using
MergeBehavior from dbt_common.

Author: yochem

dbt-bigquery/.changes/unreleased/Fixes-20260807-141738.yaml

@@ -0,0 +1,6 @@
+kind: Fixes
+body: Merge `labels` across config levels instead of clobbering, so labels set for a whole folder in dbt_project.yml combine with model-specific labels. More specific levels win per label key.
+time: 2026-08-07T14:17:38.959005+02:00
+custom:
+    Author: yochem
+    Issue: "15671"

dbt-bigquery/src/dbt/adapters/bigquery/impl.py

@@ -1,5 +1,5 @@
 import copy
-from dataclasses import dataclass
+from dataclasses import dataclass, field as dataclass_field
 from datetime import datetime
 from multiprocessing.context import SpawnContext
 import threading
@@ -34,6 +34,7 @@
     ConstraintType,
     ModelLevelConstraint,
 )
+from dbt_common.contracts.config.base import MergeBehavior
 from dbt_common.dataclass_schema import dbtClassMixin
 from dbt_common.events.functions import fire_event
 import dbt_common.exceptions
@@ -175,7 +176,9 @@ class BigqueryConfig(AdapterConfig):
     cluster_by: Optional[Union[List[str], str]] = None
     partition_by: Optional[Dict[str, Any]] = None
     kms_key_name: Optional[str] = None
-    labels: Optional[Dict[str, str]] = None
+    labels: Optional[Dict[str, str]] = dataclass_field(
+        default=None, metadata=MergeBehavior.Update.meta()
+    )
     partitions: Optional[List[str]] = None
     grant_access_to: Optional[List[Dict[str, str]]] = None
     hours_to_expiration: Optional[int] = None

dbt-bigquery/tests/unit/test_bigquery_adapter.py

@@ -27,6 +27,7 @@
 
 from google.cloud.bigquery import AccessEntry
 
+from .test_bigquery_label_merge import merge_config_levels
 from .utils import (
     config_from_parts_or_dicts,
     inject_adapter,
@@ -881,6 +882,30 @@ def test_get_common_options_labels_merge(self):
         actual = adapter.get_common_options(mock_config, node={}, temporary=False)
         self.assertEqual(expected, actual)
 
+    def test_get_common_options_labels_merged_across_config_levels(self):
+        adapter = self.get_adapter("oauth")
+        mock_config = create_autospec(RuntimeConfigObject)
+        # labels set in dbt_project.yml at the project level, then the folder
+        # level, then in the model's own config() block
+        config = merge_config_levels(
+            {"labels_from_meta": True, "meta": {"meta_label": "value2"}},
+            {"labels": {"dbt_project": "labelstest"}},
+            {"labels": {"layer": "intermediate"}},
+            {"labels": {"schedule": "daily", "dbt_project": ""}},
+        )
+        mock_config.get.side_effect = lambda name: config.get(name)
+
+        expected = {
+            "labels": [
+                ("meta_label", "value2"),
+                ("dbt_project", ""),
+                ("layer", "intermediate"),
+                ("schedule", "daily"),
+            ]
+        }
+        actual = adapter.get_common_options(mock_config, node={}, temporary=False)
+        self.assertEqual(expected, actual)
+
     def test_get_common_options_labels_no_meta(self):
         adapter = self.get_adapter("oauth")
         mock_config = create_autospec(RuntimeConfigObject)

dbt-bigquery/tests/unit/test_bigquery_label_merge.py

@@ -0,0 +1,113 @@
+import unittest
+
+from dbt.contracts.graph.model_config import ModelConfig
+
+from dbt.adapters.bigquery.impl import BigqueryConfig
+
+
+def merge_config_levels(*levels):
+    """Layer configs from least to most specific and return the result as a dict.
+
+    Mirrors what dbt-core's ContextConfigGenerator does at parse time: each
+    dbt_project.yml level (walking down the model's fqn) is applied in turn,
+    followed by the schema.yml patch and finally the model's own config() block.
+    """
+    config = ModelConfig.from_dict({})
+    for level in levels:
+        config = config.update_from(level, BigqueryConfig, validate=False)
+    return config.to_dict(omit_none=True)
+
+
+class TestBigQueryLabelMerge(unittest.TestCase):
+    def test_labels_merge_across_levels(self):
+        config = merge_config_levels(
+            {"labels": {"dbt_project": "labelstest"}},
+            {"labels": {"layer": "intermediate"}},
+            {"labels": {"schedule": "daily"}},
+        )
+
+        self.assertEqual(
+            config["labels"],
+            {
+                "dbt_project": "labelstest",
+                "layer": "intermediate",
+                "schedule": "daily",
+            },
+        )
+
+    def test_model_label_wins_over_project_label(self):
+        config = merge_config_levels(
+            {"labels": {"layer": "staging", "dbt_project": "labelstest"}},
+            {"labels": {"layer": "intermediate"}},
+        )
+
+        self.assertEqual(
+            config["labels"],
+            {"layer": "intermediate", "dbt_project": "labelstest"},
+        )
+
+    def test_labels_only_set_at_one_level(self):
+        self.assertEqual(
+            merge_config_levels({"labels": {"layer": "intermediate"}}, {})["labels"],
+            {"layer": "intermediate"},
+        )
+        self.assertEqual(
+            merge_config_levels({}, {"labels": {"schedule": "daily"}})["labels"],
+            {"schedule": "daily"},
+        )
+
+    def test_labels_absent_when_never_configured(self):
+        self.assertNotIn("labels", merge_config_levels({}, {"materialized": "table"}))
+
+    def test_empty_dict_does_not_clear_inherited_labels(self):
+        config = merge_config_levels(
+            {"labels": {"layer": "intermediate"}},
+            {"labels": {}},
+        )
+
+        self.assertEqual(config["labels"], {"layer": "intermediate"})
+
+    def test_empty_string_value_is_preserved(self):
+        config = merge_config_levels(
+            {"labels": {"dbt_project": "labelstest"}},
+            {"labels": {"schedule": ""}},
+        )
+
+        self.assertEqual(config["labels"], {"dbt_project": "labelstest", "schedule": ""})
+
+    def test_empty_string_value_overrides_inherited_value(self):
+        config = merge_config_levels(
+            {"labels": {"schedule": "daily"}},
+            {"labels": {"schedule": ""}},
+        )
+
+        self.assertEqual(config["labels"], {"schedule": ""})
+
+    def test_empty_string_value_is_overridden_by_more_specific_level(self):
+        config = merge_config_levels(
+            {"labels": {"schedule": ""}},
+            {"labels": {"schedule": "daily"}},
+        )
+
+        self.assertEqual(config["labels"], {"schedule": "daily"})
+
+    def test_labels_merge_alongside_meta(self):
+        """`labels_from_meta` reads `meta`, which merges across levels as well."""
+        config = merge_config_levels(
+            {"labels_from_meta": True, "meta": {"owner": "analytics"}},
+            {"meta": {"layer": "intermediate"}, "labels": {"dbt_project": "labelstest"}},
+            {"labels": {"schedule": "daily"}},
+        )
+
+        self.assertTrue(config["labels_from_meta"])
+        self.assertEqual(config["meta"], {"owner": "analytics", "layer": "intermediate"})
+        self.assertEqual(config["labels"], {"dbt_project": "labelstest", "schedule": "daily"})
+
+    def test_other_dict_configs_still_clobber(self):
+        """Only `labels` gained merge behavior; `partition_by` is unchanged."""
+        config = merge_config_levels(
+            {"partition_by": {"field": "created_at", "data_type": "timestamp"}},
+            {"partition_by": {"field": "updated_at"}},
+        )
+
+        self.assertEqual(config["partition_by"], {"field": "updated_at"})