@oxy-hq/cli 0.8.0 → 0.10.0

package/skills/oxy-data-apps/references/quick-reference.md

@@ -0,0 +1,171 @@
+# Data App quick reference
+
+Field-by-field reference for `.app.yml`. The why and the traps live in
+[SKILL.md](../SKILL.md); this file is for looking things up.
+
+## Top level
+
+| Key | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `title` | string | no | Display name in listings. Unset → humanized filename. |
+| `description` | string | no | Free text. |
+| `published` | bool | no | Default `false` = hidden from the sidebar (still in the IDE). |
+| `controls` | list | no | Top-level control declarations (items use `type:`). |
+| `tasks` | list | **yes** (≥ 1) | Data producers. |
+| `display` | list | **yes** (≥ 1) | Rendered blocks, top to bottom. |
+
+No other key is accepted. Omit `name:` — the filename is the name, and
+`oxyc validate` reports `name` as unknown.
+
+## Task fields (all types)
+
+| Key | Notes |
+| --- | --- |
+| `name` | Unique in the app. Letter first; letters, digits, underscores. |
+| `type` | `execute_sql`, `semantic_query` (use these); `workflow`, `formatter`, `conditional`, `loop_sequential`, `http_request`, `omni_query`, `looker_query` are accepted; `agent` and `airway` fail at run time. |
+| `mode` | `client` (default) or `server`. Forced to `server` unless the task is inline `execute_sql` on a local DuckDB. |
+| `cache` | Optional `{ enabled, path }`. Rarely needed in an app. |
+
+### `execute_sql`
+
+| Key | Required | Notes |
+| --- | --- | --- |
+| `database` | yes | A `config.yml` database name. Checked by `oxy validate`. |
+| `sql_query` | one of | Inline SQL. Jinja: `{{ controls.x }}` and friends. |
+| `sql_file` | one of | Workspace-relative `.sql` path. Rendered with the same Jinja; always server-side. |
+| `variables` | no | Map of string → string, available to the SQL template. |
+| `dry_run_limit` | no | ≥ 1. |
+| `export` | no | `{ path, format: sql\|csv\|json\|txt\|docx }` — an automation feature; not needed in apps. |
+
+Rows returned: at most 10,000.
+
+### `semantic_query`
+
+| Key | Notes |
+| --- | --- |
+| `topic` | Topic name from a `.topic.yml`. |
+| `measures` | `[view.measure, …]` |
+| `dimensions` | `[view.dimension, …]` |
+| `time_dimensions` | `[{ dimension: view.field, granularity: year\|quarter\|month\|week\|day\|hour\|minute\|second }]` |
+| `filters` | `[{ field, op, … }]` — see below |
+| `orders` | `[{ field, direction: asc\|desc }]` |
+| `limit`, `offset` | integers |
+| `variables` | map |
+
+Filter ops:
+
+| `op` | Extra keys |
+| --- | --- |
+| `eq`, `neq`, `gt`, `gte`, `lt`, `lte` | `value` |
+| `in`, `not_in` | `values: [...]` |
+| `in_date_range`, `not_in_date_range` | `from`, `to` |
+
+Output columns: `view__field`; with granularity, `view__field__<granularity>`.
+Controls are **not** rendered into any `semantic_query` field.
+
+### `workflow` (runs an automation)
+
+| Key | Notes |
+| --- | --- |
+| `src` | Path to an `.automation.yml` (legacy `.procedure.yml` still works). Don't point it at a `.workflow.yml` — that extension is no longer a recognised automation file. |
+| `variables` | Map passed to the automation. |
+
+Its result reaches the app as one text value, so displays cannot address its
+inner steps.
+
+## Displays
+
+| `type` | Required | Optional |
+| --- | --- | --- |
+| `markdown` | `content` | — |
+| `table` | `data` | `title`, `formats: { column: currency\|percent\|number }` |
+| `line_chart` | `data`, `x`, `y` | `title`, `series`, `x_axis_label`, `y_axis_label`, `y_format` |
+| `bar_chart` | `data`, `x`, `y` | `title`, `series`, `y_format` |
+| `pie_chart` | `data`, `name`, `value` | `title`, `value_format` |
+| `row` | `children` (≥ 1 display) | `columns` (≥ 1; default = number of children) |
+| `control` | `name`, `control_type` | `label`, `options` or `source`, `default` |
+| `controls` | `items` (control objects using `type:`) | — |
+
+Formats: `currency` (USD), `percent` (input already 0–100), `number`
+(thousands separators). Unset → default numeric formatting.
+
+`data:` takes a task name. `markdown` `content` is a template over task
+results: `{{ task_name }}` inserts a text result; a table result renders as a
+JSON code block.
+
+## Controls
+
+| Field | Required | Applies to | Notes |
+| --- | --- | --- | --- |
+| `name` | yes | all | Read as `{{ controls.<name> }}`. |
+| `control_type` | yes (inline `- type: control`) | all | `select` \| `date` \| `toggle` |
+| `type` | yes (top-level `controls:` and `controls.items`) | all | same values |
+| `label` | no | all | Defaults to `name`. |
+| `default` | no | all | May be Jinja, rendered once at load: `"{{ now(fmt='%Y-%m-%d') }}"`. |
+| `options` | no | `select` | Static list; entries may be Jinja too. |
+| `source` | no | `select` | Task name; its first column fills the dropdown. Use instead of `options`. |
+
+Value types: `select` → string, `date` → `YYYY-MM-DD` string, `toggle` →
+boolean. A viewer's empty value falls back to `default`; a value for an
+undeclared control is dropped.
+
+### Jinja the browser can run
+
+| Form | Effect |
+| --- | --- |
+| `{{ controls.x }}` | raw value (single quotes doubled) |
+| `{{ controls.x \| sqlquote }}` | `'value'` with embedded quotes escaped |
+| `{{ controls.x \| default('v') }}` | value, or `v` when unset |
+| `{% if controls.x %}…{% endif %}` | include the body when truthy |
+
+Anything else runs on the server instead (full Jinja, `sqlquote` included).
+
+## SQL dialect cheatsheet
+
+| Dialect | Month bucket | Std-dev | Notes |
+| --- | --- | --- | --- |
+| BigQuery | `DATE_TRUNC(col, MONTH)` | `STDDEV(col)` | backtick identifiers; `DATE_ADD(d, INTERVAL 1 DAY)` |
+| Snowflake | `DATE_TRUNC('month', col)` | `STDDEV(col)` | `"col"` identifiers |
+| Postgres | `DATE_TRUNC('month', col)` | `STDDEV(col)` | `x::date` works here only |
+| DuckDB | `DATE_TRUNC('month', col)` | `STDDEV(col)` | `INTERVAL '1 day'` |
+| ClickHouse | `toStartOfMonth(col)` | `stddevPop(col)` | functions are case-sensitive |
+
+`CAST(x AS DATE)` is the portable cast.
+
+## Profiling query
+
+Run once per candidate table before choosing a trend or a ranking. Substitute
+real expressions from the table or view — never guess column names.
+
+```sql
+SELECT
+  COUNT(*)                                     AS row_count,
+  COUNT(DISTINCT <entity_expr>)                AS entity_count,
+  MIN(<time_expr>)                             AS min_date,
+  MAX(<time_expr>)                             AS max_date,
+  COUNT(DISTINCT DATE_TRUNC('month', <time_expr>)) AS month_count,
+  MIN(<measure_expr>)                          AS min_val,
+  MAX(<measure_expr>)                          AS max_val,
+  STDDEV(<measure_expr>)                       AS measure_stddev
+FROM <table>
+```
+
+Worth charting when `row_count ≥ 100`, `month_count ≥ 3` (for a trend),
+`measure_stddev > 0` (not a flat line), and `entity_count` between 5 and 500
+(for a top-N). If the query fails, simplify once (drop `STDDEV`, swap the date
+function for the dialect's); if it fails again, skip that chart.
+
+## Checklist
+
+- [ ] `oxyc validate --file <app>` and `oxy validate --file <app>` pass
+- [ ] No top-level `name:`; `published:` set as intended
+- [ ] Task names unique; every display `data:` names a real task
+- [ ] Chart columns match the task's output columns exactly (`view__field`,
+      `__<granularity>` for semantic queries)
+- [ ] No IDs on axes or pie labels
+- [ ] Inline `- type: control` blocks use `control_type:`; no controls inside a `row`
+- [ ] Every `{{ controls.x }}` matches a declared control; every `source:` names a task
+- [ ] Strings and dates go through `| sqlquote` with no extra quotes
+- [ ] No `type: agent` or `type: airway` tasks; no `data: task.step` references
+- [ ] Each task's SQL has been run once against the real database
+- [ ] The app opens with every block populated, and each control re-runs its tasks

