Skip to main content

Fused Map

Type: fused-map

Interactive map with tile, UDF and SQL layers.

Supports children: No

Interactive map: a Mapbox basemap with every data layer (mvt, raster, geojson, h3, heatmap, arc, scatterplot, deck-geojson, fused-hex) rendered through deck.gl. Layers load data from a UDF directly (udf), from a tile endpoint (tileUrl) or from a Fused server's hex query endpoints (fused-hex with source). A DuckDB query (sql) reads UDF results on its own, or queries the rows of a udf or fused-hex layer (once over the tiles in view when the layer is tiled). A sidebar lets viewers restyle, filter and re-query layers at runtime.

Example — UDF result (GeoDataFrame)

{
"type": "fused-map",
"props": {
"layers": [{
"id": "buildings",
"type": "geojson",
"udf": "{{my_udf}}",
"tooltip": true,
"style": { "fillColor": { "type": "continuous", "attr": "height", "palette": "Sunset" } }
}]
}
}

Example — UDF as H3 tiles

{
"type": "fused-map",
"props": {
"layers": [{
"id": "hexes",
"type": "h3",
"udf": "{{my_h3_udf}}",
"tile": true,
"style": { "fillColor": { "type": "continuous", "attr": "count", "domain": [0, 500] } }
}]
}
}

Example — MVT tile layer

{
"type": "fused-map",
"props": {
"layers": [{
"id": "counties",
"type": "mvt",
"tileUrl": "https://tiles.fused.io/public/my_tileset/{z}/{x}/{y}",
"style": { "fillColor": [100, 150, 200], "opacity": 0.6 }
}]
}
}

Example — rows from a canvas SQL source (h3-query, sql-runner)

{
"type": "fused-map",
"props": {
"layers": [{
"id": "calls",
"type": "h3",
"h3Column": "hex",
"data": "{{nyc311}}",
"sql": "SELECT hex, COUNT(*) AS calls FROM {{source}} GROUP BY 1",
"style": { "fillColor": { "type": "continuous", "attr": "calls" } }
}]
}
}

data: "{{name}}" draws the rows a canvas SQL source published (an h3-query or sql-runner widget's name, or another map's layer id) straight from DuckDB: no UDF runs, and the edge from that node to this one grants access, as for a UDF. Add sql to query them ({{source}} or {{name}} reads the rows). Row layers only (geojson, h3, scatterplot, heatmap, arc, or type omitted to detect), never tiles.

Example — SQL with lat/lng points and a filter

{
"type": "fused-map",
"props": {
"layers": [{
"id": "sites",
"type": "geojson",
"sql": "SELECT name, lat, lng, score FROM {{my_udf}}",
"filters": [{ "attr": "score", "type": "range", "min": 0.5 }],
"style": { "fillColor": [255, 80, 0], "pointRadius": 8 }
}]
}
}

Example — raster tile layer

{
"type": "fused-map",
"props": {
"layers": [{
"id": "seismic",
"type": "raster",
"tileUrl": "https://udf.ai/<token>/run/tiles/{z}/{x}/{y}?format=png",
"style": { "opacity": 0.8 }
}]
}
}

Example — indexed H3 data (fused-hex)

{
"type": "fused-map",
"props": {
"centerLng": -73.985, "centerLat": 40.755, "zoom": 14,
"layers": [{
"id": "nyc311-hex",
"type": "fused-hex",
"h3Column": "hex",
"minZoom": 14,
"source": {
"path": "s3://fused-asset/data/nyc311/",
"timeColumn": "created_date",
"dateMin": "2024-07-01",
"dateMax": "2024-07-07T23:59:59",
"variables": ["complaint_type"]
},
"tooltip": ["hex", "created_date", "complaint_type"],
"style": { "fillColor": { "type": "categorical", "attr": "complaint_type", "palette": "Bold" } }
}]
}
}

Raster layers with a tileUrl fetch PNG tiles from a publicly reachable XYZ endpoint; only opacity and visible apply. udf with tile: true instead runs the UDF per tile through the workbench (or the canvas share token on a shared page), so no share token is needed and edits to the UDF re-render the layer.

Choosing a source

  • udf without tile: one whole run. Rows become features (geojson, h3, heatmap, arc, scatterplot); an image result becomes one raster picture at the bounds the run returned or was sent. Not valid for mvt — that needs tile: true with udf, or a tileUrl.
  • udf with tile: true: the UDF runs per XYZ tile; use for large or tile-shaped UDFs (raster → PNG, h3 → hexagons, geojson → vector features). Tile layers never auto-fit.
  • sql: a DuckDB query over {{udf}} results; rows become features via geometryColumn / latColumn+lngColumn / h3Column. On a tiled layer (udf with tile: true, or fused-hex) it runs once over the rows of every tile loaded in the current view, reading them as {{source}}, which takes no ?params (a udf layer may also write its own {{udf}}, bare or with exactly its own ?params), and runs again as the view moves (pan, zoom), the query changes or a $param changes; no tile is refetched. WHERE, computed columns, GROUP BY, aggregates, LIMIT, ORDER BY and USING SAMPLE apply to the whole view; only a single SELECT (a WITH is fine) over {{source}} runs (no UNION, several statements, other UDFs or joins), and its result must keep the cell column (h3, fused-hex) or the geometry columns (vector layers). raster, mvt and tileUrl layers take no sql.
  • source (fused-hex only): a Fused server's ERA5, gridMET or /h3/query endpoint, queried per XYZ tile; no udf (a sql runs once over the tiles in view as {{source}}).
  • Whole-run results larger than the viewer's "Max amount of data to auto-load" setting (default 50 MB) are not loaded until the viewer confirms, and UDFs marked for manual runs show a Run button instead of running on load. Prefer tile: true, a narrowing sql, or both for big datasets.

