Maps¶
Maps encode data through geographic position, using region fills, symbols, or other marks tied to real places. They are most useful when location itself is part of the meaning, with filled-region maps working best for values aggregated by area and symbol maps working best for counts, events, or magnitudes at specific places.
dbt Charts maps are configured primarily through top-level geographic fields such as geo, geo_source, lookup, value, projection, latitude, longitude, and size. In practice, that means this family relies much more on map-specific top-level configuration than on large mark, encoding, or style passthrough surfaces.
A chart's control surface is the full set of authored properties available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus the typed style object.
This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the YAML Schema Reference.
Map joins are exact-key joins. Your lookup field must match the geographic source's key values exactly, including formatting details such as leading zeros, abbreviations, or code systems. If a region is unexpectedly missing, the first thing to check is whether the query key format matches the map source key format.
Minimum Required for a Filled-Region Map¶
These are the minimum fields required to render a basic filled-region map in dbt Charts. Other map forms have different minimums: a symbol map (type: point_map) needs coordinate fields, and a proportional symbol map (type: bubble_map) needs coordinates plus a size field. projection is optional when the chart has a built-in geo_source (or a point map's basemap.source), because each built-in source carries a suited projection. A map without one, such as a point map with no basemap, must set projection or dbt Charts raises ERR-GEO-PROJECTION-REQUIRED.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
query |
lookup data values | Query name or query reference | Supplies the data that will be joined to the geographic features. |
type: map |
mark.type: "geoshape" |
Literal map |
Selects the filled-region map form. |
geo.source |
geographic data URL and format | Built-in geo source name or custom GeoJSON/TopoJSON URL | Chooses the boundary shapes to render. |
lookup |
geoshape lookup join key | Field name | Field in your query data that joins to the geographic source. The values must match the source key format exactly. |
value |
encoding.color.field |
Field name | Quantitative field used to fill regions. Prefer densities, rates, or percentages over raw totals. |
Minimum Map Example¶
queries:
new_england_population_density:
columns: [state_code, population_density]
values:
- ["9", 742]
- ["23", 44]
- ["25", 901]
- ["33", 154]
- ["44", 1022]
- ["50", 68]
charts:
new_england_population_density_map:
query: new_england_population_density
type: map
title: New England Population Density
geo:
source: us-states
lookup: state_code
value: population_density
projection:
type: mercator
center: [-71.8, 43.8]
scale: 2200
rows:
- new_england_population_density_map
Top-Level Chart Fields¶
These are the top-level chart properties you set directly on a map before reaching for smaller nested properties. This is where dbt Charts exposes most of the meaningful map surface.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
query |
lookup data values | Query name or query reference | Data to join to regions or plot as points. |
type: map |
mark.type: "geoshape" |
Literal map |
Canonical map type. Renders an outline map or a filled-region map depending on the fields provided. |
type: point_map |
mark.type: "circle" |
Literal point_map |
Symbol map for events or places at exact coordinates. |
type: bubble_map |
mark.type: "circle" |
Literal bubble_map |
Proportional symbol map with quantitative sizing. |
title |
title.text |
String | Chart title. |
notes |
metadata | String | AI search/context metadata. Never rendered. |
geo |
geographic source config | Object with source, optional key, optional feature |
Primary map source config. |
geo_source |
geographic source selector | us-states, us-counties, world-countries, world-50m, sf-neighborhoods, nyc-neighborhoods, chicago-neighborhoods, la-neighborhoods |
Convenience shorthand for selecting a built-in background or map source. |
lookup |
geoshape lookup join key | Field name | Query field used to join your data to the geographic features. The values must match the source key format exactly. |
value |
encoding.color.field |
Field name | Region fill value field. In practice, filled-region maps usually work best with densities, rates, or percentages rather than raw totals. |
color |
encoding.color.field |
Field name | Bubble/point color field, or region fill shorthand when value is omitted. |
projection |
top-level projection |
One of mercator, transverseMercator, equirectangular, equalEarth, naturalEarth1, mollweide, azimuthalEqualArea, azimuthalEquidistant, gnomonic, orthographic, stereographic, albers, albersUsa, conicConformal, conicEqualArea, conicEquidistant, identity; or an object with type and any of center, rotate, scale, translate, parallels, clipAngle, clipExtent, precision, reflectX, reflectY, pointRadius |
Overrides the source default projection. Any other name or key is a compile error. |
latitude |
encoding.latitude.field |
Field name | Point-map latitude field. Auto-detected from common names when omitted. |
longitude |
encoding.longitude.field |
Field name | Point-map longitude field. Auto-detected from common names when omitted. |
size |
encoding.size.field |
Field name | Quantitative size field for bubble maps. Mark area scales proportionally with the value (zero-anchored range), not radius. |
collapse |
encoding.size: {aggregate: "count"} |
true / false (default false) |
point_map/bubble_map only. Collapses marks sharing an exact latitude/longitude into one mark, area-proportional to the count. Mutually exclusive with size, and with a color channel; it would widen the count's implicit groupby beyond latitude/longitude. |
Map Form Minimums¶
This quick reference shows the minimum fields for each major map form. Use it to choose the right starting shape before you add projection, color schemes, or other refinements.
| Map form | Minimum dbt Charts fields | Notes |
|---|---|---|
map |
query, type: map, geo.source, lookup, value |
Filled-region map joined to geographic features. |
map (outline) |
type: map, geo.source |
Base outline map. Add query, lookup, and value only if you want data-driven fills. |
point_map |
query, type: point_map, latitude, longitude |
Symbol map for exact locations. Add geo_source if you want a geographic backdrop. |
bubble_map |
query, type: bubble_map, latitude, longitude, size |
Proportional symbol map with quantitative sizing. Add geo_source if you want a geographic backdrop. |
Filled-Region Maps and Bubble Maps¶
This example shows the family's two main forms using the same New England geography: a filled-region map for region-level density and a bubble map for magnitudes at exact locations.
queries:
new_england_population_density:
columns: [state_code, population_density]
values:
- ["9", 742]
- ["23", 44]
- ["25", 901]
- ["33", 154]
- ["44", 1022]
- ["50", 68]
new_england_cities:
columns: [city, lat, lng, revenue, store_type]
values:
- ["Boston", 42.3601, -71.0589, 980000, "Flagship"]
- ["Providence", 41.8240, -71.4128, 520000, "Boutique"]
- ["Portland", 43.6591, -70.2568, 410000, "Boutique"]
- ["Hartford", 41.7658, -72.6734, 460000, "Outlet"]
- ["Burlington", 44.4759, -73.2121, 290000, "Boutique"]
- ["Manchester", 42.9956, -71.4548, 380000, "Outlet"]
charts:
new_england_population_density_map:
query: new_england_population_density
type: map
title: New England Population Density
geo:
source: us-states
lookup: state_code
value: population_density
projection:
type: mercator
center: [-71.8, 43.8]
scale: 2200
new_england_revenue_bubbles:
query: new_england_cities
type: bubble_map
title: New England Store Revenue by City
latitude: lat
longitude: lng
size: revenue
color: store_type
geo_source: us-states
projection:
type: mercator
center: [-71.8, 43.8]
scale: 2200
rows:
- new_england_population_density_map
- new_england_revenue_bubbles
Symbol Maps with a Regional Backdrop¶
This example shows how a regional symbol map can reuse the same New England projection without requiring proportional sizing.
queries:
new_england_locations:
columns: [name, lat, lng, location_type]
values:
- ["Boston", 42.3601, -71.0589, "Commercial Core"]
- ["Portland", 43.6591, -70.2568, "Port City"]
- ["Providence", 41.8240, -71.4128, "College City"]
- ["Burlington", 44.4759, -73.2121, "Regional Hub"]
charts:
new_england_point_map:
query: new_england_locations
type: point_map
title: New England City Locations
geo_source: us-states
latitude: lat
longitude: lng
color: location_type
projection:
type: mercator
center: [-71.8, 43.8]
scale: 2200
rows:
- new_england_point_map
Basemap¶
basemap gives a point or bubble map a styled geographic background layer, an
alternative to geo_source for when you also want to control the background fill and
stroke directly, rather than accepting the theme default.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
basemap.source |
background geoshape layer source | Same values as geo_source |
Selects the boundary shapes for the background layer. |
basemap.fill |
background layer mark.fill |
Color value | Background geography fill color. Falls back to the theme's neutral geoshape fill when omitted. |
basemap.stroke |
background layer mark.stroke |
Color value | Background geography boundary stroke color. |
queries:
new_england_cities:
columns: [city, lat, lng]
values:
- ["Boston", 42.3601, -71.0589]
- ["Providence", 41.8240, -71.4128]
- ["Portland", 43.6591, -70.2568]
charts:
new_england_cities_styled_basemap:
query: new_england_cities
type: point_map
title: New England Cities
latitude: lat
longitude: lng
basemap:
source: us-states
fill: "#f5f5f5"
stroke: "#cccccc"
projection:
type: mercator
center: [-71.8, 43.8]
scale: 2200
rows:
- new_england_cities_styled_basemap
Style Fields¶
Use style for map presentation properties that are intentionally simpler than full Vega-Lite control.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
style.color.gradient.palette |
encoding.color.scale.scheme |
Vega-Lite color-scheme name | Most relevant for filled-region maps, where the fill scale carries the main value encoding. |
style.background |
chart SVG background wrapper | Color value | Applies a chart-level background fill behind the final rendered map SVG. Distinct from geo_source, which adds a geographic background layer for point and bubble maps. |
style.size.range |
encoding.size.scale.range |
[low, high] in px², 0 <= low < high |
Point and bubble maps only: the mark area of the smallest and largest size: value. Needs size: or collapse. |
style.size.type |
encoding.size.scale.type |
linear, sqrt, log |
Point and bubble maps only: how a size: value maps onto the range. Default linear. |
Bubble Size Scale¶
A bubble map's size: channel maps values onto a mark-area range, [0, 1000] px² by default, in proportion to the value. When a few values dwarf the rest, the small bubbles vanish. style.size sets the area range and the scale type.
queries: stores: columns: [store, lat, lon, revenue] values: - ["Boston", 42.3601, -71.0589, 600000] - ["Providence", 41.8240, -71.4128, 1400] - ["Hartford", 41.7658, -72.6734, 600] charts: store_revenue: query: stores type: bubble_map latitude: lat longitude: lon size: revenue projection: mercator style: size: range: [9, 2500] type: log rows: - store_revenue
rangeis the mark area in px²:[low, high]with0 <= low < high. Alowabove zero keeps the smallest bubble visible and adds a zero entry to the legend.linearmaps values in proportion to the area from zero.sqrtcompresses a long tail while keeping zero as the anchor.logspans the smallest to the largest value, so everysize:value must be above zero; a value at or below zero is an error.- With
collapse: truethe marks are sized by count, andstyle.sizeshapes them the same way. sqrtmakes a mark's area grow with the square root of the value, so a value 4x larger draws 2x the area. This follows Vega-Lite, not d3's sqrt-on-radius idiom, where area is proportional to the value (that islinearhere).logneeds a range starting above 0, because it maps the smallest value tolow; withlow: 0that mark would draw with no area, so setrange, for example[9, 2500].- A
logorsqrtscale adds a footnote under the legend circles ("Log scale" or "Square-root scale");linearadds none. - The size legend draws its circles at the same range and scale type.
- A
style.conditionalrulesizestill overrides the channel for the points it matches. style.sizeneeds asize:field orcollapse: true; set a default for every point map instyle.charts.point_map.size.
Color Scheme¶
This example keeps the same New England geography and join logic fixed while changing the map palette.
queries:
new_england_unemployment:
columns: [state_code, unemployment]
values:
- ["9", 4.1]
- ["23", 3.6]
- ["25", 4.3]
- ["33", 3.2]
- ["44", 4.0]
- ["50", 2.8]
charts:
new_england_unemployment_map:
query: new_england_unemployment
type: map
title: New England Unemployment Rate
geo:
source: us-states
lookup: state_code
value: unemployment
projection:
type: mercator
center: [-71.8, 43.8]
scale: 2200
style:
color:
gradient:
palette: viridis
rows:
- new_england_unemployment_map
Conditional styling¶
style.conditional restyles a mark by the value in its own row. It maps a column name to a list of rules. Each rule is one condition (eq, ne, lt, lte, gt, gte, between, in, is_null, or default) plus the part of the chart style it applies.
Point and bubble maps¶
On a point or bubble map, a rule restyles a point by the value in its own row:
queries: stores: columns: [store, lat, lon, revenue] values: - ["Boston", 42.3601, -71.0589, 1400] - ["Providence", 41.8240, -71.4128, 600] charts: store_revenue: query: stores type: bubble_map latitude: lat longitude: lon size: revenue style: conditional: revenue: - gt: 1000 marks: point: color: "#c62828" - default: true marks: point: opacity: 0.5 rows: - store_revenue
A rule can set marks.point.color, fill, filled, size, shape, opacity and stroke_width. A rule size overrides the size: channel for the points it matches, and the size legend is unchanged. Matching rules apply together, the later one winning per field, and default: true must be last and applies only when no other rule matched. The column must be in the query result, rules on two columns cannot set the same field, and the rules cannot be combined with collapse. conditional is authored on the chart's own style, not under style.charts.point_map.
Region maps¶
On a region map, a rule restyles a region by the value in its own row. The column is tested on the query row that joined the region, so a region no row matched keeps its base fill:
queries: state_population: columns: [state_code, pop] values: - ["9", 3.6] - ["25", 7.0] - ["44", 1.1] charts: population_map: query: state_population type: map geo: source: us-states lookup: state_code value: pop style: conditional: state_code: - eq: "9" marks: geoshape: fill: "#c62828" stroke: color: "#000000" width: 1.5 rows: - population_map
A rule can set only what varies per region:
| Field | Sets |
|---|---|
marks.geoshape.fill |
The region's fill |
marks.geoshape.stroke.color, marks.geoshape.stroke.width |
The region's boundary |
A stroke width needs a stroke color, from the rule or from marks.geoshape.stroke.
- Every matching rule applies, and where two set the same field the later one wins, so list the more specific rule last.
- A
default: truerule must be last and applies only when no other rule matched. - The column must be in the query result. Rules on two columns cannot set the same field.
- A rule's color replaces the
color:channel's color for the matched region only; the legend is unchanged. conditionalis authored on the chart's ownstyle; atstyle.charts.geoshapeit is refused.