dataface 0.1.6.dev360__py3-none-any.whl → 0.1.6.dev426__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -253,6 +253,32 @@ Rules:
 - Each alias must be unique across the project — two faces claiming the same alias is a startup error.
 - Aliasing a generated system route (data or inspector view) is allowed: the redirect takes precedence, letting you override what that URL serves.
 
+#### Parameterized aliases (capture a path segment into a variable)
+
+An alias may contain `<name>` capture segments.  A request matching the pattern
+302-redirects to the face's canonical URL with each captured segment appended as a
+query param of the same name — which the face then reads as its variable.  This
+gives a single detail face a clean per-entity URL:
+
+```yaml
+# faces/milestone.yml  (canonical URL: /milestone)
+aliases:
+  - /milestones/<name>
+variables:
+  name: { input: select, options: { query: milestone_options, column: slug } }
+```
+
+Now `/milestones/m3-public-launch` redirects to `/milestone/?name=m3-public-launch`,
+and `milestone.yml` renders with `name` bound to `m3-public-launch`.
+
+- Capture names use the same grammar as built-in routes: `<name>` matches exactly
+  one non-empty path segment (no `/`).  Use a capture name that matches the
+  variable you want it to fill.
+- A real face file always wins over a pattern alias, so `/milestones/` (the list
+  face) and `/milestones/<name>` (the detail redirect) coexist without conflict.
+- Plain aliases (no `<...>`) redirect as before; only aliases with a capture are
+  treated as patterns.
+
 There are two ways to override a data/inspector route for a given path:
 - **Face file at that path** — create `faces/data/warehouse/schema/table.yml` and the server renders it directly (no redirect).
 - **`aliases:` entry** — any face can declare `/data/…/` as an alias; the server issues a 302 to the declaring face's canonical URL.

dataface/agent_api/docs/yaml-reference.md

