The Deck.gl Scatterplot

What it is

deck.gl is a tool to visualize large datasets. Within Superset, it is used to visualize maps in a highly performant way.

The deck.gl Scatterplot chart draws each row of your query as a circle on a real map. It needs only three things: a latitude, a longitude, and one numeric metric per row. The metric can make the circle bigger and it can also decide the circle's color, so the map answers "where is it, and how bad is it?" at a glance.

This is the map version of the water example from the Handlebars documentation. A Handlebars card answers "can this village drink its water?" — a deck.gl scatterplot answers "which villages, and are they clustered along the same river?"

When it is useful

• When location carries meaning: water sources, sampling sites, health posts, incident reports, nesting trees.
• When you have one number per place and want hotspots, clusters, and gaps to stand out.
• When your audience reads maps naturally — a council or community often gets more from a map of colored dots than from a table of readings.
• When a Handlebars or table chart shows what the values are, and you want a companion chart to show where they are.

Setting up longitude and latitude

Build a virtual dataset with one row per place, with coordinates as separate numeric columns. The Helpful SQL Queries page (Geospatial Data Processing) has recipes for pulling latitude and longitude out of the single Record_your_current_location field that ODK/Kobo forms store. For the water example:

SELECT
    station,
    latitude,
    longitude,
    CAST(turbidity_ntu AS REAL) AS turbidity_ntu,
    sample_date
FROM water_quality

In the chart's Data tab, the Longitude & Latitude control opens a small popover with three ways to point at your coordinates:

• Longitude & Latitude columns — the usual case: pick the two columns separately, as in the query above.
• Delimited long & lat single column — when both numbers live in one text field (the Kobo format again). It accepts several orders, with a Reverse lat/long checkbox when your values land in the ocean. Splitting them in SQL instead is easier to debug and works in every chart, so prefer that when you can.

nota

Rows with empty coordinates simply do not appear on the map — no error, just missing sites. Filter them out in your query (WHERE latitude IS NOT NULL) and compare the row count of your query with the number of circles you see; the difference is a data-quality gap worth fixing at the form level.

The metric

The single number per location is set under Point Size → Point Size, by switching the toggle from Fixed to Based on a metric (for example MAX("turbidity_ntu")). This toggle is crucial: if left on Fixed, Superset completely omits the numerical values from the query payload, leaving deck.gl with no values to evaluate and defaulting all map points to grey.

Because Superset groups scatterplot data by coordinate dimensions (latitude and longitude), your metric must use an aggregation function like MAX, AVG, or SUM. If each coordinate in your dataset represents a single row, functions like MAX or AVG return the exact raw value without altering it.

Common technical pitfalls to watch for:

• Case Sensitivity: Database engines like PostgreSQL convert unquoted column names to lowercase. If Superset throws a column does not exist error, open the Custom SQL tab in the metric picker and wrap the column name in double quotes: MAX("Turbidity").
• Data Types: The column must be strictly numeric. Text responses or string-encoded decimals must be converted using CAST("column" AS REAL) or adjusted in the Dataset column settings.

Also check that Row limit covers all of your sites, and add the site name (and the reading date) under Tooltip Contents so hovering a circle tells people which station it is. To lay that hover text out yourself, see Customizing the tooltip.

Customizing the tooltip

The hover text is HTML. You write the layout, and Superset fills in {{ column_name }} placeholders. The name inside the braces has to match a field the tooltip actually receives.

Two controls do this:

1. Tooltip contents — add every column the hover should be able to show. A column left out of this list is not available to the template, even when it is in the query.
2. Customize tooltip template — the HTML. This field is where the layout goes, after the columns are selected.

Click Update chart, then hover a point.

Start with one field:

<strong>{{ cat_color }}</strong>

<strong>…</strong> makes text bold. <br> starts a new line.

{{ cat_color }} is not a column you add. It is Superset's name for the category that colors the point — the Dimension under Categorical palette, such as species. Every other value uses its own column name, and that column has to be in Tooltip contents first.

For more than one field, add those columns to Tooltip contents, then stack them:

<div style="background:#fff; color:#222; padding:10px 12px; border-radius:6px;">
  <strong>{{ station }}</strong><br>
  Turbidity: {{ turbidity_ntu }} NTU<br>
  Date: {{ sample_date }}
</div>

