dataface 0.3.1.dev78__py3-none-any.whl → 0.3.2.dev22__py3-none-any.whl

d3_format/spec.py

@@ -49,6 +49,51 @@ class FormatSpec:
     trim: bool = False  # ~ flag
     type: str = ""  # "" means default (g-ish) behavior
 
+    def __str__(self) -> str:
+        """Serialize back to a d3-format spec string, in grammar order.
+
+        Omits every default-valued token, so a parsed spec serializes back to
+        something an author would write rather than a fully-explicit
+        expansion. ``zero`` implies ``fill == "0"`` and ``align == "="`` (the
+        collapse in ``parse``), so the zero-pad flag is emitted alone rather
+        than alongside a redundant ``0=`` fill and align.
+
+        Raises:
+            ValueError: If ``zero`` is set but ``fill``/``align`` have been
+                mutated away from ``"0"``/``"="``. The d3 grammar cannot
+                express that combination -- ``parse`` collapses ``zero`` back
+                to ``fill="0"``, ``align="="`` unconditionally -- so silently
+                keeping the flag and dropping the fill would misrepresent the
+                spec. Clear ``zero`` first if an explicit fill/align is wanted.
+        """
+        if self.zero and (self.fill != "0" or self.align != "="):
+            raise ValueError(
+                "FormatSpec has zero=True with fill="
+                f"{self.fill!r}, align={self.align!r}; the d3 grammar can "
+                "only express zero-pad as fill='0', align='='. Clear zero "
+                "if you want this fill/align combination."
+            )
+        tokens: list[str] = []
+        if not self.zero and (self.fill != " " or self.align != ">"):
+            tokens.append(self.fill)
+            tokens.append(self.align)
+        if self.sign != "-":
+            tokens.append(self.sign)
+        if self.symbol:
+            tokens.append(self.symbol)
+        if self.zero:
+            tokens.append("0")
+        if self.width is not None:
+            tokens.append(str(self.width))
+        if self.comma:
+            tokens.append(",")
+        if self.precision is not None:
+            tokens.append(f".{self.precision}")
+        if self.trim:
+            tokens.append("~")
+        tokens.append(self.type)
+        return "".join(tokens)
+
 
 def parse(spec: str) -> FormatSpec:
     """Parse a d3-format spec string into a FormatSpec.

dataface/DATAFACE_SYNTAX.md

@@ -394,7 +394,7 @@ queries:
 
   # Inline values (no database)
   sample:
-    type: values                 # Optional — also implied by `values:` presence
+    type: values                 # Optional — implied by `rows:`, `columns:`, or `values:`
     columns: [name, score]
     values:
       - [Alice, 92.4]

dataface/agent_api/__init__.py

@@ -37,6 +37,9 @@ CLI/MCP files that contain logic beyond parse-and-dispatch.
 """
 
 from dataface.agent_api import skills as skills
