Gauge

The gauge widget shows one value as a dial, filled relative to a maximum. It is a stat with context — useful when the number only means something against a target, quota, or capacity.

Use it for:

• Progress toward a goal (e.g. monthly active users vs target)
• Quota / capacity usage
• Conversion rate against a benchmark

---

Query requirements

Return exactly one row. Provide the value column (alias it value). Optionally provide a second column matching a max/target pattern — max, target, goal, or limit — to set the dial maximum.

If no maximum column is supplied, the dial maxes out at 1.2× the value so the needle always has headroom.

Value only

Select

uniqExact(identity) AS value

Filters

WHERE name = 'app_started'

Value + target

Select

uniqExact(identity) AS value,
10000               AS target

Filters

WHERE name = 'app_started'

Note

The gauge displays a single scalar — do not use GROUP BY or return multiple rows. Combine with a Unit (e.g. %, $, or a custom min) to label the value.

---

Common examples

Active users vs monthly target

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

---

Conversion rate

Select: round(uniqExactIf(identity, name = 'purchase') * 100.0 / uniqExactIf(identity, name = 'app_started'), 1) AS value, 100 AS max
Filters: WHERE name IN ('purchase', 'app_started') — Unit: %