Skip To Content

Unnest field

The Unnest field tool returns values stored in array, map, or struct fields as new fields or rows.

Examples

The Unnest field tool can be used in scenarios such as the following:

  • Flatten arrays of values into new rows
  • Return nested properties from a struct or map field as new fields

Parameters

The following table outlines the parameters used in the Unnest field tool:

ParameterDescription

Input dataset

The dataset containing the array, struct, or map field to unnest.

Unnest field

The array, struct, or map field that will be unnested.

Output field name

The name of the field that will contain the unnested array values. This parameter is optional and is only available when the unnest field is of type array.

Output key field name

The name of the field that will contain the unnested map keys. This parameter is optional and is only available when the unnest field is of type map.

Output value field name

The name of the field that will contain the unnested map values. This parameter is optional and is only available when the unnest field is of type map.

Usage notes

Use the Input dataset parameter to select the dataset containing the field you want to unnest.

Use the Unnest field parameter to specify the array, map, or struct field to unnest. The output will contain new rows and fields containing the values from the specified field.

Output field name is optionally available when the field to unnest is of type array. Use this parameter to rename the resulting field containing the unnested values. By default, the output field will be named the same as the input field to unnest.

Output key field name and Output value field name are optionally available when the field to unnest is of type map. Use this parameter to rename the resulting fields containing the unnested keys and values. By default, the output fields will be named the same as the input field name appended with "_KEY" or "_VALUE".

Struct fields will be unnested to new fields with names based on the struct properties.

Outputs

The tool outputs the input dataset containing new rows or fields from the unnested field. The following outlines how each supported field type will be unnested:

  • Array—Array field values will be returned in a field containing a row for each value in the array. The following image is an example of how an input array field will be unnested:

    Example input array values and the resulting new rows from unnesting the values

  • Map—Map field values will be returned in two new fields representing the keys and values in the map. The fields will contain the keys and values, respectively. The following image is an example of how an input map field will be unnested:

    Example input map values and the resulting new rows and fields from unnesting the values

  • Struct—Struct fields will be returned as new fields for each property in the struct. The fields will contain the values for each property. The following image is an example of how an input struct field will be unnested:

    Example input struct values and the result from unnesting the values

Limitations

The tool will only resolve a single level of nesting. For example, if the input field is an array of structs, the output will be new rows containing structs. To unnest the structs, you will need to configure another unnest tool.

Licensing requirements

The following licensing and configurations are required:

  • Creator or Professional user type
  • Publisher, Facilitator, or Administrator role, or an equivalent custom role

To learn more about Data Pipelines requirements, see Requirements.