oxy-app-builder

Oxy App Builder

Build Oxy data apps - interactive dashboards that combine data tasks with visualizations. Apps are defined in *.app.yml files.

The mental model: Task -> Output -> Display

Two app models — don't confuse them. This rule builds the declarative *.app.yml app (tasks + displays, rendered by oxy serve --enterprise). The other model is a custom-code (React/Vite) app deployed with oxy publish and identified by an oxy-app.json manifest at the app root. oxy-app.json is the deploy manifest for that path, not an alternative to *.app.yml. See the oxy-app-builder SKILL.md → "Deploying custom-code apps (oxy-app.json)".

App YAML Structure

name: app_name                # snake_case identifier
description: |                # Multi-line description
  What this app does...

# Required: Array of tasks (min 1)
tasks:
  - name: task_name           # Unique, snake_case
    type: execute_sql         # Task type
    database: clickhouse      # Database to query
    sql_query: |              # Inline SQL
      SELECT * FROM table

# Required: Array of displays (min 1)
display:
  - type: table
    title: "Results"
    data: task_name           # Reference task by name

Task Types

1. execute_sql - Direct SQL Execution

- name: sales_by_region
  type: execute_sql
  database: clickhouse        # or: postgres, bigquery, local (DuckDB)
  sql_query: |
    SELECT region, SUM(amount) as total
    FROM sales
    GROUP BY region

Or reference a SQL file:

- name: sales_report
  type: execute_sql
  database: clickhouse
  sql_file: queries/sales_report.sql

2. workflow - Invoke Sub-Workflow

- name: data_prep
  type: workflow
  src: workflows/data_prep.workflow.yml
  variables:
    start_date: "2024-01-01"
    min_threshold: 100

Reference workflow task outputs: workflow_name.inner_task_name

3. semantic_query - Query Semantic Layer

- name: revenue_by_month
  type: semantic_query
  topic: sales_mrr
  dimensions:
    - sales.month
  measures:
    - sales.total_revenue
    - sales.order_count
  filters:
    - field: sales.year
      op: eq
      value: 2024
  orders:
    - field: sales.month
      direction: asc