Widgets overview

Dashboards in Vortex are built from widgets — individual panels that each run a ClickHouse query against your events and display the result as a chart, number, or table.

Each widget is independent: it has its own query, its own visualization type, and its own display settings. You can mix and match types freely on the same dashboard.

Widget types

Stat

A single KPI number. Best for totals, averages, conversion rates.

Learn more →

Line chart

Trends over time. Supports multiple series on the same chart.

Learn more →

Bar chart

Compare categories side by side — platforms, versions, countries.

Learn more →

Pie chart

Proportional share across a small number of categories.

Learn more →

Geo map

Any metric broken down by country on an interactive world map.

Learn more →

Table

Multi-column tabular data for detailed breakdowns.

Learn more →

---

Display settings

Every widget has two optional display settings that control how values are formatted — independent of the underlying query.

Display format

Value	Behaviour
None (default)	Values are displayed as-is
Percent	The frontend divides each value by the grand total and appends a % sign

Use percent mode whenever you want to show shares, proportions, or distributions. Your query returns raw counts; the percentage calculation is handled automatically.

Unit

Appends or prepends a symbol to every displayed number. Purely cosmetic — does not affect the query result.

Value	Symbol	Use when
none	—	Default, no symbol
%	%	Percentage values (combine with percent display format, or pre-computed ratios)
$	$	USD revenue, cost, price
€	€	Euro amounts
£	£	GBP amounts
¥	¥	JPY / CNY amounts
custom	your text	Any other unit — set a custom suffix such as ms, km, req/s

---

Column naming conventions

The widget renderer auto-detects which column is the value axis and which is the label axis based on the column alias you use in your SELECT.

Value columns — use one of these aliases for the numeric column your chart should measure: count, value, total, total_records

Label columns — use a descriptive name that reflects the dimension: platform, country, date, name, version, …

-- Good: clear value and label aliases
SELECT platform, count() AS count
FROM {table}
WHERE name = 'app_started'
GROUP BY platform
ORDER BY count DESC

---

Data schema

All events are stored in a single ClickHouse table. Every widget queries this table.

Column	Type	Description
name	String	Event name, e.g. app_started, level_completed
identity	String	Unique user / player identifier (UUID)
session_id	String	Session identifier (UUID)
value	JSON	Event payload — structure varies per event
app_version	String	Application version, e.g. 1.7.8
platform	String	Platform, e.g. steam, ios, android
country	String	Country name, e.g. France
region	String	Region name
custom	JSON	Custom metadata attached via the SDK
timestamp	DateTime	Event timestamp

Access nested JSON fields with dot notation: value.screen, custom.user_tier.