dataface 0.2.1.dev599__py3-none-any.whl → 0.2.1.dev647__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -155,7 +155,7 @@ Reference variables inside queries with bare `{{ region }}` — no `variables.`
 charts:
   revenue_trend:
     query: revenue                 # Named query reference
-    type: line                     # See `dft docs charts` for all 29 chart types
+    type: line                     # See `dft docs charts` for all 16 authorable chart types
     x: month
     y: total
     color: segment
@@ -531,25 +531,25 @@ charts:
       # bar/area families also accept style.orientation and style.stack
 ```
 
-### Chart types (29 total)
+### Chart types (16 authorable)
 
 Set `type:` to one of:
 
-**Basic** (one mark per chart) — `bar`, `line`, `area`, `scatter`, `pie`, `donut`, `kpi`, `table`.
+**Basic** (one mark per chart) -- `bar`, `line`, `area`, `scatter`, `pie`, `donut`, `kpi`, `table`.
 
-**Statistical** — `boxplot`, `errorbar`, `errorband`, `histogram`, `heatmap`.
+**Statistical** -- `histogram`, `heatmap`.
 
-**Geographic** — `geoshape`, `map`, `point_map`, `bubble_map`.
+**Geographic** -- `geoshape`, `map`, `point_map`, `bubble_map`.
 
-**Marks** (direct Vega-Lite mark passthroughs) — `circle`, `square`, `tick`, `rule`, `trail`, `rect`, `arc`, `image`.
+**Overlays** -- `bar`, `line`, `area`, and `scatter` accept a `layers:` field for mixed-mark or dual-axis charts (see [Combo charts](#combo-charts-barlinearea-with-layers) and [Composition](#composition)).
 
-**Overlays** — `bar`, `line`, `area`, and `scatter` accept a `layers:` field for mixed-mark or dual-axis charts (see [Combo charts](#combo-charts-barlinearea-with-layers) and [Composition](#composition)).
+**Sparklines** -- `spark_bar` (compact horizontal bars used in profiler cards).
 
-**Sparklines** — `spark_bar` (compact horizontal bars used in profiler cards).
+**Auxiliary** -- `callout` (message card with a `style.tone:` field; `message:` required).
 
-**Auxiliary** — `callout` (message card with a `style.tone:` field; `message:` required), `auto` (auto-detect from data — internal-only; not surfaced in UI dropdowns).
+Note: `donut` is an internal alias for `pie` -- `donut` is accepted but normalizes to `pie` internally. `auto` is an internal sentinel (not authored). `boxplot`, `errorbar`, and `errorband` are Vega-Lite mark types that are not in the authorable surface.
 
-Aliases that map to underlying marks: `scatter` → `circle`, `heatmap` → `rect`, `pie` / `donut` → `arc`, `histogram` → `bar` with binning, `map` → `geoshape`.
+Type aliases: `scatter` uses a circle mark, `heatmap` uses rect, `pie`/`donut` use arc, `histogram` uses bar with binning, `map` maps to geoshape.
 
 ### Shared chart fields
 
@@ -709,11 +709,6 @@ color: event_count
 type: histogram
 x: amount
 
-# boxplot / errorbar / errorband — statistical primitives
-type: boxplot
-x: region
-y: latency
-
 # geoshape — choropleth via GeoJSON
 type: geoshape
 geo_source: us-states

dataface/agent_api/_paths.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -13,15 +14,17 @@ from dataface.core.diagnostics import (
     Diagnostic,
 )
 from dataface.core.diagnostics.base import DatafaceError
-from dataface.core.project import FaceFile, Project
+from dataface.core.project import (
+    FACES_SUBDIR,
+    FaceFile,
+    Project,
+    ProjectPath,
+    assert_relpath,
+)
 from dataface.core.project_roots import (
     find_dft_root as find_dft_root,
     find_project_root as find_project_root,
 )
-from dataface.core.scoped_paths import (
-    resolve_face_path as resolve_face_path,
-    resolve_scoped_path as resolve_scoped_path,
-)
 
 
 def resolve_project_dir(project_dir: Path | None) -> Path:
@@ -72,6 +75,42 @@ def no_project_hint(project: Project) -> str:
     )
 
 
+def resolve_face_path(path: Path, project: Project) -> ProjectPath:
+    """User/agent-supplied face path -> ProjectPath.
+
+    Absolute and ``..``-leading paths are explicit locations: they relativize
+    through the containment seam (``project.path_for_fspath``, a leading
+    ``..`` resolving against cwd for CLI shell-nav feel) and are returned
+    as-is — no ``faces/`` retry, even when the exact path doesn't exist. A
+    bare relative name (no explicit location) gets the faces-first retry: for
+    a relpath that doesn't exist in the project store and has no explicit
+    ``faces/`` prefix, retries under ``FACES_SUBDIR``. This lets a
+    ``search_dashboards`` ``face_path`` of ``'looker/x.yaml'`` (``faces/``
+    prefix stripped at search time) resolve to ``faces/looker/x.yaml``
+    without producing a ``faces/faces/...`` double prefix when the caller
+    already supplies the full ``faces/looker/x.yaml``.
+
+    Existence is checked via ``project.exists(...)`` so it works for all
+    ``Project`` implementations (FilesystemProject, CloudManagedProject
+    git-blob store, etc.) — not just the local filesystem. Paths that exist
+    at root resolve from root — non-faces paths like ``models/schema.sql``
+    are not rewritten under faces/.
+    """
+    if path.is_absolute():
+        return project.path_for_fspath(path)
+    if ".." in path.parts:
+        return project.path_for_fspath(Path(os.path.normpath(Path.cwd() / path)))
+    relpath = str(path)
+    assert_relpath(relpath)
+    if project.exists(relpath):
+        return project.path(relpath)
+    if not relpath.startswith(f"{FACES_SUBDIR}/"):
+        candidate = f"{FACES_SUBDIR}/{relpath}"
+        if project.exists(candidate):
+            return project.path(candidate)
+    return project.path(relpath)  # caller reports not-found
+
+
 def resolve_face_or_error(path: Path, project: Project) -> FaceFile | Diagnostic:
     """Faces-first resolve a path to a stored ``FaceFile``, or a structured error.
 
@@ -85,21 +124,23 @@ def resolve_face_or_error(path: Path, project: Project) -> FaceFile | Diagnostic
         resolved = resolve_face_path(path, project)
     except ValueError as exc:
         return DatafaceError.from_code(ERR_INTERNAL, message=str(exc)).to_diagnostic()
-    project_path = project.path_for_fspath(resolved)
-    if not project_path.exists():
+    if not resolved.exists():
         return DatafaceError.from_code(
             ERR_FILE_NOT_FOUND,
-            path=project_path.relpath,
+            path=resolved.relpath,
             hint=no_project_hint(project),
-        ).to_diagnostic(file=project_path.relpath)
-    if isinstance(project, FilesystemProject) and not resolved.is_file():
+        ).to_diagnostic(file=resolved.relpath)
+    if (
+        isinstance(project, FilesystemProject)
+        and not (project.root / resolved.relpath).is_file()
+    ):
         # A directory (or other non-file) resolves + exists on disk but read_face
         # would raise past the structured envelope. This is a filesystem-only
         # concern — a non-filesystem store's `exists()` already gates real faces.
         return DatafaceError.from_code(
-            ERR_INTERNAL, message=f"Not a file: {project_path.relpath}"
-        ).to_diagnostic(file=project_path.relpath)
-    return project_path.read_face()
+            ERR_INTERNAL, message=f"Not a file: {resolved.relpath}"
+        ).to_diagnostic(file=resolved.relpath)
+    return resolved.read_face()
 
 
 @dataclass(frozen=True)

dataface/agent_api/cache.py

@@ -1,8 +1,13 @@
 """Cache constructors at the agent_api boundary."""
 
+from __future__ import annotations
+
 from collections.abc import Generator
 from contextlib import contextmanager
 from pathlib import Path
+from typing import TYPE_CHECKING
+
+from dataface.core.compile.config import resolve_cache_boot
 
 # Re-exported: TrivialDuckDBCache is the declared return type of open_cache,
 # so embedders annotating a held cache reach it here without a core import.
@@ -10,29 +15,69 @@ from dataface.core.execute.trivial_local_cache import (
     TrivialDuckDBCache as TrivialDuckDBCache,
 )
 
-__all__ = ["TrivialDuckDBCache", "open_cache", "cache_ctx"]
+if TYPE_CHECKING:
+    from dataface.cli.filesystem_project import FilesystemProject
+
+__all__ = [
+    "TrivialDuckDBCache",
+    "open_cache",
+    "open_project_cache",
+    "project_cache_ctx",
+]
 
 
 def open_cache(path: Path | None) -> TrivialDuckDBCache:
-    """Open the query-result cache.
+    """Open the query-result cache at an already-resolved path.
 
     ``path=None`` opens an in-memory cache — ephemeral, discarded when closed.
     A path opens (or creates, if absent) a persistent DuckDB file, reused
     across invocations. Callers own the returned cache's lifecycle (close it).
+    Does not consult project config — use ``open_project_cache`` for that.
     """
     return TrivialDuckDBCache(db_path=path)
 
 
-@contextmanager
-def cache_ctx(path: Path | None) -> Generator[TrivialDuckDBCache]:
-    """Open a cache scoped to a single command invocation; closes it on exit.
+def open_project_cache(
+    project: FilesystemProject,
+    *,
+    no_cache: bool = False,
+    cache_path: Path | None = None,
+) -> TrivialDuckDBCache | None:
+    """Open the query-result cache honoring project config, with overrides.
+
+    The caller owns the project instance. Pair this with
+    ``ProjectSession.from_project(project, cache=...)`` rather than
+    ``ProjectSession.open(project_dir, cache=...)`` — ``open()`` builds its own
+    project from the path, so composing it with this function constructs two.
 
-    Use for CLI verbs and composition roots that need a cache scoped to
-    a single command invocation. Long-lived processes (server boot, MCP
-    server) call ``open_cache()`` directly and own the lifecycle.
+    Precedence: ``no_cache=True`` (the CLI's ``--no-cache``) skips the cache
+    entirely; ``cache_path`` (``--cache PATH``, or its ``DFT_CACHE_PATH`` env
+    backing) opens that persistent file. Otherwise the project's
+    ``dataface.yml`` ``cache:`` block picks the location — a configured ``path``
+    opens that file (created if absent); no path opens the zero-config
+    in-memory default. A project-level ``cache: false`` defaults the *cascade*
+    to off without closing the door on a nearer scope's opt-in, so it still
+    opens a store; the resolved per-query policy decides what gets written.
+
+    Returns:
+        ``None`` only when ``no_cache=True`` — callers pass this straight
+        through as ``ProjectSession(cache=...)``.
     """
-    cache = open_cache(path)
+    boot = resolve_cache_boot(project, no_cache=no_cache, cache_path=cache_path)
+    return open_cache(boot.path) if boot.enabled else None
+
+
+@contextmanager
+def project_cache_ctx(
+    project: FilesystemProject,
+    *,
+    no_cache: bool = False,
+    cache_path: Path | None = None,
+) -> Generator[TrivialDuckDBCache | None]:
+    """Context-managed ``open_project_cache``; closes the cache on exit if opened."""
+    cache = open_project_cache(project, no_cache=no_cache, cache_path=cache_path)
     try:
         yield cache
     finally:
-        cache.close()
+        if cache is not None:
+            cache.close()

dataface/agent_api/describe.py

@@ -198,8 +198,8 @@ def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
             ],
         )
 
-    resolved_project_path = project.path_for_fspath(resolved)
-    if not resolved_project_path.exists():
+    resolved_display = project.root / resolved.relpath
+    if not resolved.exists():
         hint = no_project_hint(project)
         return DescribeFaceResult(
             success=False,
@@ -207,21 +207,21 @@ def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
             errors=[
                 DatafaceError.from_code(
                     ERR_FILE_NOT_FOUND,
-                    path=str(resolved),
+                    path=resolved.relpath,
                     hint=hint,
                 ).to_diagnostic()
             ],
         )
 
     try:
-        result = compile_file(resolved_project_path.read_face())
+        result = compile_file(resolved.read_face())
     except OSError as exc:
         return DescribeFaceResult(
             success=False,
-            path=resolved,
+            path=resolved_display,
             errors=[
                 DatafaceError.from_code(ERR_INTERNAL, message=str(exc)).to_diagnostic(
-                    file=str(resolved)
+                    file=resolved.relpath
                 )
             ],
         )
@@ -229,7 +229,7 @@ def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
     if result.errors:
         return DescribeFaceResult(
             success=False,
-            path=resolved,
+            path=resolved_display,
             errors=list(result.errors),
         )
 
@@ -237,11 +237,11 @@ def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
     if face is None:
         return DescribeFaceResult(
             success=False,
-            path=resolved,
+            path=resolved_display,
             errors=[
                 DatafaceError.from_code(
                     ERR_INTERNAL, message="Compilation produced no face"
-                ).to_diagnostic(file=str(resolved))
+                ).to_diagnostic(file=resolved.relpath)
             ],
         )
 
@@ -285,7 +285,7 @@ def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
 
     return DescribeFaceResult(
         success=True,
-        path=resolved,
+        path=resolved_display,
         title=face.title or None,
         description=face.description or None,
         queries=query_descs,
@@ -339,13 +339,13 @@ def _describe_one_path(
             )
         ]
 
-    if not resolved.is_dir():
-        return [describe_face(resolved, project=project)]
+    resolved_display = project.root / resolved.relpath
+    if not resolved_display.is_dir():
+        return [describe_face(resolved_display, project=project)]
 
-    under = str(resolved.relative_to(project.root))
     faces = sorted(
         project.root / pf.relpath
-        for pf in project.iter_faces(under=under, recursive=True)
+        for pf in project.iter_faces(under=resolved.relpath, recursive=True)
         if pf.is_yaml
         and not pf.is_private
         and not (pf.parent / INSPECT_TEMPLATE_MANIFEST).exists()
@@ -354,11 +354,11 @@ def _describe_one_path(
         return [
             DescribeFaceResult(
                 success=False,
-                path=resolved,
+                path=resolved_display,
                 errors=[
                     DatafaceError.from_code(
                         ERR_INTERNAL,
-                        message=f"No face files found in {resolved}",
+                        message=f"No face files found in {resolved_display}",
                     ).to_diagnostic()
                 ],
             )

dataface/agent_api/docs/yaml-reference.md

@@ -14,6 +14,7 @@ AuthoredFace (dataface) definition from YAML.
 | `text` | str | ✓ | Markdown text content for text-only sections. |
 | `allow_html` | bool | ✓ | Render the face's body text as raw HTML via foreignObject instead of markdown. TRUSTED-CONTENT ONLY: the HTML (including any Jinja-interpolated values) is rendered as-authored — this is NOT a security sandbox. mdsvg strips <script>/event-handlers as a best-effort guard, not a guarantee. Enable only on first-party faces you fully control. |
 | `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.). |
 | `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. |
@@ -32,6 +33,14 @@ AuthoredFace (dataface) definition from YAML.
 | `extends` | str \| list[str] | ✓ | Face name(s) or relative path(s) this face inherits from, low to high priority. |
 | `auto_link` | bool | ✓ | When True, table charts with no explicit link: automatically link each row to its canonical /data/<source>/<schema>/<table>/detail/ page. Default off. Explicit link: always wins; set link: ~ to suppress per chart. |
 
+<a id="cache"></a>
+## Cache
+Cache policy at one scope: cache: 1h / forever / true / false (the only opt-out).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `ttl` | str \| enum: "forever" | ✓ | Expire cached results after this wall-clock age (lazy: the next read recomputes). Short-duration string: units s/m/h/d/w, m = minutes, compound allowed ('1h30m'). Omit to inherit from the parent scope; write 'forever' to override an inherited ttl with never-auto-expire (manual refresh always remains available). |
+
 <a id="variable"></a>
 ## Variable
 Variable definition from YAML.
@@ -67,7 +76,7 @@ Raw SQL query — the default query type.
 | `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` | bool | ✓ | Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `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: "sql" | ✓ | Query adapter type. |
 | `sql` | str | ✓ | SQL query string. Supports Jinja2 templates referencing variables. |
 | `setup_sql` | str | ✓ | Non-nestable SQL preamble executed before the main query (e.g., CREATE TEMP FUNCTION). |
