Map

Use a map for governed observations with geographic coordinates or a named geometry asset. Geographic presentation and layer fields are typed and lower directly into the renderer-independent map Visual IR.

Layer tooltip fields are projected in authored order. Use the structured tooltip item form when a row needs a display label or format override; an explicit empty list suppresses hover rows. Values are escaped by the MapLibre overlay, null values display as —, and reference layers do not support row tooltips.

The tiled map accessible table reports precision family separately from geometry: an aggregate-resolution tile can contain individual points and aggregate cells. Rows identify these as Point (aggregate resolution) or Aggregated area; individual points retain their stable selection identity and remain selectable.

Every preview on this page is generated from the YAML shown below against the fixed documentation dataset.

Basemap label density

Use presentation.labelDensity to control the amount of basemap labeling without changing geographic data layers. hidden suppresses governed labels, normal keeps the primary labels while reducing secondary detail, and dense enables the full governed basemap label set. Labels authored on geographic data layers are unaffected.

presentation:
  type: geographic
  labelDensity: normal

Choropleth

Join a result dimension to a pinned geometry asset and color regions by a governed metric.

Key fields

visuals:
  state_order_map:
    title: Orders by state
    description: Maps order count by Brazilian state.
    type: map
    query:
      type: aggregate
      dimensions:
      - state
      metrics:
      - order_count
      sort:
      - field: order_count
        direction: desc
      limit: 27
    presentation:
      type: geographic
      theme: auto
      layers:
      - kind: choropleth
        id: states
        geometryAsset: brazil_states
        join: state
        value: order_count
        tooltip: [state, order_count]
        color:
          kind: sequential
          palette: teal
          nullColor: "#d8dee4"

Coordinate points

Bind latitude and longitude dimensions to semantic fields. The compiler owns the geographic renderer, tile policy, and point styling.

Tiled point layers keep the authored cluster policy as renderer-neutral contract data. radius is an approximate CSS-pixel clustering target (1–512), not an exact radial distance. Tiled aggregation uses a globally aligned grid with max(1, floor(256 / radius)) cells per tile, so the effective cell width is 256 / max(1, floor(256 / radius)) CSS pixels and radii 129–512 share one cell per tile. The transport cell radius remains separate; cluster membership is not promised to be pixel-identical between inline and tiled data. maximumZoom is the last zoom at which clusters may be served, minimumPoints controls the cluster threshold, and showCount labels a cluster with its contained coordinate count. These settings are shared by point layers on one tiled source; incompatible policies are rejected during compilation. maximumZoom must be below the tiled terminal zoom (18); at the terminal zoom and above there is no valid maximumZoom + 1 raw transition.

Key fields

visuals:
  order_point_map:
    title: Order locations
    description: Shows governed order locations with revenue context.
    type: map
    query:
      type: aggregate
      dimensions:
      - order_id
      - latitude
      - longitude
      metrics:
      - revenue
    presentation:
      type: geographic
      theme: light
      camera:
        mode: fit_data
        padding: 32
        maximumZoom: 9
      layers:
      - kind: point
        id: orders
        latitude: latitude
        longitude: longitude
        value: revenue
        label: order_id
        tooltip: [order_id, revenue]
        size:
          minimumRadius: 5
          maximumRadius: 28
        cluster:
          enabled: true
          radius: 40
          maximumZoom: 14
          minimumPoints: 2
          showCount: true
        stroke:
          color: "#ffffff"
          width: 1.5
          opacity: 1

Heat

Aggregate a numeric value around each coordinate while keeping the query and field references governed.

Key fields

visuals:
  revenue_heat_map:
    title: Revenue concentration
    type: map
    query:
      type: aggregate
      dimensions:
      - latitude
      - longitude
      metrics:
      - revenue
    presentation:
      type: geographic
      theme: dark
      layers:
      - kind: heat
        id: revenue
        latitude: latitude
        longitude: longitude
        value: revenue
        heat:
          radius: 28
          intensity: 1.15

Density

Emphasize the concentration of observations without requiring a value binding. With no value binding, raw features contribute one observation and aggregate cells are weighted by their contained row count.

Key fields

visuals:
  order_density_map:
    title: Order density
    type: map
    query:
      type: aggregate
      dimensions:
      - latitude
      - longitude
      metrics:
      - order_count
    presentation:
      type: geographic
      layers:
      - kind: density
        id: orders
        latitude: latitude
        longitude: longitude
        heat:
          radius: 22
          intensity: 1.35

Reference boundary

Reference layers add immutable, content-addressed geometry without joining query values into the shape. Because reference geometry has no query-row locator, reference layers do not support tooltip; use a data-backed layer such as choropleth when row-level tooltip context is needed.

Key fields

visuals:
  state_reference_map:
    title: Brazil state reference boundaries
    type: map
    query:
      type: aggregate
      dimensions:
      - state
      metrics:
      - order_count
      limit: 27
    presentation:
      type: geographic
      basemap: blank
      layers:
      - kind: reference
        id: state_boundaries
        geometryAsset: brazil_states
        color:
          kind: sequential
          palette: blue
          nullColor: "#d8dee4"
        stroke:
          color: "#57606a"
          width: 1.5
          opacity: 1
        opacity: 0.12

Paths

Group coordinate rows by a stable path field and order vertices deterministically.

Key fields

visuals:
  state_order_paths:
    title: State order paths
    type: map
    query:
      type: aggregate
      dimensions:
      - state
      - order_id
      - latitude
      - longitude
      metrics:
      - revenue
      limit: 100
    presentation:
      type: geographic
      controls:
        zoom: true
        reset: true
        compass: true
      layers:
      - kind: path
        id: state_paths
        latitude: latitude
        longitude: longitude
        path: state
        order: order_id
        value: revenue
        tooltip: [state, revenue]
        stroke:
          color: "#0969da"
          width: 3
          opacity: 0.9
        line:
          width: 3
        opacity: 0.9

API reference

Kind: chart. Renderer: maplibre. Supported result shapes: geographic_features.

Field	Type	Default	Allowed values	Description
`query.dimensions`	`field mapping`	—	—	Groups query results and supplies category or hierarchy labels.
`query.limit`	`integer`	`no limit`	`positive integer`	Caps the number of rows returned to the renderer.
`query.metrics`	`metric mapping`	—	—	Selects governed semantic metrics consumed by the visual shape.
`query.sort`	`sort list`	—	—	Orders query results by a returned field or metric alias.
`presentation.basemap`	`string`	`streets`	`streets` `blank`	Selects a pinned basemap asset or an intentionally blank background.
`presentation.camera`	`map camera`	`fit_data`	—	Configures bounded map camera behavior.
`presentation.controls`	`map controls`	`zoom, reset, compass`	—	Enables explicit map controls.
`presentation.layers`	`geographic layer list`	`point`	`point` `choropleth` `heat` `density` `reference` `path`	Declares typed geographic layers and governed field bindings.
`presentation.theme`	`string`	`auto`	`auto` `light` `dark`	Selects the map basemap theme.

Accessibility. Use a descriptive summary for the geographic pattern, verify region joins or coordinate fields, and do not rely on color alone to communicate intensity.