The visualizer turns a collection into an interactive query builder. Open a collection, select Visualize, and start with Samples to verify the raw events before choosing a chart.
Pick a visualization#
| Visualization | Best for |
|---|---|
| Samples | Inspecting recent raw events and field names |
| Single Line | One metric over time |
| Multi Line | A time series split by a categorical field |
| Stacked Line | Composition over time |
| Cumulative Line | A running total |
| Ratio Line | A numerator divided by a denominator |
| Compare Line | Two filtered populations on the same timeline |
| Single Value | One KPI for the selected period |
| Table | Ranked grouped values |
| Bar Chart | Comparing categories |
| Pie Chart | Showing composition across a small number of categories |
The SQL notebook supports additional output shapes, including funnels. See Run SQL queries.
Configure the query#
Time range#
start and end define the event-time window. You can use relative values such as 7 days ago and now, or a concrete date and time.
GraphJSON interprets the range in the selected IANA time zone. Boundaries are exclusive, so an event exactly equal to the start or end boundary is not included.
Aggregation and metric#
Count counts matching events and does not require a metric.
Other aggregations operate on a numeric field:
- Sum for totals such as revenue
- Avg for means such as average order value
- P25, P50, P75, P90, P95, and P99 for percentiles
If a field does not appear in the metric selector, confirm that recent events send it as a JSON number rather than a formatted string.
Split#
A split groups the result by a string field. For example, split signup counts by plan to get one series per plan.
Choose fields with a manageable number of distinct values. Splitting by a nearly unique value such as request_id produces an unreadable chart and a more expensive query.
Filters#
A filter is [field, operator, value]. Common operators are:
| Operator | Meaning |
|---|---|
= |
Equal to |
≠ |
Not equal to |
includes |
String contains |
excludes |
String does not contain |
> |
Numeric value is greater than |
< |
Numeric value is less than |
Filters inside one group are combined with AND. Separate groups are combined with OR.
For example:
[
[
["event", "=", "checkout_completed"],
["plan", "=", "pro"]
],
[
["event", "=", "subscription_renewed"],
["plan", "=", "pro"]
]
]
means “pro checkouts or pro renewals.”
Granularity#
Granularity controls the time bucket: minute, hour, day, week, or month. Auto chooses a sensible bucket from the selected range.
Use a fixed granularity when a downstream embed or report must stay structurally consistent as its range changes.
Compare#
Compare shifts the same query to an earlier window. For a seven-day chart, 7 days ago compares the current window with the preceding seven days.
The result includes both result and compare_result when comparison is enabled.
A practical sequence#
When building a new metric:
- Start in Samples with a broad time range.
- Confirm the event name, field names, and field types.
- Switch to Single Value or Single Line with Count.
- Add one filter at a time.
- Add a metric and non-count aggregation.
- Add a split or comparison only after the base number is correct.
This makes it much easier to spot whether an empty result comes from missing data, a type mismatch, a time range, or a filter.
Use the Visualization reference for the complete graph-type, aggregation, customization, and export matrix.