package/skills/oxy-data-apps/templates/dashboard-with-controls.app.yml

@@ -0,0 +1,128 @@
+# Dashboard with interactive controls — copy, rename to <your_app>.app.yml, customize.
+#
+# Shows all three control kinds, a data-driven dropdown (`source:`), a row
+# layout, and control values injected into SQL.
+#
+# As written, every task reads a CSV through a local DuckDB database, so the
+# browser can re-run the SQL itself when a control changes (client mode).
+#   - `database: local` must be a DuckDB entry in your config.yml; `'sales.csv'`
+#     is a file in that database's dataset directory.
+#   - For a warehouse (Postgres, Snowflake, BigQuery, ClickHouse…), change
+#     `database:` and the FROM clauses. Those tasks run on the server
+#     automatically; adding `mode: server` makes that explicit.
+#   - Only {{ controls.x }}, {{ controls.x | sqlquote }},
+#     {{ controls.x | default('v') }} and {% if controls.x %}…{% endif %} run in the
+#     browser. Anything richer still works, on the server.
+
+title: Sales Explorer
+description: |
+  Sales filtered live by region, start date, and a holidays-only toggle.
+  Every chart and table re-runs when a control changes.
+published: false # flip to true to show the app in the sidebar
+
+tasks:
+  # Feeds the `region` dropdown: the first column becomes the option list.
+  # The 'All' sentinel row lets a viewer clear the filter.
+  - name: region_list
+    type: execute_sql
+    database: local
+    sql_query: |
+      SELECT region
+      FROM (
+        SELECT 'All' AS region, 0 AS sort_key
+        UNION ALL
+        SELECT DISTINCT region, 1 AS sort_key FROM 'sales.csv'
+      ) AS options
+      ORDER BY sort_key, region
+
+  - name: revenue_by_category
+    type: execute_sql
+    database: local
+    sql_query: |
+      SELECT category, SUM(revenue) AS total_revenue
+      FROM 'sales.csv'
+      WHERE sale_date >= {{ controls.start_date | sqlquote }}
+        AND ({{ controls.region | sqlquote }} = 'All'
+             OR region = {{ controls.region | sqlquote }})
+        {% if controls.holidays_only %}AND period = 'Holiday'{% endif %}
+      GROUP BY category
+      ORDER BY total_revenue DESC
+
+  - name: revenue_by_region
+    type: execute_sql
+    database: local
+    sql_query: |
+      SELECT region, SUM(revenue) AS total_revenue
+      FROM 'sales.csv'
+      WHERE sale_date >= {{ controls.start_date | sqlquote }}
+        AND ({{ controls.region | sqlquote }} = 'All'
+             OR region = {{ controls.region | sqlquote }})
+        {% if controls.holidays_only %}AND period = 'Holiday'{% endif %}
+      GROUP BY region
+      ORDER BY total_revenue DESC
+
+  - name: sales_detail
+    type: execute_sql
+    database: local
+    sql_query: |
+      SELECT region, category, period, sale_date, revenue
+      FROM 'sales.csv'
+      WHERE sale_date >= {{ controls.start_date | sqlquote }}
+        AND ({{ controls.region | sqlquote }} = 'All'
+             OR region = {{ controls.region | sqlquote }})
+        {% if controls.holidays_only %}AND period = 'Holiday'{% endif %}
+      ORDER BY sale_date DESC
+      LIMIT 500
+
+display:
+  # Controls bar: inline `- type: control` blocks at the top level of `display:`.
+  # The kind is `control_type:`, NOT `type:`. Never put a control inside a `row`.
+  - type: control
+    name: region
+    control_type: select
+    label: Region
+    source: region_list # data-driven dropdown (instead of static `options:`)
+    default: All
+
+  - type: control
+    name: start_date
+    control_type: date
+    label: From date
+    default: "2024-01-01"
+
+  - type: control
+    name: holidays_only
+    control_type: toggle
+    label: Holidays only
+    default: false
+
+  - type: markdown
+    content: |
+      # Sales Explorer
+
+      Filter by **region**, **start date**, and **holiday periods** with the
+      controls above. Charts and tables update automatically.
+
+  # Two charts side by side
+  - type: row
+    columns: 2
+    children:
+      - type: bar_chart
+        title: Revenue by category
+        data: revenue_by_category
+        x: category
+        y: total_revenue
+        y_format: currency
+
+      - type: pie_chart
+        title: Revenue by region
+        data: revenue_by_region
+        name: region
+        value: total_revenue
+        value_format: currency
+
+  - type: table
+    title: Filtered sales (latest 500)
+    data: sales_detail
+    formats:
+      revenue: currency