Wrap a line in {{#if comment}} … {{/if}} to show it only when that field has a value.

Styles go on the elements. This control has no separate CSS field, and the template itself is HTML only.

nota

The layout can show up while the values stay blank. Superset 6.1.0 reads tooltip fields on the point itself and skips anything nested under extraProps, so a column selected in Tooltip contents can still come through empty. Later Superset versions do check extraProps.

If the hover shows the braces as text, such as {{ station }}, the template is not being filled in. If the layout appears and the values are empty, the names do not match the data the tooltip received.

Paste this, click Update chart, and hover a point. It prints every field the template can see:

{{#each this}}
  <div><strong>{{@key}}:</strong> {{this}}</div>
{{/each}}

Use those names in the template.

Brackets: color breakpoints

The power feature for a non-technical audience is Point Color → Color Scheme Type → Color breakpoints: you define ranges ("brackets") of the metric, and give each range its own color. Each bracket row is a minimum value, a maximum value, and a color; a point is matched inclusively (min ≤ value ≤ max), and the first bracket that matches wins — so keep your ranges contiguous without gaps. Values that fall in no range get the Default color (grey), and the legend labels the ranges for you.

What brackets require: a numeric metric selected under Point Size. They cannot work from a text column. Additionally, if you previously selected Categorical palette, clear any column remaining in the Dimension box before switching back to Color breakpoints—a leftover dimension field forces deck.gl into category mode and ignores your numeric range rules.

If you instead want one color per category — river, village, source type — that is what Categorical palette → Dimension is for: pick a dimension and each category gets its own palette color. A quick way to remember it:

Your column is...	Use
A number you want bucketed into ranges (turbidity, pH, count)	Point Size: Based on a metric Point Color: Color breakpoints
A label (station, community, water source)	Point Color: Categorical palette + Dimension

Custom brackets for ranges. Left on its own, Superset splits the data into evenly sized buckets, which almost never match a meaningful threshold. Set the ranges yourself so the colors change exactly where the real-world limits are. Ensure your highest range uses an explicit upper bound (e.g., 50.001 - 10000) rather than leaving it open; points exceeding your defined maximum will otherwise fall back to the grey default color.

For turbidity (NTU), guided by the WHO Guidelines for Drinking-water Quality:

Range	Color	Reading
0 – 1	green	Clear; disinfection works well
1.001 – 5	yellow	Most people find it acceptable, but it shields germs
5.001 – 50	orange	Visibly dirty; treatment struggles
50.001 – 10000	red	Obvious problem — investigate and act

As in the Handlebars documentation, treat these as a starting point: ask an LLM for the international standards for your metric, then confirm the thresholds your country or community actually uses.

Choosing colors

How you pick the palette depends on who reads the map:

• If the map is read by scientists, agencies, or regulators, use colors and scales those audiences use worldwide for your metric — established sequential scales (viridis-style blues, blue-to-brown for turbidity), WHO-style traffic lights for thresholds — and prefer colorblind-safe palettes.
• If the map is read exclusively by the community, use colors people already relate to the condition — clear blue, muddy brown, red as danger — and check those associations with community members first, since color meanings are not universal.
• Either way, keep colors concise across charts: the same 3–5 colors, mapped to the same ranges, in the map, the Handlebars cards, and any table. If green means "safe" on the cards and "good" on the map, both say the same thing.

Basemaps

The map behind your data layers is configured under the Map → Map Style dropdown panel:

• Standard OpenStreetMap Styles: If your instance does not have a Mapbox access token, Superset defaults to free OpenStreetMap options: Streets (OSM), Topography (OSM) (ideal for tracking rivers and terrain relief), and Dark (OSM).
• Official Mapbox Styles: If a Mapbox token is pre-configured on the backend, official basemaps like Light, Dark, Outdoors, and Satellite will seamlessly populate in the picker list.
• Contrast Tips: Use a dark basemap to make brightly colored data breakpoints pop on dashboard monitors. Switch to a light basemap if you need high contrast for readable town names or document exports.

Autozoom frames all active data coordinates automatically upon page load. To fix the camera position permanently over a single target territory, toggle Autozoom off, manually click-and-drag your map frame to the desired viewport, and click Save.

Advanced: Using a custom Mapbox Studio style

important

The style has to be Mapbox GL JS 2.x.x compatible. Mapbox Studio maps created with a 3.x.x version of GL JS will have issues, including:

• Background map assets like imagery or hillshade layers will not work, because as of 3.x.x these are added using an "imports": [] block not supported by Mapbox GL JS 2.
• The map as a whole will not work at all due to an error: cannot read properties of undefined (reading 'resize').

The best solution is to set your Mapbox GL JS version to 2.x.x (like 2.12.1+) in the Mapbox Studio style Settings, and resolve any warnings.

If all else fails, start over by creating a Classic Style in Mapbox Studio, which will be GL JS 2 compatible.

If the standard dropdown selections don't meet your needs and you do not have administrative backend access to add a custom tile server, you can forcefully inject a custom Mapbox Studio URL (e.g., mapbox://styles/...) using a configuration export workaround:

1. Export your chart: Navigate to your chart, click the action menu icon, and select Export. This downloads a .zip bundle of your configuration assets.

2. Modify the configuration file: Unzip the folder, navigate to the /charts subfolder, and open your chart's .yaml file using a standard text editor.

3. Inject your custom style: Find the parameter labeled mapbox_style: (located in both the raw params: block and nested within the stringified query_context: JSON blob). Swap out the default string with your precise Mapbox Studio link:

   mapbox_style: "mapbox://styles/your_username/your_custom_style_id"

4. Re-import the bundle: Save the text file, re-compress the root folder into a .zip package, and upload it back into Superset using the cloud Import utility.

nota

Once imported, you can safely use Save as... inside the Explorer UI to clone this chart into new views without breaking your hidden custom basemap link.

dica

This section highlights the foundational configuration components. The map includes an extensive tray of advanced parameters—such as customizable tooltip templates, geometric legend sizing, click-through workflow actions, and explicit JavaScript payload callbacks—detailed thoroughly in the Official Apache Superset Documentation.