@@ -82,7 +91,7 @@ dbt Semantic Layer (MetricFlow) query.
 | `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` | bool | ✓ | Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `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: "metricflow" | ✓ | Query adapter type. |
 | `metrics` | list[str] | ✓ | MetricFlow metric names to query. |
 | `dimensions` | list[str] | ✓ | MetricFlow dimensions to include in the result. |
@@ -99,7 +108,7 @@ REST API query.
 | `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` | bool | ✓ | Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `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). |
@@ -118,7 +127,7 @@ Inline rows embedded in YAML.
 | `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` | bool | ✓ | Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `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. |
@@ -133,7 +142,7 @@ dbt source schema query.
 | `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` | bool | ✓ | Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `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: "schema" | ✓ | Query adapter type. |
 | `schema` | str | ✓ | Schema name for schema queries (YAML key: schema). |
 | `table` | str | ✓ | Table name for schema queries. |
@@ -148,7 +157,7 @@ LookML semantic query — compiled to SQL through likeml at compile time.
 | `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` | bool | ✓ | Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `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. |
@@ -1057,7 +1066,7 @@ Authored overlay for BoardStyle. Face-level structural dimensions. Do NOT cascad
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `width` | float | ✓ | Maximum dashboard width in pixels. |
+| `width` | float | ✓ | Maximum dashboard width in pixels. Caps the measured layout width, setting the board's proportions. Rendered as an on-screen pixel maximum everywhere except the dft HTML page (dft serve, dft render --format html), which scales the board to its container. |
 | `min_height` | float | ✓ | Minimum board height in pixels. |
 | `margin` | float | ✓ | Board outer margin in pixels. |
 | `card_padding` | float | ✓ | Padding added to each card side in pixels. |
@@ -2227,7 +2236,7 @@ Authored overlay for AxisElementStyle. Axis label or title: font + padding + VL-
 | `padding` | float | ✓ | Padding between axis labels and ticks in pixels; None inherits from parent axis. |
 | `max_width` | float | ✓ | Maximum label width in pixels; None uses Vega-Lite's default (180px). |
 | `angle` | float | ✓ | Label rotation angle in degrees; None uses Vega-Lite's default. |
-| `align` | str | ✓ | Horizontal text alignment of labels; None uses Vega-Lite's default. |
+| `align` | enum: "left", "right", "center", "inward", "outward" | ✓ | Horizontal text alignment of labels. 'left'/'right'/'center' are absolute. 'inward' hugs the plot (own-side: left on a left axis, right on a right axis); 'outward' hugs away from the plot (Vega-Lite's default growth direction). inward/outward are a no-op on an axis with no left/right edge. None uses Vega-Lite's default. |
 | `baseline` | str | ✓ | Vertical text baseline of labels; None uses Vega-Lite's default. |
 | `overlap` | [AxisLabelOverlapConfig](#axislabeloverlapconfig) | ✓ | Label overlap strategy enablement. None inherits from the theme cascade. Set individual bools to enable/disable; the resolver applies them in fixed order tilt→skip. Temporal-bucketed axes ignore this and step the label cadence instead. |
 | `separation` | float | ✓ | Minimum pixel separation between labels; None uses Vega-Lite's default (0px). |
@@ -2799,6 +2808,7 @@ Postgres source configuration.
 | `dbname` | str |  | Database name (matches dbt 'dbname'). |
 | `user` | str |  | Database user name. |
 | `password` | str |  | Database password. |
+| `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. |
 | `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. |
 | `port` | int | ✓ | Database port number. |
@@ -2816,6 +2826,7 @@ Snowflake source configuration.
 | `user` | str |  | Snowflake user name. |
 | `database` | str |  | Snowflake database name. |
 | `warehouse` | str |  | Snowflake virtual warehouse name. |
+| `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. |
 | `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. |
 | `password` | str | ✓ | Snowflake password. Omit when using OAuth or key-pair auth. |
@@ -2831,6 +2842,7 @@ BigQuery source configuration.
 | `type` | enum: "bigquery" |  | Source type identifier. |
 | `project` | str |  | GCP project ID. |
 | `dataset` | str |  | BigQuery dataset name (equivalent to schema). |
+| `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. |
 | `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. |
 | `keyfile` | str | ✓ | Path to service account JSON key file. |
@@ -2849,6 +2861,7 @@ Redshift source configuration.
 | `dbname` | str |  | Redshift database name. |
 | `user` | str |  | Redshift user name. |
 | `password` | str |  | Redshift password. |
+| `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. |
 | `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. |
 | `port` | int | ✓ | Redshift port number. |
@@ -2865,6 +2878,7 @@ MySQL source configuration.
 | `database` | str |  | MySQL database name. |
 | `user` | str |  | MySQL user name. |
 | `password` | str |  | MySQL password. |
+| `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. |
 | `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. |
 | `port` | int | ✓ | MySQL port number. |
@@ -2877,6 +2891,7 @@ DuckDB source configuration.
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `type` | enum: "duckdb" |  | Source type identifier. |
+| `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. |
 | `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. |
 | `path` | str | ✓ | DuckDB file path or ':memory:' for an in-memory database. |
@@ -2892,6 +2907,7 @@ SQLite source configuration.
 | `path` | str |  | Path to the SQLite database file. |
 | `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. |