package/skills/oxy-data-apps/templates/simple-dashboard.app.yml

@@ -0,0 +1,102 @@
+# Simple dashboard — copy, rename to <your_app>.app.yml, and customize.
+#
+# The app's name is its filename; there is no `name:` key.
+# Customize:
+#   - `database:` must be a database name from your config.yml
+#   - replace `orders`, `order_date`, `category` and `amount` with your table and columns
+#   - the SQL below is Postgres / DuckDB / Snowflake dialect; for BigQuery use
+#     DATE_TRUNC(order_date, MONTH), for ClickHouse toStartOfMonth(order_date)
+
+title: Orders Overview
+description: |
+  Key order metrics, the monthly trend, and a breakdown by category.
+published: false # flip to true to show the app in the sidebar
+
+tasks:
+  # One row of headline numbers
+  - name: summary_metrics
+    type: execute_sql
+    database: warehouse
+    sql_query: |
+      SELECT
+        COUNT(*)                 AS order_count,
+        COUNT(DISTINCT category) AS category_count,
+        ROUND(SUM(amount), 2)    AS total_amount,
+        ROUND(AVG(amount), 2)    AS avg_amount
+      FROM orders
+      WHERE order_date >= '2024-01-01'
+
+  # Trend over time
+  - name: monthly_trend
+    type: execute_sql
+    database: warehouse
+    sql_query: |
+      SELECT
+        DATE_TRUNC('month', order_date) AS month,
+        COUNT(*)                        AS order_count,
+        ROUND(SUM(amount), 2)           AS total_amount
+      FROM orders
+      WHERE order_date >= '2024-01-01'
+      GROUP BY 1
+      ORDER BY 1
+
+  # Breakdown by category
+  - name: by_category
+    type: execute_sql
+    database: warehouse
+    sql_query: |
+      SELECT
+        category,
+        COUNT(*)              AS order_count,
+        ROUND(SUM(amount), 2) AS total_amount
+      FROM orders
+      WHERE order_date >= '2024-01-01'
+      GROUP BY category
+      ORDER BY total_amount DESC
+
+display:
+  - type: markdown
+    content: |
+      # Orders Overview
+
+      Key metrics since January 2024.
+
+  - type: table
+    title: Summary
+    data: summary_metrics
+    formats:
+      total_amount: currency
+      avg_amount: currency
+      order_count: number
+
+  - type: line_chart
+    title: Monthly total
+    data: monthly_trend
+    x: month
+    y: total_amount
+    x_axis_label: Month
+    y_axis_label: Amount
+    y_format: currency
+
+  - type: row
+    columns: 2
+    children:
+      - type: bar_chart
+        title: By category
+        data: by_category
+        x: category
+        y: total_amount
+        y_format: currency
+
+      - type: pie_chart
+        title: Share by category
+        data: by_category
+        name: category
+        value: total_amount
+        value_format: currency
+
+  - type: table
+    title: Category details
+    data: by_category
+    formats:
+      total_amount: currency