+from dataface.agent_api._paths import (
+    project_sources_for_face as project_sources_for_face,
+)
 from dataface.agent_api.describe import (
     DescribeFaceArgs,
     DescribeFaceResult,
@@ -47,6 +50,11 @@ from dataface.agent_api.init import (
     InitResult as InitResult,
     init_project as init_project,
 )
+from dataface.agent_api.migrate import (
+    MigrateError as MigrateError,
+    MigrateSummary as MigrateSummary,
+    migrate_paths as migrate_paths,
+)
 from dataface.agent_api.project_session import ProjectSession as ProjectSession
 from dataface.agent_api.query import QueryFaceResult, query_face
 from dataface.agent_api.schema_hints import (
@@ -61,6 +69,7 @@ from dataface.agent_api.validate_query import (
     QueryDiagnostic as QueryDiagnostic,
     validate_query as validate_query,
 )
+from dataface.core.attribution import set_surface as set_surface
 from dataface.core.compile.compiler import (
     CompileResult as CompileResult,
     compile as compile,
@@ -68,6 +77,7 @@ from dataface.core.compile.compiler import (
 from dataface.core.compile.config import ProjectSourcesConfig as ProjectSourcesConfig
 from dataface.core.dashboard import (
     RenderedDashboard as RenderedDashboard,
+    RenderFormat as RenderFormat,
     render_dashboard as render_dashboard,
 )
 from dataface.core.diagnostics import Diagnostic as Diagnostic
@@ -84,7 +94,7 @@ from dataface.core.execute.source_resolver import (
     DefaultSourceResolver as DefaultSourceResolver,
     SourceResolver as SourceResolver,
 )
-from dataface.core.fonts import get_inter_font_path as get_inter_font_path
+from dataface.core.fonts import get_fonts_dir as get_fonts_dir
 from dataface.core.project import (
     FaceFile as FaceFile,
     InMemoryFace as InMemoryFace,
@@ -106,13 +116,17 @@ __all__ = [
     "InMemoryFace",
     "InitResult",
     "LinkContext",
+    "MigrateError",
+    "MigrateSummary",
     "Project",
     "ProjectSession",
+    "set_surface",
     "ProjectSourcesConfig",
     "QueryDiagnostic",
     "QueryFaceResult",
     "RenderedDashboard",
     "RenderError",
+    "RenderFormat",
     "SchemaHints",
     "Topic",
     "ValidateDashboardArgs",
@@ -124,8 +138,9 @@ __all__ = [
     "SourceResolver",
     "WarehouseObserver",
     "describe_face",
-    "get_inter_font_path",
+    "get_fonts_dir",
     "init_project",
+    "migrate_paths",
     "query_face",
     "render_dashboard",
     "schema_hints",

dataface/agent_api/_paths.py

@@ -6,8 +6,9 @@ import os
 from dataclasses import dataclass
 from pathlib import Path, PurePosixPath
 
-# tach-ignore(agent_api->cli: runtime host-type guard in no_project_hint; the local-filesystem check needs a non-cli signal on Project — deferred)
+# tach-ignore(agent_api->cli: runtime host-type guard in resolve_face_or_error / _relpath_for_fs_location; the local-filesystem check needs a non-cli signal on Project — deferred)
 from dataface.cli.filesystem_project import FilesystemProject
+from dataface.core.compile.config import ProjectSourcesConfig
 from dataface.core.diagnostics import (
     ERR_FILE_NOT_FOUND,
     ERR_INTERNAL,
@@ -27,54 +28,6 @@ from dataface.core.project_roots import (
 )
 
 
-def resolve_project_dir(project_dir: Path | None) -> Path:
-    """Resolve the caller's `project_dir`, walking up from cwd when omitted.
-
-    Boundary helper: every agent_api / CLI callsite that today forwards a
-    possibly-None `project_dir` into a core helper routes through this so the
-    cwd read stays at the agent_api boundary, not inside `dataface/core`.
-    """
-    if project_dir is not None:
-        return project_dir.resolve()
-    cwd = Path.cwd().resolve()
-    return find_dft_root(cwd) or cwd
-
-
-def resolve_project_dir_from_paths(
-    paths: list[Path] | None, project_dir: Path | None
-) -> Path:
-    """Resolve project_dir for a multi-path CLI verb (validate / describe).
-
-    Explicit `--project-dir` wins. Otherwise, when all supplied paths are
-    absolute, walk up from the first path's parent to anchor on the project
-    that contains the file. Otherwise fall back to a cwd walk.
-    """
-    if project_dir is not None:
-        return project_dir.resolve()
-    if paths and all(p.is_absolute() for p in paths):
-        anchor = paths[0].parent.resolve()
-        return find_dft_root(anchor) or anchor
-    return resolve_project_dir(None)
-
-
-def no_project_hint(project: Project) -> str:
-    """Return a hint string when no project marker is found, else empty string.
-
-    Only walks the local filesystem for a `FilesystemProject` — a non-filesystem
-    host's `project.root` is not a real on-disk project directory (it's the
-    server cwd), so there is no marker to walk up to and nothing to hint about.
-    """
-    if not isinstance(project, FilesystemProject):
-        return ""
-    project_root = project.root
-    if find_dft_root(project_root) is not None:
-        return ""
-    return (
-        f" No Dataface project marker found at or above {project_root}."
-        f" Run from inside a Dataface project, or set project_dir."
-    )
-
-
 def resolve_face_relpath(relpath: PurePosixPath, project: Project) -> ProjectPath:
     """Project-relative face identity -> ProjectPath, with the faces-first retry.
 
@@ -179,7 +132,6 @@ def resolve_face_or_error(path: Path, project: Project) -> FaceFile | Diagnostic
         return DatafaceError.from_code(
             ERR_FILE_NOT_FOUND,
             path=resolved.relpath,
-            hint=no_project_hint(project),
         ).to_diagnostic(file=resolved.relpath)
     if (
         isinstance(project, FilesystemProject)
@@ -269,3 +221,26 @@ def build_yaml_render_context(
         project_root=project_root,
         output_dir=project_root,
     )
+
+
+def project_sources_for_face(face_path: Path) -> ProjectSourcesConfig:
+    """The `sources:` registry of the project owning ``face_path``.
+
+    Editor surfaces compile buffer text rather than a file on disk, so they
+    have no `Project` to hand `compile()` — but without the source registry
+    compile cannot tell a query's SQL dialect, and dialect is what makes a SQL
+    parse finding trustworthy enough to report.
+
+    A face outside any project needs no special case: `find_project_root`
+    falls back to the starting directory, which has no `dataface.yml`, and the
+    registry comes back empty — compile then stays silent about SQL syntax
+    rather than guessing a dialect.
+
+    A `dataface.yml` that exists but does not load raises, deliberately. That
+    is a real fault at a real location, and swallowing it here would decide on
+    the author's behalf that a broken project config is invisible — while
+    handing the caller an empty registry indistinguishable from "no project".
+    Callers attribute the failure; they do not get to pretend it did not
+    happen.
+    """
+    return FilesystemProject(find_project_root(face_path.parent, None)).sources

dataface/agent_api/board_artifact.py

@@ -22,6 +22,7 @@ from pydantic import BaseModel, ConfigDict
 
 from dataface.agent_api._paths import resolve_face_or_error
 from dataface.core.compile import compile_file
+from dataface.core.compile.variables import normalize_multiselect_values
 from dataface.core.diagnostics import ERR_FILE_NOT_FOUND, Diagnostic
 from dataface.core.diagnostics.base import DatafaceError
 from dataface.core.execute.executor import Executor
@@ -70,7 +71,7 @@ class RenderBoardArtifactResult(BaseModel):
 
 def _read_or_error(path: Path) -> bytes:
     if not path.exists():
-        raise DatafaceError.from_code(ERR_FILE_NOT_FOUND, path=str(path), hint="")
+        raise DatafaceError.from_code(ERR_FILE_NOT_FOUND, path=str(path))
     return path.read_bytes()
 
 
@@ -105,7 +106,16 @@ def emit_board_artifact(
     face = compile_result.face
     assert face is not None  # compile_result.success guarantees this
 
-    merged_variables: dict[str, Any] = {**face.variable_defaults, **(variables or {})}
+    # `emit-board` merges its own variables — it never goes through `render()`,
+    # whose prologue does this — and this dict is both rendered from and stored
+    # verbatim in the recording that `render_board_from_files` replays. `--var`
+    # values are always strings, so a scalar is the only shape a caller can
+    # supply for a multiselect here; unnarrowed, a bare `| join` would iterate
+    # it character by character.
+    merged_variables: dict[str, Any] = normalize_multiselect_values(
+        {**face.variable_defaults, **(variables or {})},
+        face.variable_registry or {},
+    )
 
     executor = Executor(
         face,

dataface/agent_api/describe.py

@@ -197,19 +197,15 @@ def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
             ],
         )
 
-    return _describe_resolved(resolved, project=project)
+    return _describe_resolved(resolved)
 
 
-def _describe_resolved(
-    resolved: ProjectPath, *, project: Project
-) -> DescribeFaceResult:
+def _describe_resolved(resolved: ProjectPath) -> DescribeFaceResult:
     """Describe an already-resolved face path — no re-resolution."""
-    from dataface.agent_api._paths import no_project_hint
     from dataface.core.compile.compiler import compile_file
     from dataface.core.diagnostics.base import DatafaceError
 
     if not resolved.exists():
-        hint = no_project_hint(project)
         return DescribeFaceResult(
             success=False,
             path=Path(resolved.relpath),
@@ -217,7 +213,6 @@ def _describe_resolved(
                 DatafaceError.from_code(
                     ERR_FILE_NOT_FOUND,
                     path=resolved.relpath,
-                    hint=hint,
                 ).to_diagnostic()
             ],
         )
@@ -349,7 +344,7 @@ def _describe_one_path(
         ]
 
     if resolved.is_yaml:
-        return [_describe_resolved(resolved, project=project)]
+        return [_describe_resolved(resolved)]
 
     faces = sorted(
         pf
@@ -371,4 +366,4 @@ def _describe_one_path(
                 ],
             )
         ]
-    return [_describe_resolved(pf, project=project) for pf in faces]
+    return [_describe_resolved(pf) for pf in faces]

dataface/agent_api/docs/yaml-reference.md

@@ -15,7 +15,7 @@ AuthoredFace (dataface) definition from YAML.
 | `source` | str | ✓ | Default source name for all queries in this face. Inheritable via meta.yaml cascade. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy for every query in this dashboard, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts the whole dashboard out. Inheritable via the meta.yaml cascade. |
 | `variables` | dict[str, [Variable](#variable) \| VariableRef] | ✓ | Variable definitions for dynamic filtering and UI controls. |
-| `queries` | dict[str, [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef] | ✓ | Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.). |
+| `queries` | dict[str, [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef] | ✓ | Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.). |
 | `charts` | dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| ChartRef] | ✓ | Named chart definitions. When no explicit layout is present, charts render as an implicit row layout in authored order. |
 | `rows` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Vertical stack layout: list of chart names or inline chart/face definitions. |
 | `cols` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Horizontal layout: list of chart names or inline chart/face definitions. |
@@ -55,7 +55,7 @@ Variable definition from YAML.
 | `visible` | bool | ✓ | When False, the variable is not rendered in the UI but can still be set via URL params. |
 | `enabled` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Enable this control. Accepts: static bool; a variable name or Jinja boolean expression string (no {{ }} required — bare names auto-wrap); or a {query, column} form that reads a single boolean cell from a named query. None = enabled. Absent variable in a string expression raises (use a default). |
 | `column` | str | ✓ | Column name in the query result to use as option values. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) | ✓ | Query name or inline query definition for populating options. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) | ✓ | Query name or inline query definition for populating options. |
 | `dimension` | str | ✓ | MetricFlow dimension name for populating options. |
 | `measure` | str | ✓ | MetricFlow measure name for populating options. |
 | `model` | str | ✓ | dbt model name for populating options. |
@@ -104,12 +104,12 @@ REST API query.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
+| `url` | str |  | HTTP endpoint URL for REST API queries. |
 | `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
 | `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
 | `type` | enum: "http" | ✓ | Query adapter type. |
-| `url` | str | ✓ | HTTP endpoint URL for REST API queries. |
 | `method` | enum: "GET", "POST", "PUT", "DELETE", "PATCH" | ✓ | HTTP method (GET, POST, PUT, DELETE, PATCH). |
 | `headers` | dict[str, str] | ✓ | HTTP request headers. |
 | `params` | dict[str, Any] | ✓ | HTTP query string parameters. |
@@ -119,18 +119,30 @@ REST API query.
 
 <a id="valuesquery"></a>
 ## ValuesQuery
-Inline rows embedded in YAML.
+Inline data authored as a list of row mappings.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
+| `rows` | list[dict[str, Any]] |  | Inline data rows (list of row dicts). Use the compact columns-and-values form instead when row values are positional. |
+| `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
+| `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
+| `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
+| `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `type` | enum: "values" | ✓ | Query adapter type. |
+
+<a id="compactvaluesquery"></a>
+## CompactValuesQuery
+Inline data authored as column names plus positional row values.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `columns` | list[str] |  | Column names for the compact syntax. Every compact values query also requires values. |
+| `values` | list[list[Any]] |  | Inline row-oriented data (list of lists) for the compact syntax. Every compact values query also requires columns. |
 | `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
 | `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
 | `type` | enum: "values" | ✓ | Query adapter type. |
-| `rows` | list[dict[str, Any]] | ✓ | Inline data rows (list of row dicts). |
-| `values` | list[list[Any]] | ✓ | Inline row-oriented data (list of lists) for the compact 'columns + values' syntax. |
-| `columns` | list[str] | ✓ | Column names for the compact 'columns + values' syntax. |
 
 <a id="schemaquery"></a>
 ## SchemaQuery
@@ -149,17 +161,40 @@ dbt source schema query.
 
 <a id="lookmlquery"></a>
 ## LookmlQuery
-LookML semantic query — compiled to SQL through likeml at compile time.
+LookML query rooted at one explore.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `explore` | str |  | LookML explore name. Presence of this key infers type: lookml. Use a merge query instead to combine multiple sources. |
+| `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
+| `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
+| `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
+| `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `type` | enum: "lookml" | ✓ | Query adapter type. |
+| `fields` | list[str] | ✓ | Qualified 'view.field' refs to select. Optional at authoring time: collected from chart channels when absent. |
+| `sorts` | list[str] | ✓ | Looker sort clauses, e.g. ['view.field', 'view.other desc']. Lowered to ORDER BY via likeml. |
+| `pivots` | list[str] | ✓ | Qualified 'view.field' refs to pivot on. |
+| `pivots_unwrapped` | bool | ✓ | Which of Looker's two pivot SQL shapes to emit: False/None = wrapped (5-layer DENSE_RANK), True = plain GROUP BY. |
+| `total` | bool | ✓ | Looker grand-totals flag. |
+| `subtotals` | list[str] | ✓ | Dimension refs to subtotal via GROUP BY ROLLUP. |
+| `filter_expression` | str | ✓ | Looker query-level free-form boolean filter over ${view.field} refs. |
+| `dynamic_fields` | list[dict[str, Any]] | ✓ | Looker dynamic fields: custom measures / custom dimensions synthesized into SQL. Table calculations compose as a derived wrapper query, not here. |
+| `limit` | int | ✓ | Maximum number of rows returned. |
+| `column_limit` | int | ✓ | Looker column_limit — caps wrapped-pivot columns. |
+| `filters` | dict[str, Any] | ✓ | RAW Looker filter expressions keyed by 'view.field' (e.g. "13 months", "gold") — translated to SQL predicates by likeml. |
+
+<a id="lookmlmergequery"></a>
+## LookmlMergeQuery
+LookML query that merges multiple sources.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
+| `merge` | list[dict[str, Any]] |  | LookML merge sources — a list of source specs. Each is either an explore spec ({explore, fields, filters?, merge_on?}) or a query reference ({query, columns, merge_on?}) for a derived source such as a table-calc wrapper. First is the primary; each secondary's `merge_on` maps its key to the primary's. Presence of this key infers type: lookml. Compiled to a FULL OUTER JOIN via likeml. |
 | `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
 | `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
 | `type` | enum: "lookml" | ✓ | Query adapter type. |
-| `explore` | str | ✓ | LookML explore name. Presence of this key infers type: lookml. |
-| `merge` | list[dict[str, Any]] | ✓ | LookML merge sources — a list of source specs. Each is either an explore spec ({explore, fields, filters?, merge_on?}) or a query reference ({query, columns, merge_on?}) for a derived source such as a table-calc wrapper. First is the primary; each secondary's `merge_on` maps its key to the primary's. Presence of this key infers type: lookml. Compiled to a FULL OUTER JOIN via likeml. |
 | `fields` | list[str] | ✓ | Qualified 'view.field' refs to select. Optional at authoring time: collected from chart channels when absent. |
 | `sorts` | list[str] | ✓ | Looker sort clauses, e.g. ['view.field', 'view.other desc']. Lowered to ORDER BY via likeml. |
 | `pivots` | list[str] | ✓ | Qualified 'view.field' refs to pivot on. |
@@ -182,7 +217,7 @@ Authored patch for bar and histogram charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -211,7 +246,7 @@ Authored patch for line charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -240,7 +275,7 @@ Authored patch for area charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -269,7 +304,7 @@ Authored patch for scatter charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -299,7 +334,7 @@ Authored patch for heatmap charts.
 | `type` | enum: "heatmap" |  | Heatmap chart type. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -328,7 +363,7 @@ Authored patch for pie and donut charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -351,7 +386,7 @@ Authored patch for KPI (key performance indicator) charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -371,7 +406,7 @@ Authored patch for table charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -392,7 +427,7 @@ Authored patch for point_map and bubble_map charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -409,7 +444,7 @@ Authored patch for point_map and bubble_map charts.
 | `latitude` | str | ✓ | Column containing latitude values for point/bubble maps. |
 | `longitude` | str | ✓ | Column containing longitude values for point/bubble maps. |
 | `size` | str | ✓ | Data column used to scale bubble radius (quantitative). Only meaningful on bubble_map. |
-| `basemap` | [BasemapConfig](#basemapconfig) | ✓ | Tile-layer configuration for the map background. |
+| `basemap` | [BasemapConfig](#basemapconfig) | ✓ | Styled geographic background layer. |
 | `style` | [PointMapChartStyle](#pointmapchartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="geoshapechart"></a>
@@ -422,7 +457,7 @@ Authored patch for map and geoshape charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -459,7 +494,7 @@ Authored patch for spark_bar charts (compact horizontal bars).
 | `type` | enum: "spark_bar" |  | SparkBar chart type. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -929,14 +964,11 @@ Authored overlay for TableChartStyle. Table chart style overrides layered on top
 
 <a id="basemapconfig"></a>
 ## BasemapConfig
-Tile-layer configuration for point_map and bubble_map charts.
+Styled geographic background layer for point_map and bubble_map charts.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `type` | str | ✓ | Tile provider type (e.g. 'mapbox', 'raster'). |
-| `style` | str | ✓ | Tile style URL (e.g. Mapbox style URI). |
 | `source` | str | ✓ | Named geographic boundary source (e.g. 'us-states') for overlay rendering. |
-| `attribution` | str | ✓ | Attribution text for the tile provider. |
 | `fill` | str | ✓ | Fill color for geographic boundary overlay. |
 | `stroke` | str | ✓ | Stroke color for geographic boundary overlay. |
 
@@ -2820,6 +2852,7 @@ Postgres source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `port` | int | ✓ | Database port number. |
 | `schema` | str | ✓ | Default schema for queries. |
 | `connect_timeout` | int | ✓ | Connection timeout in seconds. |
@@ -2846,6 +2879,7 @@ Snowflake source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `user` | str | ✓ | Snowflake user name. Omit for token-based authentication when supported. |
 | `password` | str | ✓ | Snowflake password. Omit when using OAuth or key-pair auth. |
 | `warehouse` | str | ✓ | Snowflake virtual warehouse name. |
@@ -2887,6 +2921,7 @@ BigQuery source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `keyfile` | str | ✓ | Path to service account JSON key file. |
 | `keyfile_json` | dict[str, str \| int \| float \| bool] | ✓ | Inline service account JSON dict. |
 | `location` | str | ✓ | Dataset location (e.g. US, EU). |
@@ -2929,6 +2964,7 @@ Redshift source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `port` | int | ✓ | Redshift port number. |
 | `schema` | str | ✓ | Default schema for queries. |
 | `user` | str | ✓ | Redshift user name. Omit for IAM-based authentication when supported. |
@@ -2977,6 +3013,7 @@ MySQL source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `port` | int | ✓ | MySQL port number. |
 | `schema` | str | ✓ | Default schema for queries. |
 
@@ -3073,6 +3110,7 @@ Reference to a dbt profile.
 | `type` | enum: "dbt_profile" |  | Source type identifier. |
 | `profile` | str |  | dbt profile name from profiles.yml. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `target` | str | ✓ | dbt target to use; defaults to the profile's default target. |
 | `profiles_dir` | str | ✓ | Directory containing profiles.yml, relative to the dataface project root. Use when profiles.yml is in a subdirectory (e.g. services/dbt). Resolution order: profiles_dir → $DBT_PROFILES_DIR → project root → ~/.dbt. |