metricflow-sql 0.1.1__py3-none-any.whl

metricflow_sql/compiler/rules/expand_datasets.py

@@ -0,0 +1,1208 @@
+from __future__ import annotations
+
+import logging
+from collections import deque
+from dataclasses import dataclass, field, replace
+from itertools import count
+from typing import NoReturn
+
+from sqlglot import Expr, exp
+from sqlglot.errors import SchemaError
+from sqlglot.helper import find_new_name
+from sqlglot.optimizer.helpers import projection_has_aggregate
+from sqlglot.optimizer.optimize_joins import other_table_names
+from sqlglot.optimizer.simplify import simplify, simplify_parens
+
+from metricflow_sql.compiler.catalog.cluster import Cluster
+from metricflow_sql.compiler.table_arguments import TABLE_ARGUMENTS
+from metricflow_sql.objects.base import Id
+from metricflow_sql.objects.dataset import (
+    Calculation,
+    Cardinality,
+    Column,
+    Relationship,
+    argument,
+    parameter_value,
+)
+from metricflow_sql.objects.entity import Attribute, Source
+from metricflow_sql.registry.reference_resolution import (
+    resolve_attribute_reference,
+    resolve_attribute_references,
+)
+from metricflow_sql.registry.registry import (
+    DatasetProxy,
+    DatasetTarget,
+    EntityProxy,
+    EntityTarget,
+    Registry,
+    RelationshipTarget,
+    relationship_cardinality,
+    relationship_target,
+)
+from metricflow_sql.utils.normalize import resolve_name
+from metricflow_sql.utils.sql import (
+    FINAL,
+    group_all_keys,
+    is_aggregate_expression,
+    is_shadowed,
+    normalize_group,
+    path_names,
+    table_scopes,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ExpandContext:
+    registry: Registry
+    dataset: DatasetProxy
+    alias: str
+    root_alias: str
+    datasets_by_alias: dict[str, tuple[Registry, DatasetProxy]] = field(default_factory=dict)
+    # Each source's own table function arguments, e.g. a user join's `customer(x => 1)`.
+    arguments_by_alias: dict[str, dict[str, exp.Expr]] = field(default_factory=dict)
+    used_aliases: set[str] = field(default_factory=set)
+    # Join aliases by (parent alias, relationship name, dataset the join reads).
+    join_aliases: dict[tuple[str, exp.Identifier, exp.Table], str] = field(default_factory=dict)
+    joins: dict[str, exp.Join] = field(default_factory=dict)
+    join_parents: dict[str, str] = field(default_factory=dict)
+    # The dataset each generated join reads, keyed by join alias.
+    join_datasets: dict[str, DatasetProxy] = field(default_factory=dict)
+    # The entity source identifying the rows of a generated join, for a dataset without a key.
+    grain_sources: dict[str, Source] = field(default_factory=dict)
+    join_depths: dict[str, int] = field(default_factory=dict)
+    fanout_grain_by_alias: dict[str, str] = field(default_factory=dict)
+    # One-to-many joins, keyed by alias, mapped to the alias of the join they fan out from.
+    fanout_parents: dict[str, str] = field(default_factory=dict)
+    aggregate_grains: dict[int, str] = field(default_factory=dict)
+    dialect: str | None = None
+    # The root table's table function arguments, passed to every dataset its relationships reach.
+    arguments: dict[str, exp.Expr] = field(default_factory=dict)
+
+
+class ExpandDatasetsRule:
+    """
+    Sqlglot optimizer rule that replaces calculations, relationships, etc. with
+    their physical representations.
+    """
+
+    def __init__(self, strict: bool = False):
+        self.strict = strict
+
+    def _fail(self, ctx: ExpandContext, message: str, expr: exp.Expr | None = None) -> NoReturn:
+        if expr is not None:
+            message = f"{message}: {expr.sql(dialect=ctx.dialect)}"
+        raise ValueError(message)
+
+    def __call__(self, expression: Expr, cluster: Cluster, dialect: str | None = None) -> Expr:
+        for scope, select, table in table_scopes(expression):
+            registry_and_dataset = cluster.get_dataset(table)
+            if not registry_and_dataset:
+                continue
+            registry, dataset = registry_and_dataset
+
+            ctx = ExpandContext(
+                registry=registry,
+                dataset=dataset,
+                alias=table.alias_or_name,
+                root_alias=table.alias_or_name,
+                dialect=dialect,
+                arguments=table.meta.get(TABLE_ARGUMENTS, {}),
+            )
+            for alias, (_, source) in scope.selected_sources.items():
+                ctx.used_aliases.add(alias)
+                if isinstance(source, exp.Table) and not source.meta.get(FINAL):
+                    joined = cluster.get_dataset(source)
+                    if joined:
+                        ctx.datasets_by_alias[alias] = joined
+                        ctx.arguments_by_alias[alias] = source.meta.get(TABLE_ARGUMENTS, {})
+
+            query = self._expand_scope(select, ctx)
+
+            scope.expression.replace(query)
+
+            if not scope.parent:
+                return query
+
+        return expression
+
+    def _expand_scope(self, select: exp.Select, ctx: ExpandContext) -> exp.Query:
+        projections = [self._expand_expr(projection, ctx) for projection in select.expressions]
+        user_joins: list[exp.Join] = select.args.get("joins") or []
+        prior = {ctx.root_alias: (ctx.registry, ctx.dataset)}
+        for join in user_joins:
+            on = join.args.get("on")
+            if on is not None:
+                join.set("on", self._expand_expr(on, ctx))
+
+            table = join.this
+            if isinstance(table, exp.Table):
+                joined = ctx.datasets_by_alias.get(table.alias_or_name)
+                if joined:
+                    self._warn_unverified_join(ctx, join, prior, table.alias_or_name, joined)
+                    join.set(
+                        "this",
+                        exp.alias_(
+                            joined[1].from_(ctx.arguments_by_alias[table.alias_or_name]),
+                            table.alias_or_name,
+                            copy=False,
+                        ),
+                    )
+                    prior[table.alias_or_name] = joined
+
+        where = select.args.get("where")
+        if where is not None:
+            where = self._expand_expr(where, ctx)
+
+        group = select.args.get("group")
+        requested_groups: list[tuple[exp.Expr, ...]] = [()]
+        if isinstance(group, exp.Group):
+            requested_groups = [
+                tuple(self._expand_expr(grouping, ctx) for grouping in grouping_set)
+                for grouping_set in normalize_group(group)
+            ]
+            if group.args.get("all") and requested_groups == [()]:
+                expanded = exp.select(*(projection.copy() for projection in projections))
+                requested_groups = [
+                    tuple(projections[i].unalias().copy() for i in group_all_keys(expanded))
+                ]
+
+        self._resolve_partition_by_excluding(projections, requested_groups, ctx)
+
+        # An aggregate defined on a joined dataset counts that dataset's rows, so the root's
+        # rows can't be grouped directly, e.g. AGG(store.total_employees) FROM store_sales.
+        # Without aggregates, a one-to-many join's rows are the query's, fanned out.
+        aggregates = isinstance(group, exp.Group) or bool(ctx.aggregate_grains)
+        if aggregates and (
+            ctx.fanout_parents or any(alias in ctx.joins for alias in ctx.aggregate_grains.values())
+        ):
+            return self._expand_fanout_grouping(
+                projections, requested_groups, where, user_joins, ctx
+            )
+
+        if isinstance(group, exp.Group):
+            if len(requested_groups) == 1:
+                group = (
+                    exp.Group(expressions=list(requested_groups[0]))
+                    if requested_groups[0]
+                    else None
+                )
+            else:
+                group = exp.Group(
+                    expressions=[
+                        exp.GroupingSets(
+                            expressions=[
+                                exp.tuple_(*grouping_set, copy=False)
+                                for grouping_set in requested_groups
+                            ]
+                        )
+                    ]
+                )
+
+        new_select = exp.select(*projections, copy=False).from_(
+            exp.alias_(ctx.dataset.from_(ctx.arguments), ctx.alias, copy=False),
+            copy=False,
+        )
+        new_select.set("joins", self._ordered_joins(user_joins, ctx))
+        if where is not None:
+            new_select.set("where", where)
+        if group:
+            new_select.set("group", group)
+        return new_select
+
+    def _resolve_partition_by_excluding(
+        self,
+        projections: list[exp.Expr],
+        requested_groups: list[tuple[exp.Expr, ...]],
+        ctx: ExpandContext,
+    ) -> None:
+        exclusions = [
+            exclusion
+            for projection in projections
+            for exclusion in projection.find_all(exp.PartitionByExcluding)
+        ]
+        if not exclusions:
+            return
+        if len(requested_groups) != 1:
+            self._fail(
+                ctx,
+                "Unsupported query - window calculations containing PARTITION BY EXCLUDING cannot be grouped by GROUPING SETS",
+                exclusions[0].find_ancestor(exp.Window),
+            )
+
+        group = requested_groups[0]
+        grouped_expressions = frozenset(group)
+        for exclusion in exclusions:
+            for expr in exclusion.expressions:
+                if expr not in grouped_expressions:
+                    self._fail(
+                        ctx,
+                        "Unsupported query - GROUP BY must include all dimensions in PARTITION BY EXCLUDING clauses",
+                        expr.find_ancestor(exp.Window),
+                    )
+            excluded = frozenset(exclusion.expressions)
+            exclusion.replace(
+                [dimension.copy() for dimension in group if dimension not in excluded]
+            )
+
+    def _ordered_joins(self, user_joins: list[exp.Join], ctx: ExpandContext) -> list[exp.Join]:
+        ordered: list[exp.Join] = []
+        available = {ctx.root_alias}
+
+        def add_generated(alias: str) -> None:
+            pending: list[str] = []
+            while alias in ctx.joins and alias not in available:
+                pending.append(alias)
+                alias = ctx.join_parents[alias]
+            if alias not in available:
+                self._fail(ctx, f"JOIN ON needs {pending[0]} before {alias} is joined")
+            for needed in reversed(pending):
+                # A key can read other joins, e.g. `_item.i_item_id` in `_item_as_sold`'s.
+                for dependency in sorted(other_table_names(ctx.joins[needed]) & ctx.joins.keys()):
+                    add_generated(dependency)
+                ordered.append(ctx.joins[needed])
+                available.add(needed)
+
+        for join in user_joins:
+            for alias in sorted(other_table_names(join) & ctx.joins.keys()):
+                add_generated(alias)
+            ordered.append(join)
+            available.add(join.alias_or_name)
+
+        for alias in ctx.joins:
+            add_generated(alias)
+        return ordered
+
+    def _join_terms(self, expression: exp.Expr, dialect: str | None) -> set[exp.Expr]:
+        normalized = simplify(expression, dialect=dialect).unnest()
+        if isinstance(normalized, exp.And):
+            return set(normalized.flatten())
+        return {normalized}
+
+    def _warn_unverified_join(
+        self,
+        ctx: ExpandContext,
+        join: exp.Join,
+        prior: dict[str, tuple[Registry, DatasetProxy]],
+        alias: str,
+        joined: tuple[Registry, DatasetProxy],
+    ) -> None:
+        joined_registry, joined_dataset = joined
+        on = join.args.get("on")
+        actual_terms = self._join_terms(on.copy(), ctx.dialect) if on is not None else set()
+        dialect = joined_registry.dialect
+        names: set[str] = set()
+        sources: set[str] = set()
+        for previous_alias, (registry, previous_dataset) in prior.items():
+            if registry is not joined_registry:
+                continue
+            for parent_alias, parent_dataset, source_alias, source_dataset in (
+                (previous_alias, previous_dataset, alias, joined_dataset),
+                (alias, joined_dataset, previous_alias, previous_dataset),
+            ):
+                for name in parent_dataset.column_names():
+                    relationship = parent_dataset.get_column(name)
+                    if not isinstance(relationship, Relationship):
+                        continue
+                    try:
+                        target = relationship_target(registry, relationship)
+                    except SchemaError:
+                        continue
+                    values = {
+                        name: self._qualify_key(expr, parent_alias)
+                        for name, expr in relationship.key.items()
+                    }
+                    match target:
+                        case EntityTarget(entity=entity):
+                            source = entity.get_source(source_dataset.name)
+                            if source is None:
+                                continue
+                            condition = self._bind_join_keys(ctx, source.on, values, source_alias)
+                        case DatasetTarget(dataset=target_dataset):
+                            if target_dataset.name != source_dataset.name:
+                                continue
+                            condition = self._dataset_join_on(
+                                ctx, relationship, target_dataset, source_alias, values
+                            )
+                    names.add(
+                        f"{relationship.dataset.sql(dialect)}.{relationship.name.sql(dialect)}"
+                    )
+                    sources.add(previous_alias)
+                    if self._join_terms(condition, ctx.dialect) <= actual_terms:
+                        return
+
+        if not names:
+            return
+        relationship_names = sorted(names)
+        description = (
+            f"relationship {relationship_names[0]}"
+            if len(relationship_names) == 1
+            else f"relationships {', '.join(relationship_names)}"
+        )
+        logger.warning(
+            "Join %s -> %s could not be verified as a subset of %s; "
+            "results may have missing or duplicate rows",
+            ", ".join(sorted(sources)),
+            alias,
+            description,
+        )
+
+    def _expand_fanout_grouping(
+        self,
+        projections: list[exp.Expr],
+        requested_groups: list[tuple[exp.Expr, ...]],
+        where: exp.Expr | None,
+        user_joins: list[exp.Join],
+        ctx: ExpandContext,
+    ) -> exp.Query:
+        used_aliases = {projection.alias for projection in projections}
+        alias_numbers = count()
+
+        def internal_alias(preferred: str) -> str:
+            alias = preferred
+            while alias in used_aliases:
+                alias = f"_metricflow_{next(alias_numbers)}"
+            used_aliases.add(alias)
+            return alias
+
+        grouped_expressions = frozenset(
+            expression for grouping_set in requested_groups for expression in grouping_set
+        )
+        dimensions: dict[exp.Expr, exp.Expr] = {}
+        for projection in projections:
+            if projection.this in grouped_expressions:
+                dimensions.setdefault(projection.this, projection)
+
+        aggregate_grain_by_id: dict[int, str] = {}
+        determined_by_grain: dict[str, dict[str, bool]] = {}
+        for projection in projections:
+            if projection.this in grouped_expressions:
+                continue
+            for aggregate in projection.this.find_all(exp.AggFunc):
+                referenced_aliases = {
+                    column.table for column in aggregate.find_all(exp.Column) if column.table
+                }
+                fanout_aliases = {
+                    ctx.fanout_grain_by_alias[alias]
+                    for alias in referenced_aliases
+                    if alias in ctx.fanout_grain_by_alias
+                }
+                grain_alias = (
+                    max(fanout_aliases, key=lambda alias: ctx.join_depths[alias])
+                    if fanout_aliases
+                    else ctx.aggregate_grains.get(id(aggregate), ctx.root_alias)
+                )
+                if referenced_aliases:
+                    self._reject_fanout_aggregate(
+                        ctx,
+                        aggregate,
+                        grain_alias,
+                        referenced_aliases,
+                        determined_by_grain,
+                    )
+                aggregate_grain_by_id[id(aggregate)] = grain_alias
+        aggregate_grains = set(aggregate_grain_by_id.values())
+        grains: dict[str, tuple[exp.Expr, ...]] = {}
+        if ctx.root_alias in aggregate_grains:
+            grains[ctx.root_alias] = self._grain(ctx, ctx.root_alias)
+        for alias, parent_alias in ctx.fanout_parents.items():
+            if parent_alias in aggregate_grains and parent_alias not in grains:
+                grains[parent_alias] = self._grain(ctx, parent_alias)
+            grains[alias] = self._grain(ctx, alias)
+        for alias in aggregate_grain_by_id.values():
+            if alias not in grains:
+                grains[alias] = self._grain(ctx, alias)
+
+        if len(requested_groups) > 1 and any(
+            key in grouped_expressions for grain in grains.values() for key in grain
+        ):
+            self._fail(ctx, "GROUPING SETS cannot overlap entity keys")
+
+        dimension_exprs = list(
+            dict.fromkeys(
+                expression for grouping_set in requested_groups for expression in grouping_set
+            )
+        )
+        calculated_groups = [
+            exp.tuple_(*dict.fromkeys((*requested_group, *grain)))
+            for requested_group in requested_groups
+            for grain in grains.values()
+        ]
+        inner_group = exp.Group(expressions=[exp.GroupingSets(expressions=calculated_groups)])
+
+        # Prefer a key outside the dimensions so GROUPING can identify its grain.
+        markers = [
+            next((key for key in grain if key not in grouped_expressions), grain[0])
+            for grain in grains.values()
+        ]
+        weights = [1 << (len(markers) - index - 1) for index in range(len(markers))]
+        group_id_expr = self._grouping_id_expression(markers, copy=False)
+
+        marker_weights = dict(zip(markers, weights, strict=True))
+        all_mask = (1 << len(markers)) - 1
+        dimension_mask = 0
+        for dimension in grouped_expressions:
+            dimension_mask |= marker_weights.get(dimension, 0)
+        group_ids: dict[str, int] = {}
+        for alias, grain in grains.items():
+            included_mask = dimension_mask
+            for key in grain:
+                included_mask |= marker_weights.get(key, 0)
+            group_ids[alias] = all_mask ^ included_mask
+        if len(set(group_ids.values())) != len(group_ids):
+            self._fail(ctx, "Grouping sets cannot distinguish entity grains")
+
+        group_id_alias = internal_alias("_group_id")
+        dimension_group_id_alias = (
+            internal_alias("_dimension_group_id") if len(requested_groups) > 1 else None
+        )
+        inner_projections: list[exp.Expr] = []
+        dimension_aliases: dict[exp.Expr, str] = {}
+        inner_aliases: set[str] = set()
+        for index, dimension_expr in enumerate(dimension_exprs):
+            dimension_projection = dimensions.get(dimension_expr)
+            if dimension_projection is None or dimension_projection.alias in inner_aliases:
+                alias = internal_alias(f"_group_dimension_{index}")
+                inner_projections.append(exp.alias_(dimension_expr, alias))
+            else:
+                alias = dimension_projection.alias
+                inner_projections.append(dimension_projection)
+            dimension_aliases[dimension_expr] = alias
+            inner_aliases.add(alias)
+        inner_projections.append(exp.alias_(group_id_expr, group_id_alias, copy=False))
+        inner_aliases.add(group_id_alias)
+        if dimension_group_id_alias is not None:
+            inner_projections.append(
+                exp.alias_(
+                    self._grouping_id_expression(dimension_exprs, copy=True),
+                    dimension_group_id_alias,
+                    copy=False,
+                )
+            )
+            inner_aliases.add(dimension_group_id_alias)
+        outer_projections: list[exp.Expr] = []
+        for projection in projections:
+            if projection.this in grouped_expressions:
+                outer_projections.append(
+                    exp.alias_(
+                        exp.column(dimension_aliases[projection.this], table="grouped"),
+                        projection.alias,
+                        copy=False,
+                    )
+                )
+                continue
+
+            aggregates = list(projection.this.find_all(exp.AggFunc))
+            if not aggregates:
+                self._fail(ctx, "Expected aggregate projection", projection)
+
+            def lower(
+                node: exp.Expr,
+                metric_aggregate_count: int = len(aggregates),
+                metric_alias: str = projection.alias,
+            ) -> exp.Expr:
+                if node in dimension_aliases:
+                    return exp.column(dimension_aliases[node], table="grouped")
+                # The condition reads the joined rows, so it filters each grain's value in the
+                # inner query, e.g. SUM(x) FILTER (WHERE y > 1) keeps MAX(x) FILTER (WHERE y > 1).
+                condition = None
+                if isinstance(node, exp.Filter) and isinstance(node.this, exp.AggFunc):
+                    condition = node.expression.this
+                    node = node.this
+                if not isinstance(node, exp.AggFunc):
+                    return node
+
+                grain_alias = aggregate_grain_by_id[id(node)]
+
+                group_test = exp.column(group_id_alias, table="grouped").eq(group_ids[grain_alias])
+                distinct = False
+                match node:
+                    case exp.Count(this=exp.Star()) if (
+                        grain_alias == ctx.alias and condition is None
+                    ):
+                        return exp.func(
+                            "COUNT",
+                            exp.case().when(group_test, then=1, copy=False),
+                            copy=False,
+                        )
+                    case exp.Count(this=exp.Star()):
+                        value = grains[grain_alias][0].copy()
+                    case exp.AggFunc(this=exp.Distinct(expressions=[value])):
+                        distinct = True
+                    case exp.AggFunc(this=exp.Distinct()):
+                        self._fail(ctx, "Expected one DISTINCT expression", node)
+                    case _:
+                        value = node.this
+
+                slot = (
+                    metric_alias
+                    if metric_aggregate_count == 1 and metric_alias not in inner_aliases
+                    else internal_alias(f"_metric_{len(inner_projections)}")
+                )
+                inner_aliases.add(slot)
+                outer_value = exp.case().when(
+                    group_test,
+                    then=exp.column(slot, table="grouped"),
+                    copy=False,
+                )
+                node.set(
+                    "this",
+                    exp.Distinct(expressions=[outer_value]) if distinct else outer_value,
+                )
+                if grain_alias != ctx.root_alias and not (
+                    isinstance(value, exp.Column) and value.table == grain_alias
+                ):
+                    value = exp.case().when(
+                        grains[grain_alias][0].is_(exp.null()).not_(copy=False),
+                        then=value,
+                        copy=False,
+                    )
+                inner_value: exp.Expr = exp.func("MAX", value, copy=False)
+                if condition is not None:
+                    inner_value = exp.Filter(this=inner_value, expression=exp.Where(this=condition))
+                inner_projections.append(exp.alias_(inner_value, slot, copy=False))
+                return node
+
+            outer_expr = projection.this.transform(lower, copy=False)
+            outer_projections.append(exp.alias_(outer_expr, projection.alias, copy=False))
+
+        inner = exp.select(*inner_projections, copy=False).from_(
+            exp.alias_(ctx.dataset.from_(ctx.arguments), ctx.alias, copy=False),
+            copy=False,
+        )
+        inner.set("joins", self._ordered_joins(user_joins, ctx))
+        if where is not None:
+            inner.set("where", where)
+        inner.set("group", inner_group)
+
+        outer = exp.select(*outer_projections, copy=False).from_(
+            inner.subquery(alias="grouped", copy=False), copy=False
+        )
+        outer_group = [
+            exp.column(dimension_aliases[dimension_expr], table="grouped")
+            for dimension_expr in dimension_exprs
+        ]
+        if dimension_group_id_alias is not None:
+            outer_group.append(exp.column(dimension_group_id_alias, table="grouped"))
+        if outer_group:
+            outer.group_by(
+                *outer_group,
+                copy=False,
+            )
+        return outer
+
+    def _reject_fanout_aggregate(
+        self,
+        ctx: ExpandContext,
+        aggregate: exp.AggFunc,
+        grain_alias: str,
+        referenced_aliases: set[str],
+        determined_by_grain: dict[str, dict[str, bool]],
+    ) -> None:
+        """Reject values that are not single-valued at the aggregate grain."""
+        determined = determined_by_grain.get(grain_alias)
+        if determined is None:
+            determined = {grain_alias: True}
+            alias = grain_alias
+            while alias in ctx.fanout_parents:
+                alias = ctx.fanout_parents[alias]
+                determined[alias] = True
+            determined_by_grain[grain_alias] = determined
+        for referenced_alias in referenced_aliases:
+            alias = referenced_alias
+            path: list[str] = []
+            while alias not in determined:
+                path.append(alias)
+                if alias in ctx.fanout_parents:
+                    determined[alias] = False
+                    break
+                parent = ctx.join_parents.get(alias)
+                if parent is None:
+                    determined[alias] = False
+                    break
+                alias = parent
+            is_determined = determined[alias]
+            for path_alias in path:
+                determined[path_alias] = is_determined
+            if not is_determined:
+                self._fail(ctx, "Aggregate crosses a fan-out join", aggregate)
+
+    def _grouping_id_expression(self, expressions: list[exp.Expr], copy: bool) -> exp.Expr:
+        result: exp.Expr | None = None
+        for index, expression in enumerate(expressions):
+            term: exp.Expr = exp.func("GROUPING", expression, copy=copy)
+            weight = 1 << (len(expressions) - index - 1)
+            if weight != 1:
+                term = exp.Mul(this=term, expression=exp.Literal.number(weight))
+            result = term if result is None else exp.Add(this=result, expression=term)
+        if result is None:
+            raise ValueError("GROUPING ID requires at least one expression")
+        return result
+
+    def _context_for_alias(self, ctx: ExpandContext, alias: str) -> ExpandContext:
+        if alias == ctx.alias:
+            return ctx
+        joined = ctx.datasets_by_alias.get(alias)
+        if joined is None:
+            return ctx
+        return replace(
+            ctx,
+            registry=joined[0],
+            dataset=joined[1],
+            alias=alias,
+            arguments=ctx.arguments_by_alias[alias],
+        )
+
+    def _expand_expr(
+        self,
+        expr: exp.Expr,
+        ctx: ExpandContext,
+        source_qualifier: exp.Identifier | None = None,
+        *,
+        calculation: bool = False,
+        agg: bool = False,
+    ) -> exp.Expr:
+        def recurse(node: exp.Expr) -> exp.Expr:
+            # `AGG(calc) FILTER (WHERE c)` filters every aggregate the calculation has, e.g.
+            # `SUM(a) - SUM(b)` becomes `SUM(a) FILTER (WHERE c) - SUM(b) FILTER (WHERE c)`, and
+            # an aggregate that already has a FILTER keeps it, ANDed with `c`.
+            if isinstance(node, exp.Filter) and isinstance(node.this, exp.Agg):
+                aggfunc = recurse(node.this)
+                condition = self._expand_expr(
+                    node.expression.this, ctx, source_qualifier, calculation=calculation, agg=agg
+                )
+
+                def filter_aggregate(inner: exp.Expr) -> exp.Expr:
+                    if isinstance(inner, exp.Filter):
+                        both = exp.and_(inner.expression.this, condition)
+                        return exp.Filter(this=inner.this, expression=exp.Where(this=both))
+                    if isinstance(inner, exp.AggFunc):
+                        return exp.Filter(this=inner, expression=exp.Where(this=condition.copy()))
+                    return inner
+
+                return aggfunc.transform(filter_aggregate, copy=False)
+            if isinstance(node, exp.Agg):
+                match node.this:
+                    case exp.Dot() as path:
+                        path_ctx = self._context_for_alias(ctx, path.parts[0].name)
+                        aggfunc = self._expand_relationship_path(path, path_ctx)
+                    case exp.Column() as column:
+                        column_ctx = self._context_for_alias(ctx, column.table)
+                        aggfunc = self._expand_col(column.this, column_ctx, agg=True)
+                    case _:
+                        self._fail(ctx, "Unsupported AGG argument", node)
+                if not is_aggregate_expression(aggfunc):
+                    self._fail(ctx, "AGG must be used on an aggregate calculation", node)
+                return aggfunc
+            if isinstance(node, exp.AggFunc):
+                ctx.aggregate_grains[id(node)] = ctx.alias
+            if calculation and isinstance(node, exp.Placeholder):
+                parameters = {name.name: name for name in ctx.dataset.parameters}
+                resolved = resolve_name(node.name, parameters)
+                if resolved is None:
+                    dataset = self._sql(ctx, ctx.dataset.name)
+                    self._fail(ctx, f"Dataset {dataset} has no parameter {node.name}")
+                name = parameters[resolved]
+                parameter = ctx.dataset.parameters[name]
+                return parameter_value(parameter, argument(ctx.arguments, name)).copy()
+            if isinstance(node, exp.Dot | exp.Column) and is_shadowed(node, node.parts[0].name):
+                return node
+            # A calculation's path from its dataset, e.g. `UPPER(customer.current_address.state)`.
+            # A query's paths start at an alias instead, which qualification adds.
+            if (
+                calculation
+                and isinstance(node, exp.Dot | exp.Column)
+                and isinstance(ctx.dataset.get_column(path_names(node)[0]), Relationship)
+            ):
+                return self._expand_path(list(path_names(node)), node, ctx)
+            # A field of a struct expression, e.g. `{'n': x}.n`, isn't a path, nor is a qualified
+            # function, e.g. `udfs.f(x)`.
+            if (
+                isinstance(node, exp.Dot)
+                and isinstance(node.this, exp.Column | exp.Dot)
+                and not isinstance(node.expression, exp.Func)
+            ):
+                path_ctx = self._context_for_alias(ctx, node.parts[0].name)
+                return self._expand_relationship_path(node, path_ctx)
+            if isinstance(node, exp.Column):
+                if not node.table or node.args["table"] == source_qualifier:
+                    return self._expand_col(node.this, ctx, agg=agg)
+                if node.table == ctx.alias or node.table in ctx.datasets_by_alias:
+                    column_ctx = self._context_for_alias(ctx, node.table)
+                    return self._expand_col(node.this, column_ctx, agg=agg)
+            return node
+
+        def expand(node: exp.Expr) -> exp.Expr:
+            expanded = recurse(node)
+            if expanded is node:
+                return node
+
+            # Like SQLGlot alias expansion, preserve grouping (c * 2 -> (a + b) * 2)
+            # and let its simplifier remove parentheses that the surrounding SQL doesn't need.
+            wrapped = node.replace(exp.paren(expanded, copy=False))
+            return simplify_parens(wrapped, ctx.dialect)
+
+        return expr.transform(expand)
+
+    def _sql(self, ctx: ExpandContext, name: exp.Expr) -> str:
+        return name.sql(ctx.registry.dialect)
+
+    def _expand_col(self, name: exp.Identifier, ctx: ExpandContext, *, agg: bool) -> exp.Expr:
+        field = ctx.dataset.get_column(name)
+
+        if not field and self.strict:
+            dataset = self._sql(ctx, ctx.dataset.name)
+            self._fail(ctx, f"Unknown field of dataset: {dataset}.{self._sql(ctx, name)}")
+
+        if isinstance(field, Column):
+            return self._physical_column(name, ctx.alias, field.datatype)
+        if isinstance(field, Calculation):
+            field_expr = field.expr
+            if not agg and projection_has_aggregate(field_expr):
+                return exp.null()
+            expanded = self._expand_expr(field_expr, ctx, calculation=True, agg=True)
+            return exp.null() if not agg and projection_has_aggregate(expanded) else expanded
+        if isinstance(field, Relationship):
+            return exp.null()
+        if field is None:
+            return exp.column(col=name, table=ctx.alias)
+        else:
+            self._fail(ctx, f"Unknown field type: {type(field).__name__}")
+
+    def _expand_relationship_path(self, dot: exp.Dot, ctx: ExpandContext) -> exp.Expr:
+        head, *tail = path_names(dot)
+        if head.name != ctx.alias:
+            self._fail(ctx, "Unsupported relationship path", dot)
+        return self._expand_path(tail, dot, ctx)
+
+    def _expand_path(
+        self, parts: list[exp.Identifier], expr: exp.Expr, ctx: ExpandContext
+    ) -> exp.Expr:
+        # The walk alternates namespaces: a segment resolves against a dataset's
+        # fields, or while a relationship is pending, against that entity's
+        # attributes, whose source-qualified expressions continue the walk.
+        dataset = ctx.dataset
+        dataset_alias = ctx.alias
+        relationship: Relationship | None = None
+        entity: EntityProxy | None = None
+        cardinality = Cardinality.MANY_TO_ONE
+        remaining = deque(parts)
+        while remaining:
+            name = remaining.popleft()
+            if relationship is None or entity is None:
+                match dataset.get_column(name):
+                    case Relationship() as field:
+                        if not remaining:
+                            return exp.null()
+                        match self._relationship_target(ctx, field):
+                            case EntityTarget(entity=target_entity), target_cardinality:
+                                relationship, entity = field, target_entity
+                                cardinality = target_cardinality
+                            case DatasetTarget(dataset=target), cardinality:
+                                # Like an entity's key, a many-to-one key's field needs no join.
+                                if (
+                                    cardinality is Cardinality.MANY_TO_ONE
+                                    and len(remaining) == 1
+                                    and remaining[0] in field.key
+                                    and target.get_column(remaining[0]) is not None
+                                ):
+                                    value = field.key[remaining[0]]
+                                    return self._key_value(ctx, value, dataset, dataset_alias)
+                                dataset_alias = self._register_dataset_join(
+                                    ctx, field, target, cardinality, dataset, dataset_alias
+                                )
+                                dataset = target
+                    case Column(datatype=datatype):
+                        if remaining:
+                            self._fail(ctx, "Unsupported relationship path", expr)
+                        return self._physical_column(name, dataset_alias, datatype)
+                    case Calculation() as calc:
+                        return self._expand_expr(
+                            calc.expr,
+                            replace(ctx, dataset=dataset, alias=dataset_alias),
+                            calculation=True,
+                            agg=True,
+                        )
+                    case _:
+                        self._fail(ctx, "Unsupported relationship path", expr)
+                continue
+            # Like a dataset's, a many-to-one key's column needs no join; a one-to-many one's rows do.
+            if name in relationship.key and cardinality is Cardinality.MANY_TO_ONE:
+                if remaining:
+                    self._fail(ctx, "Unsupported relationship path", expr)
+                return self._key_value(ctx, relationship.key[name], dataset, dataset_alias)
+            attribute = entity.get_column(name)
+            if attribute is None:
+                entity_name = self._sql(ctx, entity.name)
+                self._fail(ctx, f"Unknown attribute: {entity_name}.{self._sql(ctx, name)}")
+            attr_expr = attribute.expr
+            if isinstance(attr_expr, exp.Column | exp.Dot):
+                if len(attr_expr.parts) < 2:
+                    self._fail(ctx, "Unsupported attribute expression", attr_expr)
+                source, attr_path = self._attribute_source(ctx, entity, attr_expr)
+                dataset_alias = self._register_join(
+                    ctx, relationship, entity, cardinality, source, dataset, dataset_alias
+                )
+                relationship, entity = None, None
+                dataset = self._dataset_for(ctx, source.dataset)
+                remaining.extendleft(reversed(attr_path))
+                continue
+            # A general expression over one source dataset's columns.
+            source = self._single_source(ctx, entity, attr_expr, "Unsupported attribute expression")
+            if remaining:
+                self._fail(ctx, "Unsupported relationship path", expr)
+            join_alias = self._register_join(
+                ctx, relationship, entity, cardinality, source, dataset, dataset_alias
+            )
+            return self._expand_expr(
+                attr_expr,
+                replace(ctx, dataset=self._dataset_for(ctx, source.dataset), alias=join_alias),
+                source_qualifier=source.dataset.this,
+                agg=True,
+            )
+        self._fail(ctx, "Unsupported relationship path", expr)
+
+    def _physical_column(
+        self, name: exp.Identifier, alias: str, datatype: exp.DataType | None
+    ) -> exp.Expr:
+        column = exp.column(col=name, table=alias)
+        if datatype:
+            column.type = datatype.copy()
+        return column
+
+    def _dataset_for(self, ctx: ExpandContext, name: exp.Table) -> DatasetProxy:
+        dataset = ctx.registry.get_dataset(name)
+        if dataset is None:
+            self._fail(ctx, f"Unknown dataset: {self._sql(ctx, name)}")
+        return dataset
+
+    def _entity(self, ctx: ExpandContext, name: exp.Table) -> EntityProxy:
+        entity = ctx.registry.get_entity(name)
+        if entity is None:
+            self._fail(ctx, f"Unknown entity: {self._sql(ctx, name)}")
+        return entity
+
+    def _attribute_source(
+        self, ctx: ExpandContext, entity: EntityProxy, column: exp.Column | exp.Dot
+    ) -> tuple[Source, tuple[exp.Identifier, ...]]:
+        reference = resolve_attribute_reference(entity, column)
+        source = reference.source or self._entity_source(ctx, entity, reference.dataset)
+        return source, reference.path
+
+    def _single_source(
+        self, ctx: ExpandContext, entity: EntityProxy, expr: exp.Expr, message: str
+    ) -> Source:
+        sources: dict[Id, Source] = {}
+        for reference in resolve_attribute_references(entity, expr):
+            source = reference.source or self._entity_source(ctx, entity, reference.dataset)
+            sources[source.id] = source
+        if len(sources) != 1:
+            self._fail(ctx, message, expr)
+        return next(iter(sources.values()))
+
+    def _relationship_target(
+        self, ctx: ExpandContext, relationship: Relationship
+    ) -> tuple[RelationshipTarget, Cardinality]:
+        """What `relationship` targets, and its cardinality, checked against a declared one."""
+        try:
+            target = relationship_target(ctx.registry, relationship)
+            return target, relationship_cardinality(relationship, target, ctx.registry.dialect)
+        except SchemaError as error:
+            self._fail(ctx, str(error))
+
+    def _entity_source(self, ctx: ExpandContext, entity: EntityProxy, dataset: exp.Table) -> Source:
+        source = entity.get_source(dataset)
+        if source is None:
+            entity_name, dataset_name = self._sql(ctx, entity.name), self._sql(ctx, dataset)
+            self._fail(ctx, f"No source for {entity_name} on {dataset_name}")
+        return source
+
+    def _grain(self, ctx: ExpandContext, alias: str) -> tuple[exp.Expr, ...]:
+        """
+        Expressions identifying the rows of the source `alias`: its dataset's key, else the key of
+        the entity source it was joined through, else of its dataset's only entity source.
+        """
+        dataset = self._dataset_at(ctx, alias)
+        key = dataset.key
+        # A condition's parameters aren't fields of the rows, so they can't identify them.
+        if key is not None and not key.conditions():
+            alias_ctx = replace(ctx, dataset=dataset, alias=alias)
+            return tuple(self._expand_col(name, alias_ctx, agg=False) for name in key.fields())
+        source = ctx.grain_sources.get(alias)
+        if source is not None:
+            return self._entity_keys_from_on(ctx, source, alias)
+        grains = {
+            frozenset(keys): keys
+            for keys in (
+                self._entity_keys_from_on(ctx, entity_source, alias)
+                for entity_source in dataset.get_entity_sources().values()
+            )
+        }
+        if len(grains) != 1:
+            reason = "its key has a condition" if key is not None else "give it a key"
+            self._fail(ctx, f"Cannot determine the grain of {dataset.name}: {reason}")
+        return next(iter(grains.values()))
+
+    def _dataset_at(self, ctx: ExpandContext, alias: str) -> DatasetProxy:
+        """The dataset the source `alias` reads: the root, a generated join, or a user join."""
+        if alias == ctx.root_alias:
+            return ctx.dataset
+        if alias in ctx.join_datasets:
+            return ctx.join_datasets[alias]
+        return ctx.datasets_by_alias[alias][1]
+
+    def _entity_keys_from_on(
+        self, ctx: ExpandContext, source: Source, alias: str
+    ) -> tuple[exp.Expr, ...]:
+        entity = self._entity(ctx, source.entity)
+        keys = {name.name: name for name in entity.key}
+        pending = [source.on]
+        bindings: dict[exp.Identifier, exp.Expr] = {}
+        while pending:
+            clause = pending.pop().unnest()
+            match clause:
+                case exp.And(this=left, expression=right):
+                    pending.extend((right, left))
+                    continue
+                case (
+                    exp.EQ(this=exp.Placeholder() as key, expression=value)
+                    | exp.EQ(this=value, expression=exp.Placeholder() as key)
+                ):
+                    resolved = resolve_name(key.name, keys)
+                    if resolved is None:
+                        entity_name = self._sql(ctx, source.entity)
+                        self._fail(ctx, f"Cannot derive {entity_name} key from source", source.on)
+                    name = keys[resolved]
+                    if name in bindings or value.find(exp.Placeholder) is not None:
+                        self._fail(ctx, "Ambiguous source key binding", clause)
+                    bindings[name] = self._qualify_key(value, alias)
+                case _:
+                    continue
+
+        if not entity.key or bindings.keys() != entity.key.keys():
+            entity_name = self._sql(ctx, source.entity)
+            self._fail(ctx, f"Cannot derive {entity_name} key from source", source.on)
+        return tuple(bindings[name] for name in entity.key)
+
+    def _join_alias_for_path(
+        self, ctx: ExpandContext, parent_alias: str, name: exp.Identifier, dataset: exp.Table
+    ) -> str:
+        path = (parent_alias, name, dataset)
+        if path in ctx.join_aliases:
+            return ctx.join_aliases[path]
+
+        base = name.name if parent_alias == ctx.root_alias else f"{parent_alias}_{name.name}"
+        alias = find_new_name(ctx.used_aliases, base)
+        ctx.used_aliases.add(alias)
+        ctx.join_aliases[path] = alias
+        ctx.join_parents[alias] = parent_alias
+        ctx.join_depths[alias] = ctx.join_depths.get(parent_alias, 0) + 1
+        return alias
+
+    def _register_join(
+        self,
+        ctx: ExpandContext,
+        relationship: Relationship,
+        entity: EntityProxy,
+        cardinality: Cardinality,
+        source: Source,
+        parent: DatasetProxy,
+        parent_alias: str,
+    ) -> str:
+        """
+        Joins the entity `source` a path reads, through `relationship` from `parent`: on its `on`
+        if many-to-one, else on the fields the key binds, fanning out.
+        """
+        alias = self._join_alias_for_path(ctx, parent_alias, relationship.name, source.dataset)
+        if cardinality is Cardinality.ONE_TO_MANY:
+            ctx.fanout_grain_by_alias[alias] = alias
+            ctx.fanout_parents[alias] = parent_alias
+        elif parent_alias in ctx.fanout_grain_by_alias:
+            ctx.fanout_grain_by_alias[alias] = ctx.fanout_grain_by_alias[parent_alias]
+        if alias in ctx.joins:
+            return alias
+        dataset = self._dataset_for(ctx, source.dataset)
+        ctx.join_datasets[alias] = dataset
+        # The entity's key, from the source's `on`, is the grain of the rows it joins.
+        ctx.grain_sources[alias] = source
+        values = self._key_values(ctx, relationship.key, parent, parent_alias)
+        on = (
+            self._bind_join_keys(ctx, source.on, values, alias)
+            if cardinality is Cardinality.MANY_TO_ONE
+            else self._entity_join_on(ctx, relationship, entity, source, dataset, alias, values)
+        )
+        ctx.joins[alias] = exp.Join(
+            this=exp.alias_(dataset.from_(ctx.arguments), alias, copy=False), on=on, side="LEFT"
+        )
+        return alias
+
+    def _entity_join_on(
+        self,
+        ctx: ExpandContext,
+        relationship: Relationship,
+        entity: EntityProxy,
+        source: Source,
+        dataset: DatasetProxy,
+        alias: str,
+        values: dict[exp.Identifier, exp.Expr],
+    ) -> exp.Expr:
+        """
+        The condition joining the entity `source`, its `dataset` as `alias`, to the `values` of a
+        one-to-many relationship's key.
+        """
+        keys = dict(zip(entity.key, self._entity_keys_from_on(ctx, source, alias), strict=True))
+        source_ctx = replace(ctx, dataset=dataset, alias=alias)
+        terms: list[exp.Expr] = []
+        for name, value in values.items():
+            if name in keys:
+                field = keys[name]
+            else:
+                match entity.get_column(name):
+                    case Attribute(expr=exp.Column() as column) if (
+                        self._attribute_source(ctx, entity, column)[0] == source
+                    ):
+                        field = self._expand_col(column.this, source_ctx, agg=False)
+                    case _:
+                        where = (
+                            f"{self._sql(ctx, relationship.dataset)}."
+                            f"{self._sql(ctx, relationship.name)}"
+                        )
+                        self._fail(
+                            ctx,
+                            f"Relationship {where} binds {self._sql(ctx, entity.name)}."
+                            f"{self._sql(ctx, name)}, which isn't a column of the source it "
+                            f"reads, {self._sql(ctx, source.dataset)}",
+                        )
+            terms.append(field.eq(value.copy()))
+        return exp.and_(*terms, copy=False)
+
+    def _register_dataset_join(
+        self,
+        ctx: ExpandContext,
+        relationship: Relationship,
+        target: DatasetProxy,
+        cardinality: Cardinality,
+        parent: DatasetProxy,
+        parent_alias: str,
+    ) -> str:
+        """Joins `target` through `relationship` from `parent`, fanning out if one-to-many."""
+        alias = self._join_alias_for_path(ctx, parent_alias, relationship.name, target.name)
+        if cardinality is Cardinality.ONE_TO_MANY:
+            ctx.fanout_grain_by_alias[alias] = alias
+            ctx.fanout_parents[alias] = parent_alias
+        elif parent_alias in ctx.fanout_grain_by_alias:
+            ctx.fanout_grain_by_alias[alias] = ctx.fanout_grain_by_alias[parent_alias]
+        if alias in ctx.joins:
+            return alias
+        ctx.join_datasets[alias] = target
+        values = self._key_values(ctx, relationship.key, parent, parent_alias)
+        ctx.joins[alias] = exp.Join(
+            this=exp.alias_(target.from_(ctx.arguments), alias, copy=False),
+            on=self._dataset_join_on(ctx, relationship, target, alias, values),
+            side="LEFT",
+        )
+        return alias
+
+    def _dataset_join_on(
+        self,
+        ctx: ExpandContext,
+        relationship: Relationship,
+        target: DatasetProxy,
+        alias: str,
+        values: dict[exp.Identifier, exp.Expr],
+    ) -> exp.Expr:
+        """
+        The condition joining `target` as `alias` to the `values` of a relationship's key: each
+        field it binds equal to its value, in the order of the target's key, then the
+        relationship's, and each condition of the target's key, its placeholders bound, e.g.
+        `sr.sr_item_sk = ss.ss_item_sk AND sr.sr_ticket_number = ss.ss_ticket_number`.
+        """
+        where = (
+            f"Relationship {self._sql(ctx, relationship.dataset)}."
+            f"{self._sql(ctx, relationship.name)}"
+        )
+        target_name = self._sql(ctx, target.name)
+        target_ctx = replace(ctx, dataset=target, alias=alias)
+        key = target.key
+        conditions = key.conditions() if key is not None else ()
+        parameters = {name for condition in conditions for name in condition.parameters}
+        fields = dict.fromkeys((*(key.fields() if key is not None else ()), *relationship.key))
+        terms: list[exp.Expr] = [
+            self._expand_col(name, target_ctx, agg=False).eq(values[name].copy())
+            for name in fields
+            if name in values and name not in parameters
+        ]
+        for condition in conditions:
+            bound = condition.parameters.keys() & values.keys()
+            if not bound:
+                continue
+            if bound != condition.parameters.keys():
+                self._fail(
+                    ctx,
+                    f"{where} binds {sorted(name.name for name in bound)} but not all "
+                    f"placeholders of a key condition of {target_name}, "
+                    f"{sorted(name.name for name in condition.parameters)}",
+                )
+            # The condition's own columns are the target's; its placeholders are bound after.
+            on = self._expand_expr(condition.on, target_ctx)
+            terms.append(self._bind_join_keys(ctx, on, values, alias))
+        if not terms:
+            self._fail(ctx, f"{where} binds nothing of {target_name}")
+        return exp.and_(*terms, copy=False)
+
+    def _key_values(
+        self,
+        ctx: ExpandContext,
+        key: dict[exp.Identifier, exp.Expr],
+        dataset: DatasetProxy,
+        alias: str,
+    ) -> dict[exp.Identifier, exp.Expr]:
+        """A relationship's key, read from `dataset` joined as `alias`."""
+        return {name: self._key_value(ctx, expr, dataset, alias) for name, expr in key.items()}
+
+    def _key_value(
+        self, ctx: ExpandContext, expr: exp.Expr, dataset: DatasetProxy, alias: str
+    ) -> exp.Expr:
+        """
+        A value of a relationship's key, read from `dataset` joined as `alias` like a calculation
+        is, so it can read other fields and paths, e.g. `_item.i_item_id`.
+        """
+        return self._expand_expr(
+            expr, replace(ctx, dataset=dataset, alias=alias), calculation=True, agg=False
+        )
+
+    def _bind_join_keys(
+        self,
+        ctx: ExpandContext,
+        on: exp.Expr,
+        values: dict[exp.Identifier, exp.Expr],
+        source_alias: str,
+    ) -> exp.Expr:
+        """
+        Binds the `:name` placeholders of `on` to `values`, and qualifies its own columns with
+        `source_alias`, e.g. `c_customer_sk = :sk` gives `customer.c_customer_sk = ss_customer_sk`.
+        """
+
+        names = {name.name: name for name in values}
+
+        def bind(node: exp.Expr) -> exp.Expr:
+            if isinstance(node, exp.Placeholder):
+                resolved = resolve_name(node.name, names)
+                if resolved is None:
+                    self._fail(ctx, f"Unbound join key: :{node.name}")
+                return values[names[resolved]].copy()
+            if isinstance(node, exp.Column) and not node.table:
+                return exp.column(node.this, table=source_alias)
+            return node
+
+        return on.transform(bind)
+
+    def _qualify_key(self, key_expr: exp.Expr, alias: str) -> exp.Expr:
+        return key_expr.transform(
+            lambda node: (
+                exp.column(node.this, table=alias)
+                if isinstance(node, exp.Column) and not node.table
+                else node
+            ),
+        )