metricflow-sql 0.1.1__py3-none-any.whl

metricflow_sql/converters/lookml.py

@@ -0,0 +1,1041 @@
+"""Converts a Looker explore into a v1 fragment, and LookML that queries it through the server.
+
+    uv run python -m metricflow_sql.converters.lookml ../analytics/fivetran.model.lkml revenue \\
+      --connection metricflow \\
+      --user-attribute dbt_ft_prod_schema=transforms_bi --out out/revenue
+
+Each view becomes a dataset and a LookML view of the same name, shared by explores, and each
+joined view an entity, e.g. `accounts_entity`. Each explore becomes a constellation its LookML
+reads, joining nothing, e.g.
+
+    SELECT accounts.region, AGG(revenue__annual_revenue), AGG(accounts__account_count)
+    FROM metrics.public.revenue_explore(since => ...) AS revenue
+
+where `accounts` is a role, the relationship to it from `revenue`, and each view's measure a
+metric, named the same in every explore so its view can be shared. A view another explore joins
+differently gets a relationship of its own, e.g. `current_regions__region_history`. What can't be
+converted is left out, and reported.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import operator
+import re
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+import lkml
+import sqlglot
+from sqlglot import exp
+from sqlglot.errors import SqlglotError
+
+from metricflow_sql.objects.base import DEFAULT_NAMESPACE
+from metricflow_sql.utils.normalize import read_table, strategy_of
+from metricflow_sql.utils.ordered_set import OrderedSet
+from metricflow_sql.utils.sql import ref_type
+
+logger = logging.getLogger(__name__)
+
+# A column of the view's table, e.g. `${TABLE}.month`.
+_TABLE_COLUMN = re.compile(r"\$\{TABLE\}\.(\w+)")
+# A field, e.g. `${month}`, or another view's, e.g. `${accounts.region}`.
+_REF = re.compile(r"\$\{(\w+)(?:\.(\w+))?\}")
+# Liquid, e.g. `{% if x %}` or `{{ value }}`.
+_LIQUID = re.compile(r"\{[{%]")
+# A user attribute, e.g. `{{ _user_attributes['schema'] }}`.
+_USER_ATTRIBUTE = re.compile(r"\{\{\s*_user_attributes\['(\w+)'\]\s*\}\}")
+# A parameter, e.g. `{% parameter since %}`.
+_PARAMETER = re.compile(r"\{%\s*parameter\s+(\w+)\s*%\}")
+# Whether the query reads a field, which Looker knows, e.g. `accounts.region._in_query`.
+_QUERY_FLAG = re.compile(r"\b\w+\.(\w+)\._(in_query|is_filtered|is_selected)\b")
+# An `if` on query flags once they're parameters, e.g. `{% if :region_in_query %} a {% else %} b
+# {% endif %}`.
+_FLAG_IF = re.compile(
+    r"\{%\s*if\s+(:\w+(?:\s+(?:and|or)\s+:\w+)*)\s*%\}(.*?)\{%\s*else\s*%\}(.*?)\{%\s*endif\s*%\}",
+    re.DOTALL,
+)
+# A dashboard query's model and explore, e.g. `model: fivetran\n  explore: revenue`.
+_DASHBOARD_QUERY = re.compile(r"(model: )\S+(\n\s+explore: (\w+))")
+# A number filter's comparison and number, e.g. `<>0`, `>=31` or `5`.
+_NUMBER_FILTER = re.compile(r"(<>|<=|>=|<|>|=)?\s*(-?\d+(?:\.\d+)?)")
+# Looker's string filter syntax beyond one pattern: a list, e.g. `Pro,Enterprise`, an escape,
+# e.g. `50^%`, `EMPTY`, or a backtick, which the drill's filter expression quotes with.
+_STRING_SYNTAX = re.compile(r"[,^`]|\bEMPTY\b", re.IGNORECASE)
+
+# The explore's SQL is BigQuery's, as is what the converter writes.
+_DIALECT = "bigquery"
+# The SQL Looker sends the server, for the converted LookML's.
+_LOOKML_DIALECT = "trino"
+# Stands in for a reference while LookML's SQL parses, e.g. `${accounts.region}`.
+_PLACEHOLDER = "__lookml_{}"
+
+
+type _Template = Callable[[exp.Expr], exp.Expr]
+
+# The SQL Looker writes for a dimension group's timeframe, e.g. `${created_month}`.
+_TIMEFRAMES: dict[str, _Template] = {
+    "raw": lambda sql: sql,
+    "date": lambda sql: exp.func("DATE", sql, dialect=_DIALECT),
+    "month": lambda sql: exp.func(
+        "FORMAT_DATETIME", exp.Literal.string("%Y-%m"), sql, dialect=_DIALECT
+    ),
+}
+_COUNT_DISTINCT = sqlglot.parse_one("COUNT(DISTINCT :sql)", read=_DIALECT)
+_AGGREGATES: dict[str, _Template] = {
+    "sum": lambda sql: exp.func("COALESCE", exp.func("SUM", sql), 0),
+    "count": lambda sql: exp.func("COUNT", sql),
+    "count_distinct": lambda sql: exp.replace_placeholders(_COUNT_DISTINCT, sql=sql),
+    "average": lambda sql: exp.func("AVG", sql),
+    "max": lambda sql: exp.func("MAX", sql),
+    "number": lambda sql: sql,
+}
+# A number filter's comparisons, e.g. `<>0`.
+_COMPARISONS: dict[str, Callable[[exp.Expr, exp.Expr], exp.Expr]] = {
+    "<>": lambda sql, number: sql.neq(number),
+    "<=": operator.le,
+    ">=": operator.ge,
+    "<": operator.lt,
+    ">": operator.gt,
+    "=": lambda sql, number: sql.eq(number),
+}
+_PARAMETER_TYPES = {"date": "DATE", "number": "FLOAT64", "string": "STRING"}
+# The joins a relationship can express, and Looker's default.
+_RELATIONSHIPS = ("many_to_one", "one_to_one")
+_DEFAULT_RELATIONSHIP = "many_to_one"
+_FIELD_KINDS = ("parameters", "filters", "dimensions", "dimension_groups", "measures")
+# Each explore can add to these, e.g. a relationship to a view only it joins, or a LookML view's
+# field only it converts; the rest must agree.
+_UNITED = ("calculations", "relationships", "attributes", *_FIELD_KINDS, "sets")
+# Keys holding lists of field references, e.g. `fields: [accounts.core_fields*]`.
+_FIELD_LISTS = ("fields", "drill_fields", "required_fields")
+
+
+@dataclass(frozen=True)
+class Conversion:
+    fragment: dict[str, Any]
+    """A v1 fragment."""
+    lookml: dict[str, str]
+    """LookML files, keyed by file name."""
+    skipped: dict[str, list[str]]
+    """Fields left out, e.g. `revenue.owner_label`, keyed by why."""
+
+
+class _Skip(Exception):
+    pass
+
+
+type _Resolve = Callable[[str, str, str], exp.Expr]
+# A field's calculation, its converted LookML's SQL for a `filter` or a parameter, which Looker
+# renders, or why it was skipped.
+type _Result = exp.Expr | str | _Skip
+
+
+@dataclass
+class _Converter:
+    views: dict[str, dict[str, Any]]
+    explore: dict[str, Any]
+    user_attributes: dict[str, str]
+    relationships: dict[str, str] = field(default_factory=dict)
+    """By joined view, e.g. `{region_history: current_regions__region_history}`; else its name."""
+    entities: dict[str, str] = field(default_factory=dict)
+    """By joined view; else e.g. `accounts_entity`."""
+    timezone: str | None = None
+    """Looker's query timezone, which converts the time dimension groups that don't opt out."""
+    base: str = field(init=False)
+    parents: dict[str, str] = field(init=False)
+    """The view each joined view hangs off."""
+    paths: dict[str, list[str]] = field(init=False)
+    """The relationship path from the base view to each view in the explore."""
+    definitions: dict[tuple[str, str], tuple[str, dict[str, Any]]] = field(init=False)
+    columns: dict[str, OrderedSet[str]] = field(init=False)
+    """Every `${TABLE}.col` each view's LookML reads."""
+    results: dict[tuple[str, str], _Result] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.base = self.explore.get("view_name", self.explore["name"])
+        self.parents, self.paths = {}, {self.base: []}
+        for join in self.joins():
+            view = join["name"]
+            (self.parents[view],) = {match[1] for match in _REF.finditer(join["sql_on"])} - {view}
+            self.paths[view] = [*self.paths[self.parents[view]], view]
+        self.definitions = {
+            (view, definition["name"]): (kind, definition)
+            for view in self.paths
+            for kind, definition in self.fields(view)
+        }
+        self.columns = {
+            view: OrderedSet(c.lower() for c in _TABLE_COLUMN.findall(json.dumps(self.views[view])))
+            for view in self.paths
+        }
+
+    def joins(self) -> list[dict[str, Any]]:
+        """The explore's joins that relationships can express."""
+        return [
+            join for join in self.explore.get("joins", []) if _relationship(join) in _RELATIONSHIPS
+        ]
+
+    def fields(self, view: str) -> Iterator[tuple[str, dict[str, Any]]]:
+        for kind in _FIELD_KINDS:
+            for definition in self.views[view].get(kind, []):
+                yield kind, definition
+
+    def definition(self, view: str, name: str) -> tuple[str, dict[str, Any]]:
+        """A field's kind and definition, or empty ones when `view` has no such field."""
+        return self.definitions.get((view, name), ("", {}))
+
+    def result(self, view: str, name: str) -> _Result:
+        key = (view, name)
+        if key not in self.results:
+            try:
+                self.results[key] = self.convert(view, *self.definition(view, name))
+            except _Skip as skip:
+                self.results[key] = skip
+        return self.results[key]
+
+    def convert(self, view: str, kind: str, definition: dict[str, Any]) -> exp.Expr | str:
+        match kind:
+            # Looker renders parameters and filters' Liquid before it queries.
+            case "parameters":
+                return ""
+            case "filters":
+                return self.filter_sql(view, definition["sql"])
+            case "measures":
+                return self.measure(view, definition)
+            case _:
+                return self.dimension(view, definition, self.reference)
+
+    def measure(self, view: str, definition: dict[str, Any]) -> exp.Expr:
+        aggregate = _AGGREGATES.get(definition["type"])
+        if aggregate is None:
+            raise _Skip(f"measure type {definition['type']}")
+        sql = (
+            self.translate(view, definition["sql"], self.reference)
+            if "sql" in definition
+            else exp.Literal.number(1)
+        )
+        conditions = [
+            _condition(self.reference(view, *name.rsplit(".", 1)), value, self.datatype(name))
+            for name, value in self.filters(view, definition)
+        ]
+        if conditions:
+            sql = exp.case().when(exp.and_(*conditions), sql).else_(exp.null())
+        return aggregate(sql)
+
+    def dimension(self, view: str, definition: dict[str, Any], resolve: _Resolve) -> exp.Expr:
+        """A dimension's SQL as Looker renders it: a `case` one as a CASE, a `date` one as a
+        DATE, and a dimension group's as a DATETIME, in the timezone when it converts."""
+        if "case" in definition:
+            lookml_case = definition["case"]
+            if "else" not in lookml_case:
+                raise _Skip("case without else")
+            sql_case = exp.case()
+            for when in lookml_case["whens"]:
+                sql_case = sql_case.when(
+                    self.translate(view, when["sql"], resolve), exp.Literal.string(when["label"])
+                )
+            return sql_case.else_(exp.Literal.string(lookml_case["else"]))
+        if "sql" not in definition:
+            raise _Skip("dimension without sql")
+        sql = self.translate(view, str(definition["sql"]), resolve)
+        if definition.get("type") == "date":
+            return _TIMEFRAMES["date"](sql)
+        if definition.get("type") == "time":
+            # The generated connection has no timezone, so Looker converts nothing; converting here
+            # matches what Looker renders for BigQuery. It never converts a `datatype: date`.
+            if (
+                self.timezone
+                and definition.get("convert_tz") != "no"
+                and definition.get("datatype") != "date"
+            ):
+                return exp.func(
+                    "DATETIME", sql, exp.Literal.string(self.timezone), dialect=_DIALECT
+                )
+            return exp.cast(sql, "DATETIME", dialect=_DIALECT)
+        return sql
+
+    def filters(self, view: str, measure: dict[str, Any]) -> list[tuple[str, str]]:
+        """A measure's `filters`, in either form: `{field, value}` or `[field: value, ...]`, by
+        the field's name in the explore, e.g. `revenue.tier`, and once each, as LookML can state
+        a filter in both."""
+        # Looker only filters the measures that aggregate.
+        if measure.get("type") == "number":
+            return []
+        filters = []
+        for entry in measure.get("filters__all", []):
+            match entry:
+                case {"field": name, "value": value}:
+                    filters.append((name, value))
+                case list():
+                    filters.extend(pair for item in entry for pair in item.items())
+        # Looker reads an empty value as any value.
+        return list(
+            dict.fromkeys(
+                (name if "." in name else f"{view}.{name}", value)
+                for name, value in filters
+                if value
+            )
+        )
+
+    def datatype(self, name: str) -> str:
+        """The type of the field a filter names, e.g. `accounts.region`: a dimension's, or `date`
+        for a dimension group's timeframe, e.g. `accounts.closed_quarter`."""
+        view, _, field_name = name.rpartition(".")
+        kind, definition = self.definition(view, field_name)
+        match kind:
+            case "dimensions":
+                return str(definition.get("type", "string"))
+            case "measures":
+                return "measure"
+        return "date"
+
+    def translate(self, view: str, sql: str, resolve: _Resolve) -> exp.Expr:
+        """Parses LookML `sql` into an expression on `view`'s dataset: its `${TABLE}.col` is the
+        column, its parameters and query flags placeholders, e.g. `:since`, an `if` on flags a
+        CASE, and a reference what `resolve` makes of it."""
+        sql = _QUERY_FLAG.sub(lambda match: f":{_flag(match)}", _PARAMETER.sub(r":\1", sql))
+        # Each reference and `if`, by the placeholder standing in for it while the SQL parses.
+        nodes: dict[str, exp.Expr] = {}
+
+        def stand_in(node: exp.Expr) -> str:
+            name = _PLACEHOLDER.format(len(nodes))
+            nodes[name] = node
+            return f":{name}"
+
+        def flag_if(match: re.Match[str]) -> str:
+            # Liquid has no precedence, and reads `a and b or c` as `a and (b or c)`.
+            *rest, last = re.split(r"\s+(and|or)\s+", match[1])
+            condition: exp.Expr = exp.var(last)
+            for operand, connective in reversed(list(zip(rest[::2], rest[1::2], strict=True))):
+                combine = exp.and_ if connective == "and" else exp.or_
+                condition = combine(exp.var(operand), condition)
+            then, otherwise = (
+                self.translate(view, branch, resolve) for branch in match.groups()[1:]
+            )
+            return stand_in(exp.case().when(condition, then).else_(otherwise))
+
+        def reference(match: re.Match[str]) -> str:
+            return stand_in(resolve(view, *_target(view, match)))
+
+        sql = _FLAG_IF.sub(flag_if, sql)
+        if _LIQUID.search(sql):
+            raise _Skip("Liquid")
+        # A column stands in too, so one named like a keyword, e.g. `end`, parses.
+        sql = _TABLE_COLUMN.sub(lambda match: stand_in(exp.column(match[1])), sql)
+        sql = _REF.sub(reference, sql)
+        try:
+            parsed = sqlglot.parse_one(sql, read=_DIALECT)
+        except SqlglotError:
+            raise _Skip("SQL it can't parse") from None
+        names = {placeholder.name for placeholder in parsed.find_all(exp.Placeholder)}
+        # A stand-in the SQL doesn't read as a placeholder, e.g. in a string, can't be replaced.
+        if not nodes.keys() <= names:
+            raise _Skip("SQL it can't parse")
+        # Parameters stay as the fragment reads them, e.g. `:since`, rather than BigQuery's `@since`.
+        return exp.replace_placeholders(
+            parsed, **{name: nodes.get(name, exp.var(f":{name}")) for name in names}
+        )
+
+    def filter_sql(self, view: str, sql: str) -> str:
+        """A `filter` field's SQL as the converted LookML writes it, with its columns and
+        references read by their views' names. Looker renders its `{% condition %}` into SQL,
+        so it stays a template."""
+        sql = _TABLE_COLUMN.sub(lambda match: _path([view, match[1]]).sql(_LOOKML_DIALECT), sql)
+
+        def reference(match: re.Match[str]) -> str:
+            return self.path(*_target(view, match)).sql(_LOOKML_DIALECT)
+
+        return _REF.sub(reference, sql)
+
+    def calculation(self, view: str, kind: str, name: str) -> str:
+        """The dataset field a LookML field converts to, renamed when it would shadow a column."""
+        if kind == "dimensions" and _is_column(self.result(view, name), name):
+            return name
+        calculation = (f"{name}_raw" if kind == "dimension_groups" else name).lower()
+        if calculation in self.columns[view]:
+            return f"{calculation}_{kind.removesuffix('s')}"
+        return calculation
+
+    def name(self, view: str, name: str) -> tuple[str, str, _Template]:
+        """The field a reference reads, its calculation, and the template applied to it."""
+        kind = self.definition(view, name)[0]
+        group, _, timeframe = name.rpartition("_")
+        template = _TIMEFRAMES["raw"]
+        if kind not in ("dimensions", "measures"):
+            if (
+                self.definition(view, group)[0] != "dimension_groups"
+                or timeframe not in _TIMEFRAMES
+            ):
+                raise _Skip("references a field that isn't a dimension or measure")
+            name, kind, template = group, "dimension_groups", _TIMEFRAMES[timeframe]
+        if isinstance(self.result(view, name), _Skip):
+            raise _Skip("references a skipped field")
+        return name, self.calculation(view, kind, name), template
+
+    def reference(self, view: str, target: str, name: str) -> exp.Expr:
+        """A reference by name, through the relationships from `view` to `target`."""
+        prefix = self.paths[view]
+        path = self.paths.get(target)
+        if path is None or path[: len(prefix)] != prefix:
+            raise _Skip("references a view it doesn't join")
+        _, calculation, template = self.name(target, name)
+        return template(_path([*self.relationship_path(path[len(prefix) :]), calculation]))
+
+    def relationship_name(self, view: str) -> str:
+        return self.relationships.get(view, view)
+
+    def relationship_path(self, views: list[str]) -> list[str]:
+        return [self.relationship_name(view) for view in views]
+
+    def entity_name(self, view: str) -> str:
+        return self.entities.get(view, _entity_name(view))
+
+    def path(self, view: str, name: str) -> exp.Expr:
+        """A reference as the converted LookML writes it, e.g. `accounts.region`."""
+        _, calculation, template = self.name(view, name)
+        return template(_path([view, calculation]))
+
+    def inline(self, view: str, target: str, name: str) -> exp.Expr:
+        """A reference expanded to its columns, since join keys can't read calculations."""
+        resolved, _, template = self.name(target, name)
+        return template(self.dimension(target, self.definition(target, resolved)[1], self.inline))
+
+    def parameters(self, view: str) -> dict[str, tuple[str, dict[str, Any]]]:
+        """The parameters `view`'s LookML reads, by name: the Liquid Looker renders as their
+        argument, and their definition. A query flag is one too, e.g. `region_in_query` for
+        `accounts.region._in_query`, and NULL when false."""
+        lookml = json.dumps(self.views[view])
+        # The explore reads them, so by their view, e.g. `accounts.min_employees`.
+        parameters = {
+            name: (
+                f"{{% parameter {view}.{name} %}}",
+                _parameter(self.definition(view, name)[1]),
+            )
+            for name in _PARAMETER.findall(lookml)
+        }
+        for match in _QUERY_FLAG.finditer(lookml):
+            parameters[_flag(match)] = (
+                f"{{% if {match[0]} %}}TRUE{{% else %}}NULL{{% endif %}}",
+                {"datatype": "BOOL"},
+            )
+        return parameters
+
+    def resolve_user_attributes(self, sql: str) -> str:
+        return _USER_ATTRIBUTE.sub(lambda match: self.user_attributes[match[1]], sql)
+
+    def calculations(self, view: str) -> dict[str, exp.Expr]:
+        calculations = {}
+        for kind, definition in self.fields(view):
+            match self.result(view, definition["name"]):
+                case exp.Expr() as result:
+                    calculation = self.calculation(view, kind, definition["name"])
+                    if not _is_column(result, calculation):
+                        calculations[calculation] = result
+        return calculations
+
+    def dataset(self, view: str) -> dict[str, Any]:
+        calculations = self.calculations(view)
+        definition = self.views[view]
+        source: dict[str, Any]
+        parameters = {name: parameter for name, (_, parameter) in self.parameters(view).items()}
+        if "derived_table" in definition:
+            sql = self.resolve_user_attributes(definition["derived_table"]["sql"])
+            sql = _QUERY_FLAG.sub(_flag, _PARAMETER.sub(r"{{ \1 }}", sql))
+            source = {"type": "sql", "sql": sql}
+        else:
+            source = {"location": self.resolve_user_attributes(definition["sql_table_name"])}
+        source["columns"] = [{"name": column} for column in self.columns[view]]
+        return {
+            "source": source,
+            "parameters": _named(parameters),
+            "calculations": [
+                {"name": name, "expr": expr.sql(_DIALECT)} for name, expr in calculations.items()
+            ],
+        }
+
+    def join(self, join: dict[str, Any]) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+        """
+        `sql_on: ${revenue.account_id} = ${accounts.account_id}` is the entity
+
+            key: [{name: revenue__account_id}]
+            sources: [{dataset: accounts, on: ":revenue__account_id = account_id"}]
+
+        and the relationship key `[{name: revenue__account_id, expr: account_id}]` on `revenue`.
+        """
+        view = join["name"]
+        key: dict[str, exp.Expr] = {}
+
+        def bind(_: str, target: str, name: str) -> exp.Expr:
+            if target == view:
+                return self.inline(view, view, name)
+            # Named apart from `accounts.account_id`, which reads the joined row, NULL when the
+            # join doesn't match.
+            key_name = f"{target}__{name}"
+            key[key_name] = self.inline(target, target, name)
+            return exp.var(f":{key_name}")
+
+        on = self.translate(view, join["sql_on"], bind)
+        entity = {
+            "key": [{"name": name} for name in key],
+            "sources": [{"dataset": view, "on": on.sql(_DIALECT)}],
+        }
+        return entity, [{"name": name, "expr": expr.sql(_DIALECT)} for name, expr in key.items()]
+
+    def joins_by_view(self) -> dict[str, tuple[dict[str, Any], list[dict[str, Any]]]]:
+        """Each joined view's `join`; one that can't convert fails the explore."""
+        joins = {}
+        for join in self.joins():
+            try:
+                joins[join["name"]] = self.join(join)
+            except _Skip as skip:
+                raise ValueError(f"{self.explore['name']}'s join {join['name']}: {skip}") from None
+        return joins
+
+    def entity(self, view: str, entity: dict[str, Any]) -> dict[str, Any]:
+        """`join`'s entity, with the view's fields and the relationships from it as attributes,
+        e.g. `region: accounts.region` and `account_facts: accounts.account_facts`."""
+        children = [child for child, path in self.paths.items() if path[:-1] == self.paths[view]]
+        attributes = [
+            *self.columns[view],
+            *self.calculations(view),
+            *self.relationship_path(children),
+        ]
+        return {
+            **entity,
+            "attributes": [
+                {"name": name, "expr": exp.column(name, view).sql(_DIALECT)} for name in attributes
+            ],
+        }
+
+    def constellation(self) -> dict[str, Any]:
+        """
+        The explore, e.g. for `revenue` joining `accounts` and, through it, `account_facts`:
+
+            roles: [accounts: REF(accounts_entity), account_facts: ..., pricing_type, ...]
+            metrics: [
+              revenue__annual_revenue: AGG(revenue.annual_revenue),
+              accounts__account_count: AGG(revenue.accounts.account_count),
+              ...
+            ]
+            assignments: revenue -> [accounts: accounts, account_facts: accounts.account_facts, ...]
+        """
+        roles: dict[str, dict[str, Any]] = {}
+        assignments: dict[str, exp.Expr] = {}
+        metrics = {}
+        for view, path in self.paths.items():
+            if path:
+                target = read_table(self.entity_name(view), _DIALECT, strategy_of(_DIALECT))
+                roles[view] = {"datatype": ref_type(target).sql(_DIALECT)}
+                assignments[view] = _path(self.relationship_path(path))
+            for kind, definition in self.fields(view):
+                if kind == "measures" and not isinstance(
+                    self.result(view, definition["name"]), _Skip
+                ):
+                    calculation = self.calculation(view, kind, definition["name"])
+                    reference = _path([self.base, *self.relationship_path(path), calculation])
+                    metrics[_metric_name(view, calculation)] = {
+                        "expr": exp.func("AGG", reference).sql(_DIALECT)
+                    }
+        for kind, definition in self.fields(self.base):
+            if kind in ("parameters", "filters", "measures") or isinstance(
+                self.result(self.base, definition["name"]), _Skip
+            ):
+                continue
+            name = self.calculation(self.base, kind, definition["name"])
+            if name in self.paths:
+                raise ValueError(
+                    f"{self.explore['name']}' field {self.base}.{definition['name']} is named "
+                    "like a view it joins"
+                )
+            roles[name] = {}
+            assignments[name] = exp.column(name)
+        # A filter's SQL can read the view's columns, e.g. `${TABLE}.managers`.
+        for column in self.columns[self.base]:
+            roles.setdefault(column, {})
+            assignments.setdefault(column, exp.column(column))
+        return {
+            "roles": _named(roles),
+            "metrics": _named(metrics),
+            "assignments": [
+                {
+                    "dataset": self.base,
+                    "roles": [
+                        {"name": role, "expr": expr.sql(_DIALECT)}
+                        for role, expr in assignments.items()
+                    ],
+                }
+            ],
+        }
+
+    def base_entity(self) -> dict[str, Any] | None:
+        """The base view's rows, by primary key, so a joined view's measures can count theirs."""
+        try:
+            return self.primary_key_entity()
+        except _Skip as skip:
+            raise ValueError(f"{self.explore['name']}'s primary key: {skip}") from None
+
+    def primary_key_entity(self) -> dict[str, Any] | None:
+        for _, definition in self.fields(self.base):
+            if definition.get("primary_key") == "yes":
+                key = definition["name"]
+                on = self.inline(self.base, self.base, key).eq(exp.var(f":{key}"))
+                return {
+                    "key": [{"name": key}],
+                    "sources": [{"dataset": self.base, "on": on.sql(_DIALECT)}],
+                }
+        return None
+
+    def skipped(self) -> dict[str, list[str]]:
+        skipped: dict[str, list[str]] = {}
+        for view in self.paths:
+            for _, definition in self.fields(view):
+                result = self.result(view, definition["name"])
+                if isinstance(result, _Skip):
+                    skipped.setdefault(str(result), []).append(f"{view}.{definition['name']}")
+        return skipped
+
+    def prune(self, view: str, entries: list[str]) -> list[str]:
+        """Drops references to skipped fields from a list of field references."""
+
+        def is_skipped(entry: str) -> bool:
+            target, _, name = entry.lstrip("-").rpartition(".")
+            return isinstance(self.results.get((target or view, name)), _Skip)
+
+        return [entry for entry in entries if not is_skipped(entry)]
+
+    def prune_lists(self, view: str, node: dict[str, Any]) -> dict[str, Any]:
+        return {
+            key: self.prune(view, value) if key in _FIELD_LISTS else value
+            for key, value in node.items()
+        }
+
+    def sql_table_name(self, catalog: str) -> str:
+        """`metrics.public.revenue_explore(since => {% parameter revenue.since %})`"""
+        arguments = [
+            exp.Kwarg(this=exp.to_identifier(name), expression=exp.var(argument))
+            for view in self.paths
+            for name, (argument, _) in self.parameters(view).items()
+        ]
+        constellation = exp.to_identifier(_constellation_name(self.explore["name"]))
+        table = exp.Table(
+            this=(
+                exp.Anonymous(this=constellation, expressions=arguments)
+                if arguments
+                else constellation
+            ),
+            db=exp.to_identifier(DEFAULT_NAMESPACE),
+            catalog=exp.to_identifier(catalog),
+        )
+        # Named, and quoted, as a table is, rather than as a function, e.g. `REVENUE(...)`.
+        return table.sql(_LOOKML_DIALECT, normalize_functions=False)
+
+    def lookml_view(self, view: str) -> dict[str, Any]:
+        converted: dict[str, Any] = {"name": view}
+        for kind, definition in self.fields(view):
+            name = definition["name"]
+            if isinstance(self.result(view, name), _Skip):
+                continue
+            definition = self.prune_lists(view, definition)
+            path = _path([view, self.calculation(view, kind, name)])
+            match kind:
+                case "dimensions" | "dimension_groups":
+                    definition.pop("case", None)
+                    definition["sql"] = path.sql(_LOOKML_DIALECT)
+                case "measures":
+                    filters = self.filters(view, definition)
+                    metric = exp.column(_metric_name(view, self.calculation(view, kind, name)))
+                    definition = {
+                        **_without(definition, "filters__all"),
+                        "type": "number",
+                        "sql": exp.func("AGG", metric).sql(_LOOKML_DIALECT),
+                    }
+                    # The drill link only exists with drill fields, and a measure's own `html`
+                    # is kept.
+                    if filters and definition.get("drill_fields") and "html" not in definition:
+                        definition["html"] = _drill_html(filters)
+                case "filters":
+                    definition["sql"] = self.result(view, name)
+            converted.setdefault(kind, []).append(definition)
+        sets = [self.prune_lists(view, s) for s in self.views[view].get("sets", [])]
+        if sets:
+            converted["sets"] = sets
+        return converted
+
+    def lookml_explore(self, catalog: str) -> dict[str, Any]:
+        explore = {
+            **self.prune_lists(self.base, self.explore),
+            "sql_table_name": self.sql_table_name(catalog),
+        }
+        explore["joins"] = [
+            {**self.prune_lists(join["name"], _without(join, "sql_on")), "sql": ""}
+            for join in self.joins()
+        ]
+        return explore
+
+    def skipped_joins(self) -> dict[str, list[str]]:
+        skipped: dict[str, list[str]] = {}
+        for join in self.explore.get("joins", []):
+            if _relationship(join) not in _RELATIONSHIPS:
+                skipped.setdefault(f"{_relationship(join)} join", []).append(join["name"])
+        return skipped
+
+
+def _entity_name(view: str) -> str:
+    """It can't share the view's dataset's name."""
+    return f"{view}_entity"
+
+
+def _metric_name(view: str, calculation: str) -> str:
+    return f"{view}__{calculation}"
+
+
+def _constellation_name(explore: str) -> str:
+    """It can't share its base view's dataset's name."""
+    return f"{explore}_explore"
+
+
+def _distinct_names[K](
+    definitions: dict[str, dict[K, Any]], default: Callable[[K], str]
+) -> dict[str, dict[K, str]]:
+    """
+    Names what each explore defines, e.g. the entity of each view it joins, `default(key)`, or,
+    when an earlier explore defines it differently, after the first explore defining it so:
+
+        {revenue: {region_history: A}, current_regions: {region_history: B}}
+        -> {revenue: {region_history: region_history_entity},
+            current_regions: {region_history: current_regions__region_history_entity}}
+    """
+    firsts: dict[K, dict[str, str | None]] = {}
+    names: dict[str, dict[K, str]] = {explore: {} for explore in definitions}
+    for explore, by_key in definitions.items():
+        for key, definition in by_key.items():
+            seen = firsts.setdefault(key, {})
+            first = seen.setdefault(json.dumps(definition), explore if seen else None)
+            names[explore][key] = default(key) if first is None else f"{first}__{default(key)}"
+    return names
+
+
+def _merge_member(collection: dict[str, Any], name: str, member: dict[str, Any]) -> None:
+    collection[name] = _merged(collection[name], member, name) if name in collection else member
+
+
+def _merged(old: dict[str, Any], new: dict[str, Any], name: str) -> dict[str, Any]:
+    merged = {**old, **new}
+    for key in merged:
+        if key in _UNITED:
+            members = {member["name"]: member for member in old.get(key, [])}
+            for member in new.get(key, []):
+                if members.setdefault(member["name"], member) != member:
+                    raise ValueError(
+                        f"Explores convert `{name}.{key}.{member['name']}` differently"
+                    )
+            merged[key] = list(members.values())
+        elif old.get(key) != new.get(key):
+            raise ValueError(f"Explores convert `{name}.{key}` differently")
+    return merged
+
+
+def _relationship(join: dict[str, Any]) -> str:
+    return str(join.get("relationship", _DEFAULT_RELATIONSHIP))
+
+
+def _flag(match: re.Match[str]) -> str:
+    """A query flag's parameter, e.g. `region_in_query` for `accounts.region._in_query`."""
+    return f"{match[1]}_{match[2]}"
+
+
+def _named(collection: dict[str, dict[str, Any]]) -> list[dict[str, Any]]:
+    """A fragment's named collection, e.g. `[{name: orders, ...}]` for `{orders: {...}}`."""
+    return [{"name": name, **member} for name, member in collection.items()]
+
+
+def _without(node: dict[str, Any], key: str) -> dict[str, Any]:
+    return {k: v for k, v in node.items() if k != key}
+
+
+def _target(view: str, match: re.Match[str]) -> tuple[str, str]:
+    """A reference's view and field: `${accounts.region}`'s, or `${region}`'s on `view`."""
+    return (match[1], match[2]) if match[2] else (view, match[1])
+
+
+def _path(parts: list[str]) -> exp.Expr:
+    """A column through relationships, e.g. `revenue.accounts.region`, of any length."""
+    return exp.column(*reversed(parts[:4]), fields=parts[4:] or None)
+
+
+def _is_column(result: _Result, name: str) -> bool:
+    """Whether a field's calculation is just its dataset's column `name`."""
+    match result:
+        case exp.Column(table="") if result.name == name:
+            return True
+    return False
+
+
+def _condition(sql: exp.Expr, value: str, datatype: str) -> exp.Expr:
+    """A filter expression on a field of `datatype` as SQL, as Looker writes it for BigQuery:
+    `<>0` on a number is `x <> 0`, which drops NULLs, while `-Free_%` on a string keeps them.
+    What else Looker's syntax can say is skipped, e.g. a date's `3 months ago`."""
+    is_null = sql.is_(exp.null())
+    match value.lower():
+        case "null":
+            return is_null
+        case "not null" if datatype == "string":
+            raise _Skip("filter on a string")
+        case "-null" | "not null":
+            return exp.not_(is_null)
+    if datatype == "yesno" and value.lower() in ("yes", "no"):
+        return sql if value.lower() == "yes" else exp.not_(exp.func("COALESCE", sql, exp.false()))
+    if datatype == "number" and (match := _NUMBER_FILTER.fullmatch(value)):
+        return _COMPARISONS[match[1] or "="](sql, exp.Literal.number(match[2]))
+    if datatype == "string" and not _STRING_SYNTAX.search(value):
+        negated = value.startswith("-")
+        pattern = exp.Literal.string(value[1:] if negated else value)
+        # Case insensitive, as the model sets `case_sensitive: no`.
+        like = exp.func("LOWER", sql).like(exp.func("LOWER", pattern))
+        return exp.or_(exp.not_(like), is_null) if negated else like
+    raise _Skip(f"filter on a {datatype}")
+
+
+def _drill_html(filters: list[tuple[str, str]]) -> str:
+    """A converted measure's value, linked to its drill with its `filters` added, since Looker
+    adds an aggregate measure's filters to its drill, and the converted are numbers. The link
+    keeps one `f[...]` per field, so a field the query filters too takes the measure's filter as
+    an expression, as Looker's drill does, e.g. `matches_filter(${revenue.tier}, `-Free_%`)`.
+    Looker's Liquid can't `capture` the expression's parts to join them, so it starts with
+    `yes`."""
+    fields = "".join(
+        f"{{% unless {name}._is_filtered %}}&f[{name}]={quote(value, safe='')}{{% endunless %}}"
+        for name, value in filters
+    )
+    expressions = "".join(
+        f"{{% if {name}._is_filtered %}}"
+        f"{quote(f' AND matches_filter(${{{name}}}, `{value}`)', safe='')}"
+        "{% endif %}"
+        for name, value in filters
+    )
+    any_filtered = " or ".join(f"{name}._is_filtered" for name, _ in filters)
+    return (
+        f'<a href="{{{{ link }}}}{fields}'
+        f"{{% if {any_filtered} %}}&filter_expression=yes{expressions}{{% endif %}}"
+        '">{{ rendered_value }}</a>'
+    )
+
+
+def _parameter(definition: dict[str, Any]) -> dict[str, Any]:
+    parameter: dict[str, Any] = {"datatype": _PARAMETER_TYPES[definition["type"]]}
+    if "default_value" in definition:
+        value = definition["default_value"]
+        literal = (
+            exp.Literal.number(value)
+            if definition["type"] == "number"
+            else exp.Literal.string(value)
+        )
+        parameter["default"] = literal.sql(_DIALECT)
+    return parameter
+
+
+def _included(model: Path, patterns: list[str], include: tuple[Path, ...]) -> Iterator[Path]:
+    """The view files `patterns` match, as Looker reads them: `*.view` is `*.view.lkml`, and
+    `/x/*` and `//project/x/*` start at the model's and another project's directory."""
+    for pattern in patterns:
+        directories: tuple[Path, ...] = (model.parent,)
+        if pattern.startswith("//"):
+            directories, pattern = include, pattern[2:].partition("/")[2]
+        if not pattern.endswith(("*", ".lkml")):
+            pattern += ".lkml"
+        for directory in directories:
+            yield from (
+                p for p in directory.glob(pattern.lstrip("/")) if p.name.endswith(".view.lkml")
+            )
+
+
+def convert(
+    model: Path,
+    explores: list[str],
+    *,
+    user_attributes: dict[str, str],
+    connection: str,
+    include: tuple[Path, ...] = (),
+    model_name: str | None = None,
+    group_label: str | None = None,
+    dashboards: tuple[Path, ...] = (),
+    catalog: str = "metrics",
+    timezone: str | None = None,
+) -> Conversion:
+    """Converts `explores` of `model`, or all of them, reading the views it includes: from the
+    model's directory, and another project's, e.g. `//fivetran/*.view.lkml`, from `include`'s.
+    `group_label` replaces the explores', e.g. to list them apart from the model's."""
+    parsed = lkml.load(model.read_text())
+    views = {
+        view["name"]: view
+        for path in _included(model, parsed.get("includes", []), include)
+        for view in lkml.load(path.read_text()).get("views", [])
+    }
+    for view in views.values():
+        for dimension in view.get("dimensions", []):
+            # Looker reads a dimension without SQL as its view's column of its name.
+            if "sql" not in dimension and "case" not in dimension:
+                dimension["sql"] = f"${{TABLE}}.{dimension['name']}"
+    selected = [
+        definition
+        for definition in parsed["explores"]
+        if not explores or definition["name"] in explores
+    ]
+    # What each explore's joins are, to name what explores join differently.
+    drafts = {
+        definition["name"]: _Converter(views, definition, user_attributes, timezone=timezone)
+        for definition in selected
+    }
+    joins = {explore: draft.joins_by_view() for explore, draft in drafts.items()}
+    base_entities = {explore: draft.base_entity() for explore, draft in drafts.items()}
+    entity_names = _distinct_names(
+        {
+            explore: {
+                **(
+                    {drafts[explore].base: base_entities[explore]} if base_entities[explore] else {}
+                ),
+                **{view: entity for view, (entity, _) in by_view.items()},
+            }
+            for explore, by_view in joins.items()
+        },
+        _entity_name,
+    )
+    # Relationships to the same view from different datasets don't collide.
+    relationship_names = _distinct_names(
+        {
+            explore: {
+                (drafts[explore].parents[view], view): {
+                    "target": entity_names[explore][view],
+                    "key": key,
+                }
+                for view, (_, key) in by_view.items()
+            }
+            for explore, by_view in joins.items()
+        },
+        operator.itemgetter(1),
+    )
+    datasets: dict[str, Any] = {}
+    entities: dict[str, Any] = {}
+    constellations: dict[str, Any] = {}
+    skipped: dict[str, list[str]] = {}
+    lookml_explores = []
+    lookml_views: dict[str, Any] = {}
+    for definition in selected:
+        explore = definition["name"]
+        converter = _Converter(
+            views,
+            definition,
+            user_attributes,
+            relationships={view: name for (_, view), name in relationship_names[explore].items()},
+            entities=entity_names[explore],
+            timezone=timezone,
+        )
+        # Converting every field first, so field lists can drop the skipped ones.
+        # Explores share views, so a view's skips would otherwise repeat.
+        for reason, names in {**converter.skipped(), **converter.skipped_joins()}.items():
+            skipped[reason] = list(dict.fromkeys([*skipped.get(reason, []), *names]))
+
+        if base_entity := base_entities[explore]:
+            _merge_member(entities, converter.entity_name(converter.base), base_entity)
+        explore_datasets = {view: converter.dataset(view) for view in converter.paths}
+        for view, (entity, key) in joins[explore].items():
+            name = converter.entity_name(view)
+            _merge_member(entities, name, converter.entity(view, entity))
+            explore_datasets[converter.parents[view]].setdefault("relationships", []).append(
+                {"name": converter.relationship_name(view), "target": name, "key": key}
+            )
+        for view, dataset in explore_datasets.items():
+            _merge_member(datasets, view, dataset)
+        constellations[_constellation_name(explore)] = converter.constellation()
+
+        lookml_explore = converter.lookml_explore(catalog)
+        if group_label is not None:
+            lookml_explore["group_label"] = group_label
+        lookml_explores.append(lookml_explore)
+        for view in converter.paths:
+            _merge_member(lookml_views, view, converter.lookml_view(view))
+    lookml_files = {
+        f"{view}.view.lkml": lkml.dump({"views": [lookml_view]}) or ""
+        for view, lookml_view in lookml_views.items()
+    }
+    model_name = model_name or model.name.removesuffix(".model.lkml")
+    fragment = {
+        "schema_version": "v1",
+        "bundle": model_name,
+        "dialect": _DIALECT,
+        "generation_meta": {"generator_name": __name__},
+        "datasets": _named(datasets),
+        "entities": _named(entities),
+        "constellations": _named(constellations),
+    }
+    lookml_model = {
+        "connection": connection,
+        **{
+            k: v
+            for k, v in parsed.items()
+            if k in ("case_sensitive", "fiscal_month_offset", "week_start_day")
+        },
+        # Only what the conversion writes, so the model can share a project with others.
+        "includes": [*lookml_files, *(dashboard.name for dashboard in dashboards)],
+        "explores": lookml_explores,
+    }
+    lookml_files[f"{model_name}.model.lkml"] = lkml.dump(lookml_model) or ""
+    # A dashboard's queries on the converted explores read the converted model.
+    converted = {explore["name"] for explore in lookml_explores}
+    for dashboard in dashboards:
+        lookml_files[dashboard.name] = _DASHBOARD_QUERY.sub(
+            lambda match: (
+                f"{match[1]}{model_name}{match[2]}" if match[3] in converted else match[0]
+            ),
+            dashboard.read_text(),
+        )
+    return Conversion(fragment=fragment, lookml=lookml_files, skipped=skipped)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("model", type=Path)
+    parser.add_argument("explores", nargs="*", help="Explores to convert; all when none.")
+    parser.add_argument("--include", type=Path, action="append", default=[])
+    parser.add_argument("--model-name", help="The converted model's name; the model's by default.")
+    parser.add_argument("--group-label", help="The converted explores' group label.")
+    parser.add_argument("--dashboard", type=Path, action="append", default=[])
+    parser.add_argument("--connection", required=True)
+    parser.add_argument("--catalog", default="metrics", help="The catalog the server serves.")
+    parser.add_argument("--user-attribute", action="append", default=[], metavar="NAME=VALUE")
+    parser.add_argument(
+        "--timezone",
+        help="Looker's query timezone, e.g. America/Los_Angeles; none converts nothing.",
+    )
+    parser.add_argument("--out", type=Path, required=True)
+    args = parser.parse_args()
+
+    conversion = convert(
+        args.model,
+        args.explores,
+        include=tuple(args.include),
+        model_name=args.model_name,
+        group_label=args.group_label,
+        dashboards=tuple(args.dashboard),
+        user_attributes=dict(a.split("=", 1) for a in args.user_attribute),
+        connection=args.connection,
+        catalog=args.catalog,
+        timezone=args.timezone,
+    )
+    args.out.mkdir(parents=True, exist_ok=True)
+    (args.out / "fragment.json").write_text(json.dumps(conversion.fragment, indent=2))
+    for name, text in conversion.lookml.items():
+        (args.out / name).write_text(text)
+    for reason, fields in sorted(conversion.skipped.items(), key=lambda item: -len(item[1])):
+        print(f"{len(fields):5}  {reason}")
+        for name in fields:
+            print(f"         {name}")
+
+
+if __name__ == "__main__":
+    main()