Fix: set expr on column-based dimensions/entities when name differs from column (#12513)

* Fix FK constraint ref() resolving to deferred relation when target is selected

During deferral, foreign key constraint ref() was always resolving to the
deferred (production) relation even when the referenced model was being
built as part of the current selection. This caused FK constraints to
reference the wrong schema.

The fix adds selection awareness to FK constraint compilation:
- Track selected node IDs on the Compiler instance
- Use deferred relation only if FK target is NOT in selection
- Propagate selection info from task to runner compilers

This mirrors the behavior of RuntimeRefResolver.create_relation() for
model body refs, ensuring FK constraints behave consistently.

Fixes #12455

* Set expr on column-based dimensions and entities when name differs from column (#12512)

When using v2 semantic layer YAML with column-level dimension/entity
definitions, if the name differs from the column name, expr was not set
in the manifest. This caused MetricFlow to query the dimension/entity
name instead of the actual warehouse column, resulting in invalid
identifier errors during `dbt sl validate`.

Author: b-per

.changes/unreleased/Fixes-20260219-170000.yaml

@@ -0,0 +1,6 @@
+kind: Fixes
+body: Set expr to column name for column-based dimensions and entities when the semantic layer name differs from the column name, so MetricFlow queries the correct warehouse column
+time: 2026-02-19T17:00:00.000000+00:00
+custom:
+    Author: b-per
+    Issue: "12512"

core/dbt/parser/schema_yaml_readers.py

@@ -912,20 +912,23 @@ def _parse_v2_column_dimensions(self, columns: Dict[str, ColumnInfo]) -> List[Di
                 meta = dict(column.config.get("meta", {}))
                 meta.update((column.dimension.config or {}).get("meta", {}))
                 config = SemanticLayerElementConfig(meta=meta)
+                dimension_name = column.dimension.name or column.name
                 dimensions.append(
                     Dimension(
                         # required
                         type=DimensionType(column.dimension.type),
                         # fields that use column's values as fallback values
-                        name=column.dimension.name or column.name,
+                        name=dimension_name,
                         description=column.dimension.description or column.description,
                         config=config,
                         # optional fields
                         label=column.dimension.label,
                         is_partition=column.dimension.is_partition,
                         type_params=type_params,
                         metadata=None,  # Not yet supported in v1 or v2 YAML
-                        # expr argument is not supported for column-based dimensions
+                        # When the dimension name differs from the column name, set expr
+                        # to the column name so MetricFlow queries the correct warehouse column.
+                        expr=column.name if dimension_name != column.name else None,
                     )
                 )
         return dimensions
@@ -978,6 +981,9 @@ def _parse_v2_column_entities(self, columns: Dict[str, ColumnInfo]) -> List[Enti
                         type=column.entity.type,
                         description=column.entity.description,
                         label=column.entity.label,
+                        # When the entity name differs from the column name, set expr
+                        # to the column name so MetricFlow queries the correct warehouse column.
+                        expr=column.name if column.entity.name != column.name else None,
                         config=SemanticLayerElementConfig(
                             meta=column.entity.config.get("meta", column.config.get("meta", {}))
                         ),

tests/functional/semantic_models/test_semantic_model_v2_parsing.py

@@ -78,6 +78,9 @@ def test_semantic_model_parsing(self, project) -> None:
         assert id_dim.label == "ID Dimension"
         assert id_dim.is_partition is True
         assert id_dim.config.meta == {"component_level": "dimension_override"}
+        # dimension name "id_dim" differs from column name "id", so expr must
+        # be set to the column name for MetricFlow to query the correct column.
+        assert id_dim.expr == "id"
         second_dim = dimensions["second_dim"]
         assert second_dim.type == DimensionType.TIME
         assert second_dim.description == "This is the second column (dim)."
@@ -86,6 +89,9 @@ def test_semantic_model_parsing(self, project) -> None:
         assert second_dim.config.meta == {}
         assert second_dim.type_params.validity_params.is_start is True
         assert second_dim.type_params.validity_params.is_end is True
+        # dimension name "second_dim" differs from column name "second_col",
+        # so expr must be set to the column name.
+        assert second_dim.expr == "second_col"
         col_with_default_dimensions = dimensions["col_with_default_dimensions"]
         assert col_with_default_dimensions.type == DimensionType.CATEGORICAL
         assert (
@@ -96,6 +102,8 @@ def test_semantic_model_parsing(self, project) -> None:
         assert col_with_default_dimensions.is_partition is False
         assert col_with_default_dimensions.config.meta == {}
         assert col_with_default_dimensions.validity_params is None
+        # dimension name matches column name, so expr should not be set.
+        assert col_with_default_dimensions.expr is None
 
         # Entities
         assert len(semantic_model.entities) == 3
@@ -105,12 +113,17 @@ def test_semantic_model_parsing(self, project) -> None:
         assert primary_entity.description == "This is the id entity, and it is the primary entity."
         assert primary_entity.label == "ID Entity"
         assert primary_entity.config.meta == {"component_level": "entity_override"}
+        # entity name "id_entity" differs from column name "id", so expr must
+        # be set to the column name for MetricFlow to query the correct column.
+        assert primary_entity.expr == "id"
 
         foreign_id_col = entities["foreign_id_col"]
         assert foreign_id_col.type == EntityType.FOREIGN
         assert foreign_id_col.description == "This is a foreign id column."
         assert foreign_id_col.label is None
         assert foreign_id_col.config.meta == {}
+        # entity name matches column name, so expr should not be set.
+        assert foreign_id_col.expr is None
 
         col_with_default_entity_testing_default_desc = entities[
             "col_with_default_entity_testing_default_desc"
@@ -122,6 +135,8 @@ def test_semantic_model_parsing(self, project) -> None:
         )
         assert col_with_default_entity_testing_default_desc.label is None
         assert col_with_default_entity_testing_default_desc.config.meta == {}
+        # entity name differs from column name, so expr must be set.
+        assert col_with_default_entity_testing_default_desc.expr == "col_with_default_dimensions"
 
         # No measures in v2 YAML
         assert len(semantic_model.measures) == 0

tests/unit/parser/test_v2_column_semantic_parsing.py

@@ -0,0 +1,148 @@
+"""Unit tests for _parse_v2_column_dimensions and _parse_v2_column_entities.
+
+These methods transform column-level dimension/entity definitions into Dimension
+and Entity objects for the semantic manifest. When a dimension or entity name
+differs from the column name, the resulting object must have expr set to the
+column name so that MetricFlow generates SQL against the correct warehouse column.
+"""
+
+from collections import OrderedDict
+
+from dbt.artifacts.resources import ColumnDimension, ColumnEntity, ColumnInfo
+from dbt.parser.schema_yaml_readers import SemanticModelParser
+from dbt_semantic_interfaces.type_enums import DimensionType, EntityType
+
+
+def _make_column(name, description="", dimension=None, entity=None, granularity=None, config=None):
+    """Helper to construct a ColumnInfo with only the fields we need."""
+    return ColumnInfo(
+        name=name,
+        description=description,
+        dimension=dimension,
+        entity=entity,
+        granularity=granularity,
+        config=config or {},
+    )
+
+
+def _make_columns_dict(*columns):
+    """Build an OrderedDict of ColumnInfo keyed by name, as the parser expects."""
+    return OrderedDict((col.name, col) for col in columns)
+
+
+class TestParseV2ColumnDimensionsExpr:
+    """Test that _parse_v2_column_dimensions sets expr correctly."""
+
+    def test_dimension_name_override_sets_expr_to_column_name(self):
+        """When dimension.name differs from column.name, expr must be the column name."""
+        columns = _make_columns_dict(
+            _make_column(
+                name="afe_number",
+                description="AFE identifier",
+                dimension=ColumnDimension(
+                    name="approval_afe_number",
+                    type=DimensionType.CATEGORICAL,
+                ),
+            ),
+        )
+        dimensions = SemanticModelParser._parse_v2_column_dimensions(None, columns)
+        assert len(dimensions) == 1
+        dim = dimensions[0]
+        assert dim.name == "approval_afe_number"
+        assert dim.expr == "afe_number"
+
+    def test_dimension_name_matches_column_name_expr_is_none(self):
+        """When dimension.name matches column.name, expr should be None."""
+        columns = _make_columns_dict(
+            _make_column(
+                name="status",
+                dimension=ColumnDimension(
+                    name="status",
+                    type=DimensionType.CATEGORICAL,
+                ),
+            ),
+        )
+        dimensions = SemanticModelParser._parse_v2_column_dimensions(None, columns)
+        assert len(dimensions) == 1
+        assert dimensions[0].name == "status"
+        assert dimensions[0].expr is None
+
+    def test_dimension_empty_name_defaults_to_column_name(self):
+        """When dimension.name is empty string, name defaults to column.name and expr is None."""
+        columns = _make_columns_dict(
+            _make_column(
+                name="category",
+                dimension=ColumnDimension(
+                    name="",
+                    type=DimensionType.CATEGORICAL,
+                ),
+            ),
+        )
+        dimensions = SemanticModelParser._parse_v2_column_dimensions(None, columns)
+        assert len(dimensions) == 1
+        assert dimensions[0].name == "category"
+        assert dimensions[0].expr is None
+
+    def test_dimension_shorthand_type_expr_is_none(self):
+        """When dimension is just a DimensionType (shorthand), expr should be None."""
+        columns = _make_columns_dict(
+            _make_column(
+                name="color",
+                dimension=DimensionType.CATEGORICAL,
+            ),
+        )
+        dimensions = SemanticModelParser._parse_v2_column_dimensions(None, columns)
+        assert len(dimensions) == 1
+        assert dimensions[0].name == "color"
+        assert dimensions[0].expr is None
+
+
+class TestParseV2ColumnEntitiesExpr:
+    """Test that _parse_v2_column_entities sets expr correctly."""
+
+    def test_entity_name_override_sets_expr_to_column_name(self):
+        """When entity.name differs from column.name, expr must be the column name."""
+        columns = _make_columns_dict(
+            _make_column(
+                name="id",
+                description="Primary key",
+                entity=ColumnEntity(
+                    name="id_entity",
+                    type=EntityType.PRIMARY,
+                ),
+            ),
+        )
+        entities = SemanticModelParser._parse_v2_column_entities(None, columns)
+        assert len(entities) == 1
+        ent = entities[0]
+        assert ent.name == "id_entity"
+        assert ent.expr == "id"
+
+    def test_entity_name_matches_column_name_expr_is_none(self):
+        """When entity.name matches column.name, expr should be None."""
+        columns = _make_columns_dict(
+            _make_column(
+                name="user_id",
+                entity=ColumnEntity(
+                    name="user_id",
+                    type=EntityType.FOREIGN,
+                ),
+            ),
+        )
+        entities = SemanticModelParser._parse_v2_column_entities(None, columns)
+        assert len(entities) == 1
+        assert entities[0].name == "user_id"
+        assert entities[0].expr is None
+
+    def test_entity_shorthand_type_expr_is_none(self):
+        """When entity is just an EntityType (shorthand), name defaults to column.name and expr is None."""
+        columns = _make_columns_dict(
+            _make_column(
+                name="foreign_id_col",
+                entity=EntityType.FOREIGN,
+            ),
+        )
+        entities = SemanticModelParser._parse_v2_column_entities(None, columns)
+        assert len(entities) == 1
+        assert entities[0].name == "foreign_id_col"
+        assert entities[0].expr is None