+| `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. |
 
 <a id="csvsourceconfig"></a>
 ## CsvSourceConfig
@@ -2901,6 +2917,7 @@ CSV file source configuration.
 |-------|------|:--------:|-------------|
 | `type` | enum: "csv" |  | Source type identifier. |
 | `files` | dict[str, str] |  | Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty. |
+| `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. |
 | `delimiter` | str | ✓ | Field delimiter character. |
 | `encoding` | str | ✓ | File encoding. |
 
@@ -2908,19 +2925,21 @@ CSV file source configuration.
 ## ParquetSourceConfig
 Parquet file source configuration.
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | enum: "parquet" | Source type identifier. |
-| `files` | dict[str, str] | Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty. |
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "parquet" |  | Source type identifier. |
+| `files` | dict[str, str] |  | Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty. |
+| `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. |
 
 <a id="jsonsourceconfig"></a>
 ## JsonSourceConfig
 JSON file source configuration.
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | enum: "json" | Source type identifier. |
-| `files` | dict[str, str] | Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty. |
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `type` | enum: "json" |  | Source type identifier. |
+| `files` | dict[str, str] |  | Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty. |
+| `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. |
 
 <a id="httpsourceconfig"></a>
 ## HttpSourceConfig
@@ -2930,6 +2949,7 @@ HTTP/REST API source configuration.
 |-------|------|:--------:|-------------|
 | `type` | enum: "http" |  | Source type identifier. |
 | `url` | str |  | Base URL for HTTP requests. |
+| `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. |
 | `headers` | dict[str, str] | ✓ | Default HTTP headers (e.g. Authorization). |
 
 <a id="dbtprofilesourceconfig"></a>
@@ -2940,6 +2960,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. |
 | `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. |