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
udfwithouttile: one whole run. Rows become features (geojson, h3, heatmap, arc, scatterplot); an image result becomes onerasterpicture at the bounds the run returned or was sent. Not valid formvt— that needstile: truewithudf, or atileUrl.udfwithtile: 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 (udfwithtile: true, orfused-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$paramchanges; 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,mvtandtileUrllayers take nosql.source(fused-hexonly): a Fused server's ERA5, gridMET or/h3/queryendpoint, queried per XYZ tile; noudf(asqlruns 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 narrowingsql, or both for big datasets.
Layer types
geojson: polygons, lines and points from any source.deck-geojsonis an alias ofgeojsonand renders identically — prefergeojson.h3: hexagons fromh3Column(auto-detected from common names like hex, h3 when omitted), styled withcoverage,extruded,elevationAttr.scatterplot: point circles;pointRadiusin pixels (default 5),lineColor/lineWidthfor the outline.heatmap: density of points; weight comes from a continuousfillColor.attr(1 per point when fillColor is static),pointRadiusis the kernel radius in pixels (default 30). Not pickable, no tooltip.arc: one arc per row. Give the endpoints withstartLatColumn/startLngColumnandendLatColumn/endLngColumn(auto-detected from common names when omitted), or asource/targetproperty holding [lng, lat], or a LineString whose first and second vertices are the ends.fillColorcolours the source end,lineColorthe target end,lineWidththe arc width.mvt/raster: tiled fromtileUrl, or fromudfwithtile: true.fused-hex: H3 tiles queried from a Fused server; each XYZ tile's bbox is sent tosource.endpoint(a full URL, or a path on the current server; /h3/query when onlysource.pathis set):/retrieve/era5/daily/bbox,/retrieve/era5/hourly/bboxand/retrieve/gridmet/bboxserve fixed resolution 7 datasets and needdateMin/dateMax;/h3/queryreads any indexedsource.pathand needs the layer'sh3Columnset to the location's indexed space column (setsource.timeColumntoo 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; unlessminZoomis 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 unlessstyle.coverageis set (default 1, where other hex layers default to 0.9). It readssourceinstead ofudf;sqlruns once over every tile in view as{{source}}, beforereduce. It is never auto-detected, never auto-fits and takes nobounds. Setsource.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, andoverview.extentlimits 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 bystyle.overview(fused-hex only):lineColorandfillColor(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 byrow_count_total(rows in the whole file) orrow_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. AlsolineWidth(default 1, 0 = no stroke),opacity(the fill's, default 0.35) andcoverage(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" }.domaindefaults to the data's min/max,paletteto "Sunset".scaleType"quantize" (default) drawsstepsequal-width bands over the domain; "quantile" drawsstepsbands of roughly equal row count, with breaks from the data (domainis 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)" }. Omitcolorsto 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.
Filters
A layer's filters keep the features that pass every one: { "attr": "score", "type": "range", "min": 0.5 }, { "attr": "kind", "type": "categories", "values": ["a", "b"] }, or a time window { "attr": "datetime", "type": "time", "min": "2025-01-06", "max": "2025-01-13T12:00:00Z" }. A time filter reads ISO dates and datetimes (no zone means UTC), common date text and epoch numbers; its bounds are ISO text, epoch milliseconds, or a $param. With the "Map time playback" experimental feature on, the sidebar types time columns as times and a time filter has a Time playback button: it opens a bar along the bottom of the map that plays the window across the data, as kepler.gl's time filter does (any layer with rows, tiled layers over their loaded tiles; not rasters). A fused-hex layer plays any time column. On its time column (source.timeColumn, date on the retrieve endpoints), when that is a series of daily or hourly steps, it plays one time step at a time: the window is one step, play moves 4 steps a second at 1× and skips steps with no rows, and source.reduce is ignored while the filter holds one step. A paused or closed bar leaves that step in the filter (min and max equal), and the layer keeps drawing it; Reset clears it and the layer reduces again.
Every widget is defined as { "type": "fused-map", "props": { ... } }. The properties below describe the props object.
Props
Raw schema
Download the full schema file: /widget-schema/fused-map.json