2D spatial heatmap chart type for SQL/HogQL insights

Feature request

Summary

Add a spatial heatmap chart type to HogQL/SQL insights that renders a 2D grid where:

• The x-axis is mapped to one numeric or categorical column
• The y-axis is mapped to a second numeric or categorical column
• The color intensity of each cell represents a third numeric column (e.g. event count, average, sum)
  This is distinct from the existing TwoDimensionalHeatmap display type, which maps breakdown values against time intervals. The requested feature maps two arbitrary data columns against each other.

---

Problem

When analyzing spatial or coordinate-based event data (e.g. game world positions, physical zones, grid-based maps), users need to visualize where activity is concentrated across two dimensions simultaneously.

Currently:

• The existing 2D heatmap is time-series only (breakdown × time), not suitable for coordinate data.
• SQL insights support ActionsTable, which works but is not visual — users must mentally parse rows of x/y/z values to find hotspots.
• There is no native way to render a data-driven spatial grid in PostHog without exporting to an external tool.
  Example use case: A game server tracks player dwell events with x, y, z coordinates. Grouping events by bucketed x and z coordinates and coloring cells by event count would instantly show where players spend the most time — something a table cannot convey at a glance.

Proposed solution

Add a new display type (e.g. SpatialHeatmap or extend TwoDimensionalHeatmap) for DataVisualizationNode (HogQL insights) that:

1. Accepts a SQL query result with at least 3 columns: two dimension columns and one numeric value column.
2. Renders a grid where:

• Column 1 → x-axis buckets
• Column 2 → y-axis buckets
• Column 3 → cell color intensity (with a configurable color scale, e.g. white → red)

3. Allows the user to configure which column maps to which axis in the chart settings panel.
4. Optionally supports a 4th column for a tooltip label (e.g. exact timestamp, event type).
5. Handles sparse grids gracefully (empty cells rendered as zero / neutral color).

Example query that should drive this chart:

SELECT  
    round(toFloat(properties.x) / 100) * 100   AS x_bucket,  
    round(toFloat(properties.z) / 100) * 100   AS z_bucket,  
    count()                                      AS event_count  
FROM events  
WHERE event IN ('stationary_dwell', 'area_dwell')  
  AND properties.x IS NOT NULL  
  AND properties.z IS NOT NULL  
  AND timestamp >= now() - INTERVAL 90 DAY  
GROUP BY x_bucket, z_bucket  
ORDER BY event_count DESC  
LIMIT 500  

This should render as a grid with x on one axis, z on the other, and cell color driven by event_count.

Why this matters

• Game analytics – player position heatmaps, spawn/death maps, resource gathering zones.
• Physical space analytics – store foot traffic grids, warehouse zone activity.
• Infrastructure monitoring – server × error-type matrix, host × time-of-day grid.
• Any domain with two categorical/bucketed dimensions and a numeric signal.
  The table view works today but doesn't scale visually — a 20×20 coordinate grid is 400 rows in a table and 400 colored cells in a heatmap. The heatmap communicates the pattern instantly.

Acceptance criteria

• New display type available for DataVisualizationNode (HogQL SQL insights)

• User can select which query columns map to x-axis, y-axis, and cell value

• Color scale is configurable (min/max, color ramp)

• Tooltip shows exact cell values on hover

• Empty/missing cells rendered as zero (neutral color)

Works with up to ~500 unique values per axis without performance degradation

Existing TwoDimensionalHeatmap behavior for trends insights is unchanged

Additional context

• Related existing type: TwoDimensionalHeatmap (trends only, time × breakdown)
• Workaround today: export SQL results → Grafana or custom dashboard

Debug info

- [ ] PostHog Cloud, Debug information: [please copy/paste from https://us.posthog.com/settings/project-details#variables]
- [ ] PostHog Hobby self-hosted with `docker compose`, version/commit: [please provide]
- [ ] PostHog self-hosted with Kubernetes (deprecated, see [`Sunsetting Kubernetes support`](https://posthog.com/blog/sunsetting-helm-support-posthog)), version/commit: [please provide]

Start by locating the DataVisualizationNode implementation and the existing TwoDimensionalHeatmap display type used by trends insights. Trace how SQL insight query columns and chart settings are exposed, then compare the acceptance criteria against the existing rendering and configuration paths. Done means a distinct spatial display type supports axis and value selection, sparse cells, tooltips, configurable color scales, and the stated performance range without changing existing trend heatmaps.