SmashGL Reference

~10 min read

SmashGL (Smash Goal Language) is dashboardSMASHBOARD's goal-first query language for configuring each card. It extends ShopifyQL with additional clauses that control time windows, comparison modes, goal tracking, sparkline smoothing, and visualization rendering.

The Simple tab in the card editor writes SmashGL automatically. This reference is for users who want to write or customise queries directly in the Code tab.

Query Structure

A SmashGL query has two blocks separated by the DEFINE keyword:

-- Intent block: what to measure and how to display it
SMASH <vizType> [<flags>]
[GOAL <variable> <operator>]
WINDOW <period>
[COMPARE <mode>]
[SMOOTH <algorithm>]
[NAME "<label>"]
-- Data body: where the data comes from
DEFINE <variable>
  FROM <source>
  SHOW <metrics>
  [GROUP BY <dimension>]
  [ORDER BY <field> ASC|DESC]
  [LIMIT <n>]

SMASH must be the first non-empty line. DEFINE marks the boundary between the intent block and the data body. FROM and SHOW are required inside DEFINE.

SMASH — Visualization and Flags

The opening clause. Declares the visualization type and optional display flags.

SMASH <vizType> [<flag> ...]

vizType

Value	Description
`metric`	Large hero number with OKR goal block and vs-prior comparison pill
`sparkline`	Hero number + delta pill + trend line chart
`chart`	Full-width chart variant (alias for sparkline)
`bar`	Horizontal bar chart with optional goal line
`table`	Ranked rows (used by Top Products)
`gauge`	Arc/dial showing progress toward a goal
`badge`	Simple large-number display

Flags

Optional display features listed on the same line as SMASH. Two modes:

No flags listed → all applicable flags are active by default
Any flag listed → only the listed flags are active

Flag	Description	Requires
`TREND`	Historical sparkline alongside the hero number	`GROUP BY day` in DEFINE block
`FORECAST`	Forward projection pill + dashed sparkline	GOAL + fixed or named window
`ALERT`	RAG pulse on card border keyed to goal status	GOAL
`RISK`	Pace-to-goal indicator: At risk / On pace / Ahead	GOAL + fixed or named window
`GAP`	Gap to goal — value remnant + time remnant	GOAL

Custom ALERT colours — provide exactly 3 hex values (red, amber, green) to override defaults:

