This website is for Vega-Lite v2. 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.

  "transform": [
    {"lookup": ..., "from" ..., "as": ..., "default": ...} // Lookup Transform

Lookup Transform

For each data object in the main data source, the transform tries to find a 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

Required. Secondary data reference.

as String | String[]

The field or fields for storing the computed formula value. If from.fields is specified, the transform will use the same names for as. If from.fields is not specified, as has to be a string and we put the whole object into the data under the specified name.

default String

The default value to use if lookup fails.

Default value: null

Lookup Data

The secondary data reference (set with from) is an 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 to lookup. If not specified, the entire object is queried.


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.