# Map Data Join

<flow-map-data-join>

Reactive

Stable

The map data join component specifies non-geospatial data to join with a geospatial datasource.

The Map Data join component is used as a child element of a Map Data Source component to specify additional non-geospatial data to join with the geospatial features from the parent Map Data Source. The joined data can be accessed in Map Layer style rules to apply data-driven styling in a similar way to using feature properties.

Using data joins is a very efficient way of creating maps that display static geometry with dynamic data attributes. The static geometry is loaded once and the dynamic data attributes are applied without reloading map tiles or static geojson. Updates to the dynamic data are applied very quickly with no flicker when redrawing the map features.

# The Joined Data Source

The src attribute of the Map Data Join component is used to specify the non-geospatial data to join to the parent data source features. The data should be an array of data objects, typically with a one-to-one correspondence between data objects and geospatial features.

The source of the data to join can be specified in a number of ways:

A literal array of data objects.
A Flo.w reactive expression returnin an array of data objects.
Results of a Flo.w RDF reactive query
A Flo.w dataset ID.
A URL to a 3rd-party API returning data in the required format.

When specifying a Flo.w dataset ID or a 3rd-party URL, additional reactive parameters can be set by specifying Map Parameters as children of the Map Data Join component. These parameters will be added to the query string of the resulting HTTP request.

# Specifying How to Join the Data

Data joining to features of the parent geospatial data source is performed by matching the primary key of geospatial features with a foreign key in the joined data. It is analogous to performing a LEFT JOIN in SQL. Use the feature-id attribute of the parent data source to specify the primary key. Use the foreign-key attribute of the data join to specify the foreign key in the joined dataset.

Specify the clear attribute to clear all joined data from all features before applying new joined data. Use this option to determine the behavior when applying a partial data join with some missing features.

# Accessing the Joined Data

To access joined data within Map Layer style rules, use the @@<data join name>.<property> notation. This is equivalent to the @<property> notation used to access geospatial feature properties.

Joined data for a particular feature may be null if no data for that feature is present in the joined dataset. Use the ternary operator to supply a 'no data' value in style rules.

For example, to access the val property from the joinedData data join to specify a color but default to gray for missing data:

  ...
  circle-color: @@joinedData ? from-palette('RdYlGn', @@joinedData.val, 0, 10) : gray;
  ...

# Examples

# Join Results of Flo.w Reactive Query

# Properties

Property	Description	Type	Default
`clear`	Set to `true` to clear all current feature state before applying the data join.	`boolean`	`false`
`foreignKey` `foreign-key`	The foreign key property of the joined data. Data will be joined to features where the foreign key equals the feature ID.	`string`	`'id'`
Deprecated `name`	Use `id` attribute instead. The name of the data join.	`string`
`sourceLayer` `source-layer`	Specify the source layer in the target data source to join. Applicable only for vector data sources. Defaults to 'geometry'.	`string`
Reactive `src`	The data to join. Specify a reactive expression or an array of data objects.	`any[] \| string`

← Map Parameter Map Popup →