Skip to content

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
New England Population DensityPopulation density05001,0001,500 Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
New England Population DensityPopulation density05001,0001,500New England Store Revenue by CityStore typeBoutiqueFlagshipOutletRevenue200,000400,000600,000800,000 Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
New England City LocationsLocation typeCollege CityCommercial CorePort CityRegional Hub Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
New England Cities Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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
  • range is the mark area in px²: [low, high] with 0 <= low < high. A low above zero keeps the smallest bubble visible and adds a zero entry to the legend.
  • linear maps values in proportion to the area from zero. sqrt compresses a long tail while keeping zero as the anchor. log spans the smallest to the largest value, so every size: value must be above zero; a value at or below zero is an error.
  • With collapse: true the marks are sized by count, and style.size shapes them the same way.
  • sqrt makes 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 is linear here).
  • log needs a range starting above 0, because it maps the smallest value to low; with low: 0 that mark would draw with no area, so set range, for example [9, 2500].
  • A log or sqrt scale adds a footnote under the legend circles ("Log scale" or "Square-root scale"); linear adds none.
  • The size legend draws its circles at the same range and scale type.
  • A style.conditional rule size still overrides the channel for the points it matches.
  • style.size needs a size: field or collapse: true; set a default for every point map in style.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
New England Unemployment RateUnemployment2.53.03.54.04.5 Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

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: true rule 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.
  • conditional is authored on the chart's own style; at style.charts.geoshape it is refused.