Layer types

  • geojson: polygons, lines and points from any source. deck-geojson is an alias of geojson and renders identically — prefer geojson.
  • h3: hexagons from h3Column (auto-detected from common names like hex, h3 when omitted), styled with coverage, extruded, elevationAttr.
  • scatterplot: point circles; pointRadius in pixels (default 5), lineColor/lineWidth for the outline.
  • heatmap: density of points; weight comes from a continuous fillColor.attr (1 per point when fillColor is static), pointRadius is the kernel radius in pixels (default 30). Not pickable, no tooltip.
  • arc: one arc per row. Give the endpoints with startLatColumn/startLngColumn and endLatColumn/endLngColumn (auto-detected from common names when omitted), or a source/target property holding [lng, lat], or a LineString whose first and second vertices are the ends. fillColor colours the source end, lineColor the target end, lineWidth the arc width.
  • mvt / raster: tiled from tileUrl, or from udf with tile: true.
  • fused-hex: H3 tiles queried from a Fused server; each XYZ tile's bbox is sent to source.endpoint (a full URL, or a path on the current server; /h3/query when only source.path is set): /retrieve/era5/daily/bbox, /retrieve/era5/hourly/bbox and /retrieve/gridmet/bbox serve fixed resolution 7 datasets and need dateMin/dateMax; /h3/query reads any indexed source.path and needs the layer's h3Column set to the location's indexed space column (set source.timeColumn too so latest/first can order rows). Each hex's rows over the window are reduced to one (reduce: latest, first, mean, min, max, sum). Tiles load from zoom 7 for a single day; unless minZoom is set the floor rises with the window (about one zoom level per 4x more time steps) so a tile stays within the server's row limit, and nothing draws below it. A tile the server still rejects as too large shows an error: zoom in or narrow the window. Row cells cover their hexagon whole unless style.coverage is set (default 1, where other hex layers default to 0.9). It reads source instead of udf; sql runs once over every tile in view as {{source}}, before reduce. It is never auto-detected, never auto-fits and takes no bounds. Set source.overview ({} is enough) to outline, from zoom 3 up to the floor, the H3 cells of the files the query reads (no rows are read): one request lists them, with no tiles and no values, so the outlines show where data exists, not what it holds. ERA5 retrieve endpoints and /h3/query only (for /h3/query the world extent lists the whole location); it is an error on gridMET. overview.minZoom (default 3) must sit below the floor for the overview to draw, and overview.extent limits the area it looks up and also confines the row tiles: none are requested outside it, and cells are drawn only inside it, overview and rows alike, by cell centre (default: the whole world). Overview cells are styled apart from the rows by style.overview (fused-hex only): lineColor and fillColor (default: #afafaf stroke, no fill) each take a single colour, "inherit" (the layer's own stroke/fill; when that is data-driven, no overview is drawn and a warning shows on the layer card, rows unaffected), or a data-driven {type: "continuous"|"categorical", attr, ...} colouring cells by row_count_total (rows in the whole file) or row_count_window (rows in the file sections the current date window reads) -- the only two overview attributes, since a files overview carries no other values. Also lineWidth (default 1, 0 = no stroke), opacity (the fill's, default 0.35) and coverage (default 1).

Colours

style.fillColor and style.lineColor accept an [r, g, b] or [r, g, b, a] array, a CSS colour string, or a data-driven object:

  • Continuous: { "type": "continuous", "attr": "<numeric property>", "domain": [min, max], "palette": "Sunset", "steps": 7, "reverse": false, "nullColor": "#b8b8b8", "scaleType": "quantize" }. domain defaults to the data's min/max, palette to "Sunset". scaleType "quantize" (default) draws steps equal-width bands over the domain; "quantile" draws steps bands of roughly equal row count, with breaks from the data (domain is ignored). Sequential palettes (CARTOColors): Sunset, SunsetDark, Teal, TealGrn, Emrld, BluGrn, BluYl, Mint, DarkMint, Purp, PurpOr, Magenta, Burg, BurgYl, RedOr, OrYel, Peach, PinkYl, BrwnYl.
  • Categorical: { "type": "categorical", "attr": "<property>", "colors": { "<value>": "#hex" }, "palette": "Bold", "nullColor": "rgba(128,128,128,0.5)" }. Omit colors to auto-assign from the palette (default "Bold"). Qualitative palettes: Bold, Vivid, Safe, Prism.

A legend is drawn only for data-driven colours (see legend and showLegend).

layerBlending (normal, additive, subtractive) sets how all data layers blend where they overlap, as kepler.gl's Layer blending does; omit it for normal.

Every widget is defined as { "type": "fused-map", "props": { ... } }. The properties below describe the props object.

Props

Loading ....

Raw schema

Download the full schema file: /widget-schema/fused-map.json