This website is for Vega-Lite v4. Go to the main Vega-Lite homepage for the latest release.

Lookup Transform

Edit this page

The lookup transform extends a primary data source by looking up values from another data source. It is similar to a one sided join.

// Any View Specification
{
  ...
  "transform": [
    {"lookup": ..., "from" ..., "as": ..., "default": ...} // Lookup Transform
     ...
  ],
  ...
}

Lookup Transform

For each data object in the main data source, the transform finds matching objects in the secondary data source. An object matches if the value in the field specified by lookup is the same as the field specified in the from.key.

Property Type Description
lookup String

Required. Key in primary data source.

from LookupData | LookupSelection

Required. Data source or selection for secondary data reference.

as String | String[]

The output fields on which to store the looked up data values.

For data lookups, this property may be left blank if from.fields has been specified (those field names will be used); if from.fields has not been specified, as must be a string.

For selection lookups, this property is optional: if unspecified, looked up values will be stored under a property named for the selection; and if specified, it must correspond to from.fields.

default String

The default value to use if lookup fails.

Default value: null

Lookup Data

The secondary data reference (set with from) can be object that specifies how the lookup key should be matched to a second data source and what fields should be added.

Property Type Description
data Data

Required. Secondary data source to lookup in.

key String

Required. Key in data to lookup.

fields String[]

Fields in foreign data or selection to lookup. If not specified, the entire object is queried.

Example

This example uses lookup to add the properties age and height to the main data source. The person field in the main data source is matched to the name field in the secondary data source.

Lookup Selection

The secondary data reference (set with from) canalso be a selection name reference.

Property Type Description
selection String

Required. Selection name to look up.

Example: Interactive Index Chart