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:
| Parameter | Description |
|---|---|
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:
- 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:
- 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:
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.