Heatmaps
Read a metric across a day-of-week by month calendar grid, where each cell is colored by how high its value is.
When to use it — When you want to spot weekly and seasonal patterns at a glance, such as which weekdays peak or which months run hot.
Where to find it — Pick Heatmap from the chart-type switcher in the embedded Discover editor, or in any tile's chart picker.
Who can use it — Tracer, Weaver, and Luminary. (Lens can view a saved heatmap but cannot edit the query.)
The heatmap turns a date attribute and a single metric into a grid you can read by eye. Rows are days of the week (Mon through Sun), columns are months (Jan through Dec), and the color of each cell tells you how that day-and-month combination compares to the rest of the grid: lighter cells are low, darker cells are high.
Every row that shares the same weekday and month is summed into one cell, so the heatmap is a quick way to see, for example, that Saturdays in November are your busiest cells while Mondays in February are your quietest.
Overview
The heatmap is deliberately simple. It always draws the same fixed grid — seven weekday rows and twelve month columns — and colors each cell on a single hardcoded purple gradient. There are no configuration controls: once you have a date attribute and a metric on the query, the chart renders and reads itself.
Celiq builds the grid by walking every row in your result set, reading the date, working out which weekday and month it falls on, and adding the metric value into that cell. Cells with no data stay light grey. The lightest purple is the lowest non-empty value in the grid and the darkest purple is the highest, so the shading is always relative to the data you are currently looking at.
Exact numbers are not printed inside the cells. To read a value, hover a cell and the tooltip shows the weekday, the month, and the summed value (for example, Sat Nov: 12,480).
When to use it
Reach for a heatmap when the shape of a pattern matters more than precise numbers:
- Weekly rhythm — see which weekdays consistently run high or low across the year.
- Seasonality — see which months light up and which stay quiet.
- Day-and-month hotspots — find the specific combinations (such as Fridays in December) where a metric spikes.
Choose a different chart when you need exact values, a time series with a continuous date axis, or a breakdown by a non-date dimension. A line or area chart is better for trends over a true timeline, and a table is better when readers need the underlying numbers.
Concepts
| Term | What it means in the heatmap |
|---|---|
| Cell | One square in the grid, representing one weekday-and-month combination. |
| Weekday row | One of seven rows, Mon through Sun. The week starts on Monday. |
| Month column | One of twelve columns, Jan through Dec. |
| Aggregation | Every result row that lands on the same weekday and month is summed into that cell. |
| Color scale | A fixed light-to-dark purple gradient. Lightest = the grid's lowest value, darkest = its highest. |
| Empty cell | A weekday-and-month combination with no data, shown in light grey. |
| Low / High legend | A small swatch strip at the bottom-right labelled Low and High that explains the gradient direction. |
Getting started
You need two fields on the query before a heatmap can render:
- A date attribute — the field whose dates are split into weekday and month. If you have not tagged a field as a date, Celiq falls back to the first attribute on the query.
- A metric — the value summed into each cell. If you have not chosen one, Celiq uses the last column in the result.
To open it, run a query in the embedded Discover editor (or open a tile for editing) and select Heatmap from the chart-type switcher. There is nothing else to set up — the heatmap has no settings panel of its own.
Step-by-step
Open Discover and load a query
Open the embedded Discover editor on a reveal that has a date field, or open an existing tile for editing.
Add a date attribute
Put a date field on the query — for example an order date or an event date. This drives the weekday rows and month columns.
Add one metric
Add a single metric, such as a count or a sum. This is the value that fills and colors each cell.
Switch to Heatmap
In the chart-type switcher, choose Heatmap. The grid renders immediately from your current results.
Read the grid by hovering
Darker cells are higher values, lighter cells are lower, and grey cells have no data. Hover any cell to see the weekday, month, and exact summed value in the tooltip.
Examples
Suppose you want to see how order volume moves across days of the week and months of the year. Build a query in Discover with a date attribute and an order-count metric:
SELECT
order_date, -- date attribute → weekday + month
COUNT(*) AS orders -- metric → summed into each cell
FROM orders
GROUP BY order_dateSwitch the result to a heatmap. Celiq takes each order_date, maps it to its weekday (Mon–Sun) and month (Jan–Dec), and sums orders into that cell. If 2,000 orders landed on Saturdays in November across your data, the Sat / Nov cell holds 2,000 and is shaded near the dark end of the gradient; a quiet Mon / Feb cell stays light. Hovering Sat / Nov shows Sat Nov: 2,000.
Because the gradient is relative to the current grid, the same query over a busier date range simply re-shades the cells — the darkest cell is always whatever the current high is.
Best practices
- Bring enough history. A heatmap shines when most weekday-and-month cells have data. A single month of results leaves eleven columns empty.
- Use a metric that sums meaningfully. Counts, totals, and other additive metrics aggregate cleanly into cells. Averages and ratios are summed across rows here, which is usually not what you want.
- Tag your date field as a date. When a field is typed as a date, the heatmap uses it directly instead of falling back to the first attribute.
- Pair it with detail. Use the heatmap to find a hotspot, then drill or switch to a table or line chart to read the exact numbers behind it.
Tips
The week starts on Monday, so the bottom two rows are Sat and Sun — handy for spotting weekend versus weekday patterns at a glance. To read any exact value, just hover the cell; the tooltip carries the full number.
Common mistakes
- Looking for value labels inside the cells. The heatmap never prints numbers on the cells — values live in the hover tooltip only.
- Expecting color or formatting controls. The heatmap has no settings: the purple gradient, the Low/High legend, and the grid layout are all fixed and cannot be changed.
- Using a non-date field as the first attribute. If no field is typed as a date, the heatmap falls back to the first attribute on the query, which may not parse as a date and can leave the grid empty.
- Reading colors across two heatmaps as equivalent. Shading is relative to each grid's own minimum and maximum, so the same purple in two charts can mean very different values.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The chart shows an empty-state placeholder | The query returned no rows | Adjust filters or the date range so the query returns data, then re-run. |
| Message: Select a date attribute and a metric | The query is missing a usable date attribute or a metric | Add a date field and one metric to the query. |
| Message: No date data to display | Rows returned, but none of the date values could be parsed into a valid date | Make sure the date field holds real dates (Celiq reads the first ten characters of the value as the date). |
| Whole grid looks light / no dark cells | The metric values are flat, or only one cell has data | Widen the date range so more cells fill in, or choose a metric with more variation. |
| Many empty grey cells | Your data covers only part of the year or week | Bring in more history so more weekday-and-month combinations have values. |
| Numbers don't appear on the cells | By design — values are shown only in the tooltip | Hover a cell to read its weekday, month, and summed value. |