@@ -287,6 +287,7 @@ Authored patch for KPI (key performance indicator) charts.
 | `label` | str | ✓ | KPI label rendered above the headline value. |
 | `support` | [KpiSupportConfig](#kpisupportconfig) | ✓ | Optional support line beneath the KPI value. |
 | `style` | [KpiChartStyle](#kpichartstyle) | ✓ | Chart-local style overrides. |
+| `background` | str \| dict[str, Any] | ✓ | Gradient background channel — {column, scale} shape. Paints the card background by the value's position in the scale. See channel.py parse_style_channel for the full grammar. |
 
 <a id="tablechart"></a>
 ## TableChart
@@ -848,6 +849,7 @@ Authored overlay for TableChartStyle. Table chart style overrides layered on top
 | `more_rows` | [TableEdgeStyle](#tableedgestyle) | ✓ | Style for the 'more rows' edge-case indicator. |
 | `empty_state` | [TableEdgeStyle](#tableedgestyle) | ✓ | Style for the empty-state (no data) indicator. |
 | `spark` | [SparkStyle](#sparkstyle) | ✓ | Inline sparkline defaults for table cells. |
+| `transpose` | bool | ✓ | When True, render a single wide data row as N (label, value) rows — one per column. Raises ChartDataError when data has more than one row. Used for Looker single-value summary tiles with multiple measures. |
 | `text_baseline_offset` | float | ✓ | Vertical offset to align SVG text baseline with cell grid in pixels. |
 | `title_baseline_offset` | float | ✓ | Vertical offset to align SVG title baseline in pixels. |
 | `title_subtitle_gap` | float | ✓ | Gap between table title and subtitle lines in pixels. |
@@ -1348,6 +1350,7 @@ Authored overlay for LegendStyle.
 | `title` | [LegendElementStyle](#legendelementstyle) | ✓ | Legend title style. |
 | `visible` | bool | ✓ | Show the legend. None = legend visible; False = explicitly suppressed. |
 | `interactive_legend` | bool | ✓ | Emit a dft_legend point-selection param for single-click series toggle. |
+| `symbol_limit` | int | ✓ | Maximum number of legend entries to display; maps to VL symbolLimit. None uses Vega-Lite's default (no cap). Set to a positive integer to prevent legend overflow on high-cardinality series. |
 
 <a id="tooltipstyle"></a>
 ## TooltipStyle
@@ -1569,6 +1572,7 @@ Authored overlay for TableColumnsStyle.
 | `default_width` | float | ✓ | Default column width in pixels. |
 | `cell_padding` | float | ✓ | Horizontal padding inside table cells in pixels. |
 | `width_similarity_threshold` | float | ✓ | Auto-width columns whose min/max ratio &gt;= this threshold are snapped to a shared width before budget allocation. 1.0 disables clustering; 0.0 forces all auto-columns to equal width. |
+| `content_headroom` | float | ✓ | Fractional breathing room added above the raw p95 column demand when pinning compact columns in mixed (compact + text) tables.  0.10 means each compact column is pinned at 10 % above its measured demand; the extra width is funded by the text-column budget.  Has no effect on all-compact tables (proportional scaling already fills the budget).  0.0 disables headroom. |
 
 <a id="tableheaderstyle"></a>
 ## TableHeaderStyle

dataface/agent_api/project_session.py

@@ -35,7 +35,7 @@ from dataface.core.execute.adapters.adapter_registry import (
     AdapterRegistry,
     build_adapter_registry,
 )
-from dataface.core.execute.duckdb_cache import DuckDBCache
+from dataface.core.execute.cache_backend import QueryResultCache
 from dataface.core.execute.observability import WarehouseObserver
 from dataface.core.inspect.query_validator import (
     QueryDiagnostic,
@@ -68,7 +68,7 @@ class ProjectSession:
     """
 
     project: Project
-    cache: DuckDBCache | None
+    cache: QueryResultCache | None
     _owns_registry: bool
     _read_only: bool
     _connection_string: str | None
@@ -82,7 +82,7 @@ class ProjectSession:
     def __init__(
         self,
         project: Project,
-        cache: DuckDBCache | None = None,
+        cache: QueryResultCache | None = None,
         adapter_registry: AdapterRegistry | None = None,
         read_only: bool = True,
         observers: list[WarehouseObserver] | None = None,
@@ -110,7 +110,7 @@ class ProjectSession:
         cls,
         project_dir: Path | str,
         *,
-        cache: DuckDBCache | None = None,
+        cache: QueryResultCache | None = None,
         read_only: bool = True,
         connection_string: str | None = None,
         dialect: str = "duckdb",
@@ -150,7 +150,7 @@ class ProjectSession:
         cls,
         project: Project,
         *,
-        cache: DuckDBCache | None = None,
+        cache: QueryResultCache | None = None,
         read_only: bool = True,
         connection_string: str | None = None,
         dialect: str = "duckdb",
@@ -183,7 +183,7 @@ class ProjectSession:
         face_file: Path | str,
         *,
         read_only: bool = True,
-        cache: DuckDBCache | None = None,
+        cache: QueryResultCache | None = None,
     ) -> Self:
         """Open a ProjectSession rooted at the project directory discovered upward from face_file."""
         resolved = Path(face_file).resolve()

dataface/agent_api/render_face.py

@@ -13,8 +13,8 @@ from dataface.core.compile.markdown import (
     is_markdown_face,
     markdown_to_yaml,
 )
-from dataface.core.execute.duckdb_cache import DuckDBCache
-from dataface.core.project import Project
+from dataface.core.execute.cache_backend import QueryResultCache
+from dataface.core.project import Project, ProjectFile
 from dataface.core.render.face_api import compile_and_render
 
 
@@ -26,7 +26,7 @@ def render_face(
     project: Project | None = None,
     variables: dict[str, str] | None = None,
     use_cache: bool = True,
-    cache: DuckDBCache | None = None,
+    cache: QueryResultCache | None = None,
     **options: Any,
 ) -> str | bytes:
     """Render a Dataface face file (.yml or .md) to embeddable output.
@@ -70,7 +70,15 @@ def render_face(
         project_session = ProjectSession.from_face(face_file, cache=cache)
     try:
         p = project_session.project
-        base_file = p.file_for_path(face_file)
+        # The face may live outside an explicitly-supplied project root — e.g.
+        # the looker_migrate eval renders faces under evals/runs/ against a
+        # project rooted at runtime/ for its sources/schema. Such a face has no
+        # project-relative handle; nested sub-file refs are unsupported in that
+        # mode (relative reads still resolve via face_dir below).
+        try:
+            base_file: ProjectFile | None = p.file_for_path(face_file)
+        except ValueError:
+            base_file = None
         return compile_and_render(
             yaml_content,
             p,

dataface/ai/skills/dashboard-build/SKILL.md

@@ -129,6 +129,8 @@ Skip this step when you are previewing ephemerally — see "Previewing vs. savin
 
 Fix any errors `{{ s_validate_dashboard }}` reports, then re-run until it passes.
 
+**YAML style:** write block style — one key per line. Avoid JSON-like inline flow maps (`{ type: bar, x: month }`); they read and diff worse than indented blocks. Inline arrays (`y: [revenue, cost]`) are fine.
+
 ## Parameterized Queries — Use From the Start
 
 Use `{{ variable_name }}` syntax for any configurable values, even during exploration:

dataface/core/compile/channel.py

@@ -130,7 +130,7 @@ def validate_channel_fields(
             )
 
 
-_COLOR_CHANNELS = frozenset({"color"})
+_COLOR_CHANNELS = frozenset({"color", "background"})
 _NUMERIC_CHANNELS: frozenset[str] = frozenset()
 
 
@@ -165,8 +165,10 @@ def normalize_chart_channels(
 ) -> dict[str, ResolvedStyleChannel]:
     """Parse and validate chart-level style channels.
 
-    Only ``color`` is a data channel at chart root. background/opacity/stroke
-    were removed as data channels (they are paint fields, not data bindings).
+    ``color`` is a data channel at chart root for all chart types.
+    ``background`` is a data channel at chart root for KPI charts only
+    (gradient background painted by value position in scale).
+    Other paint fields (opacity, stroke) are not data channels.
 
     ``style_color``: when a ``StyleColorConfig`` with a scale is provided, the
     series color channel is upgraded to gradient mode.  A plain string value
@@ -182,6 +184,11 @@ def normalize_chart_channels(
     if color_raw is not None:
         channels["color"] = parse_style_channel(color_raw, "color")
 
+    if chart_type == "kpi":
+        background_raw = chart.background
+        if background_raw is not None:
+            channels["background"] = parse_style_channel(background_raw, "background")
+
     # Upgrade series channel to gradient when style.color carries a scale.
     if isinstance(style_color, StyleColorConfig):
         if "color" not in channels:

dataface/core/compile/models/chart/authored.py

@@ -1538,6 +1538,17 @@ class KpiChart(_BaseChartFields):
         KpiChartStylePatch | None,
         Field(default=None, description="Chart-local style overrides."),
     ]
+    background: Annotated[
+        str | dict[str, Any] | None,
+        Field(
+            default=None,
+            description=(
+                "Gradient background channel — {column, scale} shape. "
+                "Paints the card background by the value's position in the scale. "
+                "See channel.py parse_style_channel for the full grammar."
+            ),
+        ),
+    ]
 
     @field_validator("value", mode="before")
     @classmethod

dataface/core/compile/models/chart/normalized.py

@@ -201,6 +201,13 @@ class Chart(BaseModel):
     support: KpiSupportConfig | None = Field(
         default=None, description="Optional support line beneath the KPI value."
     )
+    background: str | dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "KPI gradient background channel — {column, scale} shape. "
+            "Parsed at render time via parse_style_channel. None for all other chart types."
+        ),
+    )
     projection: str | Projection | None = Field(
         default=None, description="Map projection name or Vega-Lite projection config."
     )

dataface/core/compile/models/style/resolved.py

@@ -195,6 +195,7 @@ class ResolvedLegendStyle:
     title: ResolvedLegendElementStyle
     interactive_legend: bool
     visible: bool | None = None
+    symbol_limit: int | None = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -885,6 +886,7 @@ def _build_resolved_legend(legend: LegendStyle) -> ResolvedLegendStyle:
         direction=legend.direction,
         visible=legend.visible,
         interactive_legend=legend.interactive_legend,
+        symbol_limit=legend.symbol_limit,
         label=ResolvedLegendElementStyle(
             font=resolve_cascaded_font(legend.label.font, "charts.legend.label.font"),
             padding=legend.label.padding,

dataface/core/compile/models/style/theme.py

@@ -1089,6 +1089,15 @@ class LegendStyle(BaseModel):
     interactive_legend: bool = Field(
         description="Emit a dft_legend point-selection param for single-click series toggle.",
     )
+    symbol_limit: int | None = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Maximum number of legend entries to display; maps to VL symbolLimit. "
+            "None uses Vega-Lite's default (no cap). "
+            "Set to a positive integer to prevent legend overflow on high-cardinality series."
+        ),
+    )
 
 
 # Inference
@@ -2586,6 +2595,18 @@ class TableColumnsStyle(BaseModel):
             "0.0 forces all auto-columns to equal width."
         ),
     )
+    content_headroom: float = Field(
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Fractional breathing room added above the raw p95 column demand when "
+            "pinning compact columns in mixed (compact + text) tables.  0.10 means "
+            "each compact column is pinned at 10 % above its measured demand; the "
+            "extra width is funded by the text-column budget.  Has no effect on "
+            "all-compact tables (proportional scaling already fills the budget).  "
+            "0.0 disables headroom."
+        ),
+    )
 
 
 class TableHeaderStyle(BaseModel):
@@ -2988,6 +3009,18 @@ class TableChartStyle(_ChartStyleBaseAllOptional):
     )
     spark: SparkStyle = Field(description="Inline sparkline defaults for table cells.")
 
+    # Authored convenience — not a theme constant; defaults False so themes need
+    # not supply it.  When True the renderer pivots a single wide data row into
+    # N (label, value) rows, one per column.
+    transpose: bool = Field(
+        default=False,
+        description=(
+            "When True, render a single wide data row as N (label, value) rows — "
+            "one per column. Raises ChartDataError when data has more than one row. "
+            "Used for Looker single-value summary tiles with multiple measures."
+        ),
+    )
+
     # SVG layout constants (all-config per ADR-002)
     text_baseline_offset: float = Field(
         description="Vertical offset to align SVG text baseline with cell grid in pixels."

dataface/core/compile/style_cascade.py

@@ -121,6 +121,10 @@ def _merge_legend(
         updates["direction"] = patch.direction
     if patch.visible is not None:
         updates["visible"] = patch.visible
+    # symbol_limit=None on the patch means "unset / inherit base"; only an
+    # explicitly authored integer overrides the resolved value.
+    if patch.symbol_limit is not None:  # pyright: ignore[reportUnnecessaryComparison]
+        updates["symbol_limit"] = patch.symbol_limit
     for sub_name in ("label", "title"):
         sub_patch = getattr(patch, sub_name)
         if sub_patch is None:

dataface/core/dashboard.py

@@ -43,7 +43,7 @@ from dataface.core.errors import (
 from dataface.core.errors.structured import NextCommand
 from dataface.core.execute import ExecutionError, Executor
 from dataface.core.execute.adapters import AdapterRegistry
-from dataface.core.execute.duckdb_cache import DuckDBCache
+from dataface.core.execute.cache_backend import QueryResultCache
 from dataface.core.project import Project
 from dataface.core.render.warnings.base import RenderWarning
 from dataface.core.render.warnings.suppression import partition as _partition_warnings
@@ -164,7 +164,7 @@ def render_dashboard(
     scale: float | None = None,
     as_link: bool = False,
     link_context: LinkContext | None = None,
-    duckdb_cache: DuckDBCache | None,
+    duckdb_cache: QueryResultCache | None,
     ignore_codes: set[str] | None = None,
     url_mount_dir: str = "",
     max_workers: int | None = None,

dataface/core/defaults/themes/_base.yaml

@@ -231,6 +231,7 @@ style:
     legend:
       position: right
       direction: vertical
+      symbol_limit: 20
       label:
         font:
           size:  *size_label
@@ -276,6 +277,10 @@ style:
         default_width: 100.0
         cell_padding: 8.0
         width_similarity_threshold: 0.8
+        # Opt-in: 0.0 globally (no width change to existing dashboards). The
+        # Looker migrator sets this per-table so migrated tables get breathing
+        # room without perturbing every authored table's column widths.
+        content_headroom: 0.0
       title_row:
         height: 40.0
       more_rows:

dataface/core/execute/_duckdb_cache_base.py

@@ -0,0 +1,272 @@
+"""Shared base and helpers for DuckDB-backed QueryResultCache implementations.
+
+Stage: EXECUTE (Cache)
+Purpose: Hold the connection lifecycle, SQL helpers, and failure store
+that are identical across DuckDBCache (full history) and
+TrivialDuckDBCache (replace-on-write).
+
+The two subclasses override only the parts that genuinely diverge:
+  - get/put  — result-table schema and sequencing logic differ
+  - _ensure_result_table  — seq columns (DuckDBCache) vs none (Trivial)
+  - _drop_*_tables  — legacy-table cleanup differs
+
+Public helpers (_q, _result_table_name, _cache_safe_value, _infer_type)
+live here so both subclasses share one definition and duckdb_cache.py
+can re-export them without a circular import.
+
+Dependencies:
+    - duckdb (optional at module load; required at construction)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import threading
+import traceback as tb_mod
+from datetime import datetime
+from decimal import Decimal
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import duckdb
+
+    HAS_DUCKDB = True
+else:
+    try:
+        import duckdb
+
+        HAS_DUCKDB = True
+    except ImportError:
+        duckdb = None
+        HAS_DUCKDB = False
+
+from dataface._install_hint import install_hint
+from dataface.core.execute.cache_backend import CachedQueryFailure
+
+logger = logging.getLogger(__name__)
+
+# How long to keep a combined hash prefix for table names
+_HASH_PREFIX = 12
+
+# Exported: these helpers are defined here to avoid duplication but used by
+# duckdb_cache.py and trivial_local_cache.py (subclass modules).
+__all__ = [
+    "_DuckDBResultCacheBase",
+    "_cache_safe_value",
+    "_infer_type",
+    "_q",
+    "_result_table_name",
+]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SQL helper functions (re-exported by duckdb_cache for backward compat)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def _q(identifier: str) -> str:
+    """Quote a SQL identifier (already assumed safe)."""
+    escaped = identifier.replace('"', '""')
+    return f'"{escaped}"'
+
+
+def _result_table_name(source_hash: str, query_hash: str, variables_hash: str) -> str:
+    """Generate the table name for a cached result.
+
+    Format: _r_{combined_prefix} where combined is a short hash of all three key parts.
+    Short enough to stay under DuckDB's identifier limits.
+    """
+    combined = hashlib.sha256(
+        f"{source_hash}:{query_hash}:{variables_hash}".encode()
+    ).hexdigest()[:_HASH_PREFIX]
+    return f"_r_{combined}"
+
+
+def _cache_safe_value(value: Any) -> Any:
+    """Coerce a Python value to something DuckDB's parameterized INSERT accepts.
+
+    Decimals become float: DuckDB's DECIMAL is HUGEINT-backed and capped at
+    precision 38, but BigQuery NUMERIC can return precision > 38 (e.g. NUMERIC(47,38)
+    on fan-out-deduplicated SUM aggregates). float's 15 significant digits are
+    plenty for dashboard rendering. list/dict become JSON text for the JSON column.
+    """
+    if isinstance(value, Decimal):
+        return float(value)
+    if isinstance(value, (list, dict)):
+        return json.dumps(value)
+    return value
+
+
+def _infer_type(value: Any) -> str:
+    if value is None:
+        return "VARCHAR"
+    if isinstance(value, bool):
+        return "BOOLEAN"
+    if isinstance(value, int):
+        return "BIGINT"
+    if isinstance(value, (float, Decimal)):
+        return "DOUBLE"
+    if isinstance(value, datetime):
+        return "TIMESTAMP"
+    if isinstance(value, (list, dict)):
+        return "JSON"
+    return "VARCHAR"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Abstract base class
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class _DuckDBResultCacheBase:
+    """Abstract base for DuckDB-backed result caches.
+
+    Manages: connection lifecycle, failure store (_query_failures).
+
+    Subclasses must implement: get, put, and any storage-specific setup
+    (_drop_*_tables, _ensure_result_table, _insert_rows).
+    """
+
+    def __init__(
+        self,
+        db_path: Path | None = None,
+        failure_ttl_seconds: int = 900,
+        result_ttl_seconds: int | None = None,
+        *,
+        _class_name: str,
+    ) -> None:
+        if not HAS_DUCKDB:
+            raise ImportError(
+                f"DuckDB is required to use {_class_name}. "
+                f"Install it with: {install_hint('duckdb')}"
+            )
+
+        self.db_path = db_path
+        self.failure_ttl_seconds = failure_ttl_seconds
+        self.result_ttl_seconds = result_ttl_seconds
+        self._lock = threading.RLock()
+
+        if db_path:
+            self.conn = duckdb.connect(str(db_path))
+        else:
+            self.conn = duckdb.connect(":memory:")
+
+        self.conn.execute("SET enable_object_cache = true")
+
+    def get_failure(
+        self, source_hash: str, query_hash: str, variables_hash: str
+    ) -> CachedQueryFailure | None:
+        """Return a cached failure if within TTL, else None."""
+        if self.failure_ttl_seconds == 0:
+            return None
+        with self._lock:
+            row = self.conn.execute(
+                """
+                SELECT error_class, error_message, traceback, failed_at
+                FROM _query_failures
+                WHERE source_hash = ? AND query_hash = ? AND variables_hash = ?
+                """,
+                [source_hash, query_hash, variables_hash],
+            ).fetchone()
+        if row is None:
+            return None
+        error_class, error_message, traceback, failed_at = row
+        elapsed = (datetime.now() - failed_at).total_seconds()
+        if elapsed > self.failure_ttl_seconds:
+            return None
+        return CachedQueryFailure(
+            error_class=error_class,
+            error_message=error_message,
+            traceback=traceback,
+            failed_at=failed_at,
+        )
+
+    def put_failure(
+        self,
+        source_hash: str,
+        query_hash: str,
+        variables_hash: str,
+        exception: Exception,
+        *,
+        face_slug: str,
+        query_name: str,
+    ) -> None:
+        """Store a query failure keyed by (source_hash, query_hash, variables_hash)."""
+        with self._lock:
+            self.conn.execute(
+                """
+                INSERT OR REPLACE INTO _query_failures
+                    (source_hash, query_hash, variables_hash,
+                     face_slug, query_name,
+                     error_class, error_message, traceback, failed_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                [
+                    source_hash,
+                    query_hash,
+                    variables_hash,
+                    face_slug,
+                    query_name,
+                    type(exception).__name__,
+                    str(exception),
+                    "".join(tb_mod.format_exception(exception)),
+                    datetime.now(),
+                ],
+            )
+
+    def clear(self, source_hash: str, query_hash: str, variables_hash: str) -> None:
+        """Remove success and failure entries for this key."""
+        with self._lock:
+            self.conn.execute(
+                "DELETE FROM _query_failures WHERE source_hash = ? AND query_hash = ? AND variables_hash = ?",
+                [source_hash, query_hash, variables_hash],
+            )
+            tbl = _result_table_name(source_hash, query_hash, variables_hash)
+            if self._table_exists(tbl):
+                self.conn.execute(f"DROP TABLE {_q(tbl)}")
+
+    def close(self) -> None:
+        with self._lock:
+            self.conn.close()
+
+    def _ensure_schema(self) -> None:
+        """Create the system tables if they don't exist."""
+        self.conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS _query_failures (
+                source_hash TEXT NOT NULL,
+                query_hash TEXT NOT NULL,
+                variables_hash TEXT NOT NULL,
+                face_slug TEXT NOT NULL,
+                query_name TEXT NOT NULL,
+                error_class TEXT NOT NULL,
+                error_message TEXT NOT NULL,
+                traceback TEXT,
+                failed_at TIMESTAMP NOT NULL,
+                PRIMARY KEY (source_hash, query_hash, variables_hash)
+            )
+            """
+        )
+
+    def _table_exists(self, name: str) -> bool:
+        try:
+            result = self.conn.execute(
+                "SELECT COUNT(*) FROM information_schema.tables WHERE table_name = ?",
+                [name],
+            ).fetchone()
+            return bool(result and result[0] > 0)
+        except duckdb.CatalogException:
+            return False
+
+    def _column_names(self, table_name: str) -> set[str]:
+        try:
+            rows = self.conn.execute(
+                "SELECT column_name FROM information_schema.columns WHERE table_name = ?",
+                [table_name],
+            ).fetchall()
+            return {r[0] for r in rows}
+        except duckdb.CatalogException:
+            return set()