Stat

The stat widget displays a single scalar value — one large number with an optional unit. It is the right choice whenever you want to surface a KPI at a glance.

Use it for:

• Total user count, total events, total revenue
• Averages (average session duration, average score)
• Conversion rates and percentages
• Any single-number metric

---

Query requirements

A stat widget must receive exactly one row with one column.

Caution

Do not use GROUP BY in a stat query. GROUP BY returns multiple rows — the stat widget only reads the first one and the result will be misleading.

To filter by a category (e.g. only one country or platform), put the filter in the WHERE clause — do not SELECT the category column.

Simple mode (recommended)

Select

count() AS value

Filters

WHERE name = 'app_started' AND country = 'France'

What NOT to do

-- Wrong: two columns + GROUP BY → multiple rows
SELECT country, count() AS count
FROM {table}
WHERE country = 'France'
GROUP BY country

---

Percentage stat

To display a ratio as a percentage (e.g. “what % of users who started level 1 completed level 5?”), return two columns: a value column (the numerator) and a total column (the denominator). The frontend computes value / total and renders it as a percentage.

Simple mode (recommended)

Select

uniqExactIf(identity, name = 'level_5_completed') AS value,
uniqExactIf(identity, name = 'level_1_started')   AS total

Filters

WHERE name IN ('level_1_started', 'level_5_completed')

Set Display format to percent and Unit to %.

Column name matching rules:

• The value column must match one of: value, count, amount, sum, qty, val
• The total column must match one of: total, base, all, records, denominator

Tip

The two-column approach is preferred over pre-computing the ratio in SQL — it avoids division-by-zero and keeps the query readable.

---

Common examples

Total unique users (simple mode)

Select: uniqExact(identity) AS value
Filters: WHERE name = 'app_started'

---

Total sessions (simple mode)

Select: count() AS value
Filters: WHERE name = 'app_started'

---

Average session duration — requires a subquery, use full query mode

SELECT formatReadableTimeDelta(avg(duration_minutes) * 60) AS value
FROM (
    SELECT toFloat64((last_event - first_event) / 60) AS duration_minutes
    FROM (
        SELECT
            session_id,
            MIN(timestamp) AS first_event,
            MAX(timestamp) AS last_event,
            minIf(timestamp, name = 'app_started') AS app_started_ts
        FROM {table}
        GROUP BY session_id
    )
    WHERE app_started_ts = first_event
)

---

Conversion rate: level 1 → level 5 (simple mode)

Select:

uniqExactIf(identity, name = 'level_5_completed') AS value,
uniqExactIf(identity, name = 'level_1_started')   AS total

Filters: WHERE name IN ('level_1_started', 'level_5_completed')
Display format: percent — Unit: %