dataface 0.1.2__py3-none-any.whl

dataface/ai/skills/dataface-troubleshooting/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: dataface-troubleshooting
+kind: workflow
+description: >
+  Diagnose and fix Dataface dashboard errors. Use when validation, query
+  execution, query inspection, or dashboard rendering returns an error, when a
+  dashboard renders but looks wrong, when SQL fails, when YAML won't validate,
+  or when the user says 'fix this error', 'debug this dashboard', 'why is this
+  broken', 'chart shows no data'. Covers YAML validation failures, SQL
+  execution errors, rendering issues, and variable misconfiguration. Do NOT
+  use for building new dashboards from scratch (use dashboard-build). Do NOT
+  use for design quality review (use dashboard-design).
+metadata:
+  author: fivetran
+---
+
+# Troubleshooting Dataface
+
+Systematically diagnose and fix errors when building Dataface dashboards. Never guess — use the tools to confirm.
+
+## The Iron Rule
+
+**Never change working YAML to "fix" a problem you haven't diagnosed.** Read the error message. Reproduce it. Understand the cause. Then fix it.
+
+## Diagnostic Workflow
+
+```
+Error occurs
+  → Read the full error message (not just the first line)
+  → Classify: YAML error, SQL error, or rendering issue?
+  → Apply the relevant fix pattern below
+  → Validate again to confirm the fix
+```
+
+## YAML Validation Errors
+
+These come from `{{ s_validate_dashboard }}`. The error message tells you exactly what's wrong.
+
+### "must have at least one layout"
+
+Every face needs a layout element. Add `rows: []`, `cols: []`, `grid: {...}`, `tabs: {...}`, or `text: "..."`.
+
+### "references unknown chart 'X'"
+
+**The most common error.** Layout references *charts*, not queries. The fix:
+
+```yaml
+# WRONG — referencing a query name in layout
+queries:
+  my_query:
+    sql: SELECT ...
+rows:
+  - my_query              # ❌ This is a query, not a chart
+
+# RIGHT — create a chart that references the query
+queries:
+  my_query:
+    sql: SELECT ...
+charts:
+  my_chart:
+    query: my_query       # Chart references query
+    type: table
+rows:
+  - my_chart              # ✅ Layout references chart
+```
+
+**Structure order: Queries → Charts → Layout.** You cannot skip the Charts layer.
+
+### "missing required: query"
+
+Charts need a `query:` field. Either reference a named query or define one inline:
+
+```yaml
+charts:
+  my_chart:
+    query: my_query           # Reference a named query
+    type: bar
+    x: category
+    y: value
+
+  # OR inline
+  my_chart:
+    query:
+      sql: SELECT ...
+      source: my_profile
+    type: bar
+    x: category
+    y: value
+```
+
+### "source required" / "missing source"
+
+SQL queries must specify which data source to use. Either set a top-level `source:` or specify per-query:
+
+```yaml
+source: my_profile            # Top-level default
+
+queries:
+  uses_default:
+    sql: SELECT ...           # Inherits top-level source
+
+  explicit:
+    sql: SELECT ...
+    source: other_profile     # Overrides for this query
+```
+
+### Variable Options Errors
+
+The `default` field goes at the variable level, NOT inside `options`:
+
+```yaml
+# WRONG
+variables:
+  region:
+    input: select
+    options:
+      static: [North, South]
+      default: North          # ❌
+
+# RIGHT
+variables:
+  region:
+    input: select
+    options:
+      static: [North, South]
+    default: North            # ✅
+```
+
+Use `options.static` for static values, not `options.values`.
+
+## SQL Execution Errors
+
+These come from `{{ s_query_face }}`, `{{ s_execute_query }}`, or `{{ s_render_dashboard }}`.
+
+### "table does not exist"
+
+Discover available tables first via `{{ s_schema }}` (hierarchy drill-down) or `{{ s_schema_search }}` (keyword search). For ad-hoc SQL against the information schema:
+
+```sql
+-- PostgreSQL / Redshift
+SELECT table_schema, table_name FROM information_schema.tables;
+
+-- BigQuery
+SELECT table_name FROM `project.dataset.INFORMATION_SCHEMA.TABLES`;
+
+-- Snowflake
+SHOW TABLES IN SCHEMA my_schema;
+```
+
+### "column does not exist"
+
+Check actual column names — don't guess. Use `{{ s_schema }}` at the table/column level for profiling details when available, or:
+
+```sql
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_name = 'my_table';
+```
+
+### Type mismatches
+
+Common causes:
+
+- Comparing a string column to an unquoted value: `WHERE status = active` → `WHERE status = 'active'`
+- Date functions that differ between databases (BigQuery vs Postgres vs Snowflake)
+- Aggregating a non-numeric column
+
+## Rendering Issues
+
+These show up when `{{ s_render_dashboard }}` produces unexpected visual results.
+
+### Chart shows no data
+
+- Verify the query returns rows: `{{ s_execute_query }}` with the same SQL
+- Check that `x:` and `y:` column names match the query's SELECT aliases exactly (case-sensitive)
+- Check variable defaults — a restrictive filter might exclude all data
+
+### Chart axes are wrong
+
+- Ensure `x:` is the categorical/time column and `y:` is the numeric column
+- For time series, ensure the date column is sorted in the SQL: `ORDER BY date`
+
+### Layout doesn't look right
+
+- Check column spans: `cols: [chart_a, 2]` means chart_a spans 2 columns
+- Charts in a `cols:` array share the row equally unless spans are specified
+- Too many items in one `cols:` array = each gets too narrow
+
+## Debugging Checklist
+
+When stuck, work through this in order:
+
+1. **Read the full error** — not just the first line. The details matter.
+2. **Validate the YAML** — `{{ s_validate_dashboard }}` catches structural issues before SQL runs.
+3. **Test one query at a time** — `{{ s_query_face }}` for saved face queries, `{{ s_execute_query }}` for raw SQL.
+4. **Check column names** — `{{ s_schema }}`, `{{ s_schema_search }}`, or `{{ s_describe_query }}` to verify.
+5. **Simplify** — Remove charts until you find the one that's broken.
+6. **Re-render** — Confirm the fix visually.
+7. **Restore metadata** — Ensure `description` fields remain populated for queries/charts/variables/layout sections.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Changing YAML randomly until errors stop | Read the error. Diagnose first, then fix. |
+| Referencing queries in layout | Create a chart that references the query. Layout references charts. |
+| Assuming column names | Use `{{ s_schema }}`, `{{ s_schema_search }}`, or `{{ s_execute_query }}` to verify |
+| Wrong `source` | Call `{{ s_schema }}` (no args) to see available sources |
+| Variable `default` inside `options` | `default` goes at the variable level, not nested inside `options` |
+
+## Rationalizations to Resist
+
+| Excuse | Reality |
+|--------|---------|
+| "The error message is confusing, I'll try something else" | Read it again carefully — it tells you what's wrong. |
+| "I'll just change the chart type, maybe that'll fix it" | Chart type doesn't fix SQL or YAML structure errors. |
+| "It works for similar dashboards" | This data source may have different column names. Verify. |
+| "I'll skip validation and just render" | Validation is instant and catches errors before the slow SQL runs. |
+
+## Red Flags — STOP
+
+- About to make a change without understanding the error message
+- Changing multiple things at once (change one thing, validate, repeat)
+- Guessing column names instead of checking the schema
+- The same error keeps coming back (you're not fixing the root cause)

dataface/ai/skills/drill-down-link/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: drill-down-link
+kind: pattern
+description: >
+  Pattern for cross-face navigation: a chart or table whose elements link to a
+  detail face, passing a row value as a URL path segment or query parameter.
+  Use when users need to click from a summary view into a per-item detail face.
+  Triggers on: 'drill down', 'click through', 'detail page', 'per-item face',
+  'link to detail', 'cross-face navigation'. Do NOT use for filtering within
+  the same face (use filter-bar-with-variables). Do NOT use for tabs within a
+  single face (use the tabs layout).
+metadata:
+  author: fivetran
+---
+
+# Drill-Down Link
+
+Two faces wired together: a *source* face whose chart elements are clickable
+links, and a *target* face that receives the clicked value as a URL parameter
+and filters its queries accordingly.
+
+The source uses `link:` on a chart (channel placeholder substitution) or
+`link:` on a table column (per-row URL). The target reads the URL parameter
+via a `variables:` entry with `input: text`.
+
+## When to reach for this
+
+- Users need to click from a ranking or list into a per-item detail view
+- The detail content is rich enough to justify its own face (not just a tooltip)
+- The linking dimension is a natural identifier (region, product, customer ID)
+
+## When NOT to use this
+
+- Filtering within the same face → `filter-bar-with-variables`
+- Show/hide sections → tabs layout
+- Simple tooltip detail → hover tooltips work automatically, no extra YAML
+
+## The pattern — source face
+
+```yaml
+charts:
+  region_bars:
+    type: bar
+    query: revenue_by_region
+    x: region
+    y: revenue
+    title: Revenue by Region — click to drill
+    link: "/region-detail?region={{ x }}"   # {{ x }} = clicked bar's region
+```
+
+For tables, use `link:` at the chart root (applies to all cells) or per-column
+in `style.columns` (overrides the root for that column):
+
+```yaml
+charts:
+  customers_table:
+    type: table
+    query: top_customers
+    link: "/customer-detail?id={{ customer_id }}"   # default for all cells
+    style:
+      columns:
+        customer_name:
+          label: Customer
+          # inherits chart-root link
+        status:
+          label: Status
+          link: "/status-detail?status={{ status }}"   # overrides root for this column
+```
+
+## The pattern — target face
+
+```yaml
+variables:
+  region:
+    input: text            # populated from ?region= query param
+    default: "North"       # fallback when opened standalone
+
+queries:
+  region_detail:
+    sql: SELECT * FROM orders WHERE {{ filter('region', region) }}
+```
+
+See `examples/drill-down-link.yml` for the source face worked example.
+
+## Variations
+
+| Variation | YAML knob | When |
+|---|---|---|
+| Path segment | `link: "/detail/{{ x }}"` | Clean URLs, server-side routing |
+| Query param | `link: "/detail?id={{ x }}"` | Multiple params, easier debugging |
+| Table cell link | `link:` on column in `style.columns` | Per-row links in a table |
+| In-page filter | `link: "?var={{ x }}"` | Update a variable without navigation |
+| External link | `link: "https://external.com/{{ x }}"` | Link out to another system |
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Using `{{ color }}` placeholder on a chart with no color channel | Compile error: `link template references channel 'color' but chart has no 'color' encoding assigned` | Use only the chart's mapped channels: `x`, `y`, `color`, `theta` |
+| Target face has no matching variable | Parameter ignored, shows all data | Add a `variables:` entry on the target with the same name |
+| Using `href:` instead of `link:` | Compile error: `'href:' was renamed to 'link:'` | Use `link:` on all chart types |
+
+## Worked example
+
+See `examples/drill-down-link.yml` — the source face: a bar chart with
+`link:` that passes the clicked region to a detail face. Inline data, no
+warehouse required. The target face is documented in the body above — author
+it as a separate YAML file in the same `faces/` directory.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/drill-down-link/examples/drill-down-link.yml

@@ -0,0 +1,27 @@
+title: Revenue by Region
+description: >
+  Drill-down link pattern — source face. Each bar links to a per-region detail
+  face via link. The {{ x }} placeholder is replaced with the clicked region.
+
+queries:
+  by_region:
+    description: Revenue totals by region, pre-ranked
+    columns: [region, revenue, orders]
+    values:
+      - [North, 85000, 320]
+      - [East,  71000, 268]
+      - [South, 62000, 241]
+      - [West,  54000, 198]
+
+charts:
+  region_bars:
+    description: Clickable bar chart — each bar links to the region detail face
+    type: bar
+    query: by_region
+    x: region
+    y: revenue
+    title: Revenue by Region — click to drill
+    link: "/region-detail?region={{ x }}"
+
+rows:
+  - region_bars

dataface/ai/skills/faceted-small-multiples/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: faceted-small-multiples
+kind: pattern
+description: >
+  Pattern for showing the same metric sliced by a categorical dimension —
+  either as one multi-series chart (color encoding) or as N side-by-side
+  charts (manual small multiples). Use when comparing a trend or distribution
+  across segments. Triggers on: 'by segment', 'by region', 'by category',
+  'small multiples', 'faceted', 'breakdown', 'compare across groups',
+  'stacked area'. Use color encoding for ≤5 segments in one chart; use manual
+  multiples when segments need separate y-scales or spatial separation. Do NOT
+  use for aggregate totals (use kpi-row or two-by-two-grid-overview). Do NOT
+  use for two-series comparison (use before-after-comparison).
+metadata:
+  author: fivetran
+---
+
+# Faceted Small Multiples
+
+Two approaches for showing the same metric broken down by a category:
+
+**Option A — Color encoding (one chart):** Add `color: segment_col` to any
+chart. Dataface renders one series per segment value, with a legend. Best for
+≤5 segments, same y-scale.
+
+**Option B — Manual multiples (side-by-side charts):** Author N separate
+charts — one per segment — and arrange them in `cols:` or a `grid:`. Best
+when segments need independent y-scales or when you want spatial separation.
+
+## When to reach for this
+
+- "Show me revenue by region across months" (time × segment)
+- "Compare the distribution of orders across product categories" (category × count)
+- Segments are the primary lens; aggregate total is secondary
+
+## When NOT to use this
+
+- Two series only → `before-after-comparison`
+- Composition (parts add to 100%) → stacked area (`type: area` + `color:`)
+- More than 8 segments → group the long tail into "Other" in SQL
+
+## The pattern — Option A (color encoding)
+
+```yaml
+queries:
+  revenue_by_segment:
+    sql: |
+      SELECT month, region, SUM(revenue) AS revenue
+      FROM orders
+      GROUP BY month, region
+      ORDER BY month, region
+
+charts:
+  region_trend:
+    type: line
+    query: revenue_by_segment
+    x: month
+    y: revenue
+    color: region            # one series per region value
+    title: Revenue by Region
+```
+
+## The pattern — Option B (manual multiples)
+
+```yaml
+queries:
+  east_data:
+    sql: SELECT month, SUM(revenue) AS revenue FROM orders WHERE region='East' GROUP BY 1
+  west_data:
+    sql: SELECT month, SUM(revenue) AS revenue FROM orders WHERE region='West' GROUP BY 1
+
+charts:
+  east_chart:
+    type: line
+    query: east_data
+    x: month
+    y: revenue
+    title: East
+  west_chart:
+    type: line
+    query: west_data
+    x: month
+    y: revenue
+    title: West
+
+rows:
+  - cols: [east_chart, west_chart]   # same visual encoding, side by side
+```
+
+See `examples/faceted-small-multiples.yml` for the worked example (Option A).
+
+## Variations
+
+| Variation | YAML knob | When |
+|---|---|---|
+| Stacked area | `type: area` + `color:` | Show composition — parts of a whole over time |
+| Side-by-side bar | `type: bar` + `color:` | Grouped bars per category |
+| Manual N-up | N charts in a `cols:` row | Independent scales per segment |
+| Grid layout | `grid: columns: 24, col_span: 8` | 3+ multiples in a row |
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Too many color segments (>8) | Legend overflows, colors repeat | Limit to top-N in SQL + "Other" bucket |
+| Stacked area with `color:` but no GROUP BY | Wrong aggregation, chart errors | Ensure one row per (x, color) combination |
+| Manual multiples with different y-scales | Misleading comparisons | Use same y-axis domain, or make the difference visible in chart titles |
+
+## Worked example
+
+See `examples/faceted-small-multiples.yml` — monthly signups by channel using
+color encoding (Option A). Inline data, no warehouse required.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/faceted-small-multiples/examples/faceted-small-multiples.yml

@@ -0,0 +1,33 @@
+title: Signups by Channel
+description: Faceted small multiples pattern — one series per segment via color encoding
+
+queries:
+  signups_by_channel:
+    description: Monthly signups broken down by acquisition channel
+    columns: [month, channel, signups]
+    values:
+      - ["2026-01-01", Organic,  90]
+      - ["2026-01-01", Paid,     40]
+      - ["2026-01-01", Partner,  18]
+      - ["2026-02-01", Organic, 105]
+      - ["2026-02-01", Paid,     48]
+      - ["2026-02-01", Partner,  22]
+      - ["2026-03-01", Organic, 118]
+      - ["2026-03-01", Paid,     52]
+      - ["2026-03-01", Partner,  29]
+      - ["2026-04-01", Organic, 134]
+      - ["2026-04-01", Paid,     58]
+      - ["2026-04-01", Partner,  34]
+
+charts:
+  signups_trend:
+    description: Signup trend faceted by channel — one colored series per channel
+    type: area
+    query: signups_by_channel
+    x: month
+    y: signups
+    color: channel
+    title: Monthly Signups by Channel
+
+rows:
+  - signups_trend

dataface/ai/skills/filter-bar-with-variables/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: filter-bar-with-variables
+kind: pattern
+description: >
+  Pattern for interactive dashboards with dropdown/date/numeric filter controls
+  wired into queries via Jinja variable substitution. Use when users need to
+  slice data by dimension, date range, or threshold without editing YAML.
+  Triggers on: 'filter', 'dropdown', 'date range', 'interactive', 'variable',
+  'select', 'picker', 'parameterized'. Variables render as UI controls above
+  the charts. Do NOT use for drill-through navigation between faces (use
+  drill-down-link). Do NOT use when all data fits on one chart without
+  filtering.
+metadata:
+  author: fivetran
+---
+
+# Filter Bar with Variables
+
+Variables add interactive controls to a face. Each `variables:` entry renders
+a UI widget (select, date picker, number slider). Queries reference variables
+with `{{ var_name }}` Jinja placeholders — Dataface substitutes the current
+widget value at query time.
+
+## When to reach for this
+
+- Users need to slice the data by region, category, time window, or threshold
+- The same face serves multiple audiences who want different views
+- Query results would be too large without a default filter
+
+## When NOT to use this
+
+- Cross-face navigation → `drill-down-link`
+- Static content, no user controls needed
+
+## The pattern
+
+```yaml
+variables:
+  region:
+    label: Region
+    description: Filter all charts to this region
+    options:
+      static: [North, South, East, West]
+
+  date_range:
+    label: Date Range
+    input: daterange
+    column: orders.order_date
+    default: ["2025-01-01", "2025-12-31"]
+
+queries:
+  monthly:
+    description: Monthly revenue filtered by region and date window
+    sql: |
+      SELECT DATE_TRUNC('month', order_date) AS month,
+             SUM(revenue) AS revenue
+      FROM orders
+      WHERE {{ filter('region', region) }}
+        AND {{ filter_date_range('order_date', date_range) }}
+      GROUP BY 1
+      ORDER BY 1
+```
+
+See `examples/filter-bar-with-variables.yml` for the worked example.
+
+## Variable input types
+
+| Input | YAML | Widget |
+|---|---|---|
+| Dropdown (static list) | `options: static: [A, B, C]` | Select element |
+| Date range | `input: daterange` | Two date pickers |
+| Single date | `input: date` | One date picker |
+| Numeric input | `input: number` | Free numeric entry |
+| Range slider | `input: slider` (or `range`), `min:`, `max:`, `step:` | Bounded numeric range |
+| Free text | `input: text` | Text input |
+
+## Filtering helpers in SQL
+
+| Helper | Use for |
+|---|---|
+| `{{ filter('col', var) }}` | Single-value dropdown — emits `col = 'val'` or `1=1` when unset |
+| `{{ filter_date_range('col', date_range) }}` | Date range variable |
+| `{{ filter('col', var, '>=') }}` | Numeric threshold with operator |
+
+Always use these helpers — never write `WHERE col = '{{ var }}'` directly. The
+helpers are null-safe (emit `1=1` when the variable is unset) and handle quoting
+correctly.
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Variable name contains a hyphen | Jinja can't parse `{{ my-var }}` | Use underscores: `my_var` |
+| No `default:` on a required variable | Blank widget, query may fail | Add a sensible `default:` value |
+| Scoping variables globally but only one chart needs them | Re-queries all charts | Nest variables + queries + charts in a nested board |
+
+## Worked example
+
+See `examples/filter-bar-with-variables.yml` — region dropdown and date
+pickers wired to a sales query. Uses inline data to compile without a
+warehouse; swap `columns/values` for `sql:` when connecting to a live source.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/filter-bar-with-variables/examples/filter-bar-with-variables.yml

@@ -0,0 +1,49 @@
+title: Sales Dashboard with Filters
+description: |
+  Filter-bar pattern — region dropdown and date controls wired to queries. Inline data used here; in production, replace with sql: + WHERE {{ filter(...) }}.
+
+variables:
+  region:
+    label: Region
+    description: Filter to a single region, or leave blank for all
+    options:
+      static:
+        - North
+        - South
+        - East
+        - West
+  start_date:
+    label: Start Date
+    input: date
+    default: "2025-07-01"
+  end_date:
+    label: End Date
+    input: date
+    default: "2025-12-31"
+queries:
+  monthly_revenue:
+    description: Monthly revenue — replace with sql and {{ filter }} for a live source
+    columns:
+      - month
+      - region
+      - revenue
+    values:
+      - ['2025-07-01', 'North', 32000]
+      - ['2025-08-01', 'North', 35000]
+      - ['2025-09-01', 'North', 38000]
+      - ['2025-07-01', 'South', 21000]
+      - ['2025-08-01', 'South', 23000]
+      - ['2025-09-01', 'South', 26000]
+charts:
+  revenue_by_month:
+    description: Monthly revenue trend by region
+    type: bar
+    query: monthly_revenue
+    x: month
+    y: revenue
+    color: region
+    title: Monthly Revenue by Region
+    style:
+      stack: zero
+rows:
+  - revenue_by_month