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

Flatten

Edit this page

The flatten transform maps array-valued fields to a set of individual data objects, one per array entry. This transform generates a new data stream in which each data object consists of an extracted array value as well as all the original fields of the corresponding input data object.

// Any View Specification
{
  ...
  "transform": [
    {"flatten": ...} // Flatten Transform
     ...
  ],
  ...
}

Flatten Transform Definition

Property Type Description
flatten String[]

Required. An array of one or more data fields containing arrays to flatten. If multiple fields are specified, their array values should have a parallel structure, ideally with the same length. If the lengths of parallel arrays do not match, the longest array will be used with null values added for missing entries.

as String[]

The output field names for extracted array values.

Default value: The field name of the corresponding array field

Usage

{"flatten": ["foo", "bar"]}

This example flattens the "foo" and "bar" array-valued fields. Given the input data

[
  {"key": "alpha", "foo": [1, 2], "bar": ["A", "B"]},
  {"key": "beta", "foo": [3, 4, 5], "bar": ["C", "D"]}
]

this example produces the output:

[
  {"key": "alpha", "foo": 1, "bar": "A"},
  {"key": "alpha", "foo": 2, "bar": "B"},
  {"key": "beta", "foo": 3, "bar": "C"},
  {"key": "beta", "foo": 4, "bar": "D"},
  {"key": "beta", "foo": 5, "bar": null}
]

Examples

Below are some examples to demonstrate the usage of the flatten transform.

Basic Example

In this example, flatten is used on two fields simultaneously. null values are added to the shorter array.

Advanced Example: Coordinated Views with Nested Time Series

Here, a single field is flattened and then used to plot the line chart corresponding to the circle chart above.