ALERT(#ef4444,#f59e0b,#22c55e)

GOAL — Target Tracking

Sets a goal for the card. Optional — without it, the card shows the metric and vs-prior comparison only.

GOAL <variable> <operator>

The <variable> must match the identifier on the DEFINE line.

Relative Goal

The goal is calculated as N% above or below the comparison period's value. Adjusts automatically every period.

GOAL revenue +10%
GOAL returns -5%

Absolute Goal

A fixed target value, regardless of historical performance.

GOAL orders >= 15500
GOAL revenue >= 50000

Supported operators: >=, <=, >, <, =

WINDOW — Time Range

Defines the time period for the current data window. Required.

WINDOW <period>

Syntax	Period
`WINDOW 7d`	Last 7 days (rolling)
`WINDOW 30d`	Last 30 days (rolling)
`WINDOW Nd`	Last N days (rolling)
`WINDOW Nw`	Last N weeks (rolling)
`WINDOW startOfWeek`	From the start of the current calendar week to today
`WINDOW startOfMonth`	From the 1st of the current month to today
`WINDOW startOfQuarter`	From the start of the current quarter to today
`WINDOW startOfYear`	From January 1st to today
`WINDOW 2026-03-01`	From that date to today (rolling from a fixed start)
`WINDOW 2026-03-01 2026-03-15`	Fixed range between two dates

COMPARE — Comparison Mode

Controls which period to compare against for % change calculations. Optional — defaults to previousPeriod.

Value	Comparison period
`previousPeriod`	Equal-length window immediately before the current window (default)
`previousYear`	Same date range, exactly 12 months earlier
`sameDayLastWeek`	Same date range, shifted back 7 days

SMOOTH — Sparkline Smoothing

Applies a smoothing algorithm to the sparkline trend data. Does not affect the headline KPI value. Optional.

Value	Description
`rolling7`	7-day rolling average
`rolling14`	14-day rolling average
`rolling30`	30-day rolling average
`ema7`	Exponential moving average, 7-period span — recent days weighted more
`ema14`	Exponential moving average, 14-period span

NAME — Card Label

Sets the display label shown as the card title on the dashboard. Optional — defaults to the card type name.

NAME "March Revenue"

DEFINE — Data Source

Declares the named variable and the data body that populates it. Required.

DEFINE <variable>
  FROM <source>
  SHOW <metrics>
  [GROUP BY <dimension>]
  [ORDER BY <field> ASC|DESC]
  [LIMIT <n>]

The variable name on the DEFINE line must match the variable in the GOAL clause.

FROM — Data source

Source	Data available
`sales`	Net sales, gross sales, orders, items sold
`sessions`	Online store visitors

SHOW — Metrics

FROM sales:

Field	Type	Description
`net_sales`	Currency	Revenue after discounts, returns, and taxes
`gross_sales`	Currency	Revenue before discounts and returns
`orders`	Integer	Number of orders
`net_items_sold`	Integer	Net quantity of items sold (after returns)

FROM sessions:

Field	Type	Description
`online_store_visitors`	Integer	Unique visitors to the online store

The first metric in SHOW is the primary KPI (hero number). Additional metrics appear as supplementary stats.

AOV: Including both net_sales and orders in SHOW automatically calculates Average Order Value as net_sales ÷ orders.

Complete Examples

Revenue — monthly target, vs. last year

SMASH metric ALERT
GOAL revenue >= 50000
WINDOW startOfMonth
COMPARE previousYear
NAME "March Revenue"
DEFINE revenue
FROM sales
SHOW net_sales, gross_sales

Orders — rolling 30 days, grow 15%

SMASH metric TREND ALERT
GOAL orders +15%
WINDOW 30d
NAME "Orders"
DEFINE orders
FROM sales
SHOW orders

Revenue Trend — sparkline with 7-day smoothing

SMASH sparkline TREND
WINDOW 30d
SMOOTH rolling7
NAME "Revenue Trend"
DEFINE revenue
  FROM sales
  SHOW net_sales
  GROUP BY day
  ORDER BY day ASC

AOV — rolling 30 days, gauge with absolute goal

SMASH gauge
GOAL aov >= 85
WINDOW 30d
NAME "Avg Order Value"
DEFINE aov
FROM sales
SHOW net_sales, orders

AOV is calculated automatically when both net_sales and orders are in SHOW.

Store Sessions — this quarter, all goal indicators

SMASH metric TREND FORECAST ALERT RISK GAP
GOAL sessions >= 10000
WINDOW startOfQuarter
COMPARE previousYear
NAME "Q1 Sessions"
DEFINE sessions
  FROM sessions
  SHOW online_store_visitors
  GROUP BY day

Top Products — last 90 days

SMASH table
WINDOW 90d
NAME "Top Products (90d)"
DEFINE products
  FROM sales
  SHOW gross_sales
  GROUP BY product_title
  ORDER BY gross_sales DESC
  LIMIT 10

BFCM — fixed date range with forecast

SMASH metric ALERT FORECAST GAP
GOAL revenue >= 25000
WINDOW 2026-11-27 2026-11-30
NAME "BFCM Revenue"
DEFINE revenue
FROM sales
SHOW net_sales, orders

SmashGL vs. ShopifyQL

Feature	SmashGL	ShopifyQL
Shopify data tables	✓	✓
`GOAL` clause	✓	✗
`WINDOW` / `COMPARE`	✓	✗
`SMASH` visualization control	✓	✗
Sparkline smoothing (`SMOOTH`)	✓	✗
Embedded in dashboardSMASHBOARD	✓	✗

Validation Rules

A SmashGL query is valid when:

SMASH <vizType> is the first non-empty line
WINDOW is present in the intent block
DEFINE <variable> is present
If GOAL is present, the variable name must match the identifier on the DEFINE line
<vizType> is one of: gauge, badge, chart, bar, metric, sparkline, table

Warnings (query still runs):

FORECAST or RISK with a rolling window → silently ignored
TREND without GROUP BY day → silently ignored
Goal-dependent flags without a GOAL → silently ignored

Next Steps

Was this helpful? Thanks for the feedback!

Still need help?