Build Workflow

The only workflow order that scales

Looky is deterministic when you build in this order. If you invert steps, you get ambiguous failures and slow delivery.

1. Workspace structure and context are correct.
2. Runtime source aliases are defined and valid.
3. Malloy models expose stable, idiomatic query contracts (semantic layer, named views — not ad hoc SQL scattered across viz YAML).
4. Visualizations map query fields to renderers.
5. Dashboards compose validated visualizations.
6. Validate, diff, push, and verify in UI.

The canonical chain inside a workspace

Every Looky workspace is the same four layers, in this dependency order — read your own workspace files in this order whenever you need to debug or extend it:

• runtime/sources.runtime.yml declares source aliases (e.g. an alias ecommerce pointing at a BigQuery dataset, or a Postgres / MySQL connection string).
• content/models/*.malloy defines reusable dimensions, measures, and named queries on top of those source aliases.
• content/visualizations/*.yml binds one model query to one chart/table renderer.
• content/dashboards/*.yml composes visualizations into the final surfaces the audience sees.

Each layer references only the one above it. If a layer fails to validate, fix it before touching anything below — the layers below cannot recover on their own.

One workspace, end to end

The four files below are a complete, working workspace against the public BigQuery ecommerce dataset — the smallest thing worth publishing. Every downstream page elaborates one of these layers.

runtime/sources.runtime.yml:

sources:
  ecommerce:
    name: The Look Ecommerce
    type: bigquery
    project_id: my-gcp-billing-project
    credentials_file: my-workspace-bq.json
    datasets:
      - bigquery-public-data.thelook_ecommerce

content/models/ec_revenue.malloy:

##! experimental.parameters

source: ec_revenue() is ecommerce.table('bigquery-public-data.thelook_ecommerce.order_items') extend {
  dimension: order_month is created_at::date.month
  measure: revenue is sum(sale_price)
  measure: order_count is count(order_id)

  view: kpi is {
    aggregate: revenue, order_count
  }

  view: over_time is {
    group_by: order_month
    aggregate: revenue
    order_by: order_month asc
  }
}

content/visualizations/ec_revenue_kpi.yml and content/visualizations/ec_revenue_over_time_line.yml:

id: ec_revenue_kpi
title: Revenue
query: "models/ec_revenue.malloy::kpi"
type: kpi
mapping:
  value: revenue
format:
  revenue: "$#,##0a"
published: true

id: ec_revenue_over_time_line
title: Revenue over time
query: "models/ec_revenue.malloy::over_time"
type: line
mapping:
  x: order_month
  y: revenue
format:
  revenue: "$#,##0"
published: true

content/dashboards/ec_revenue_overview.yml:

id: ec_revenue_overview
title: "Where is revenue going?"
layout_mode: fluid_grid
published: true
items:
  - visualization: ec_revenue_kpi
  - visualization: ec_revenue_over_time_line
    width: 2

With those files in place, looky validate then looky push puts the dashboard in front of the workspace's users.

Builder loop you should run every day

cd <local_root>/<billing_account_id>/<workspace_slug>
looky status
looky validate
looky diff
looky push
looky list visualizations
looky list dashboards

Run this loop for every meaningful change. It catches structural issues before users see broken dashboards.

Definition of done for a content change

• looky validate has no blocking errors.
• looky diff only shows intended files.
• looky push succeeds on target workspace.
• Dashboard is visible and renders correctly in https://my.looky.studio.