Skip to content
Nappai Documentation

Flatten By Key

The Flatten By Key component helps you organize messy data by turning lists into individual rows. Imagine you have a table where one column contains a list of items (like a shopping list or a list of tags). Instead of keeping that list in one cell, this component breaks it apart. It creates a new, separate row for every item in that list, while keeping the rest of the information from the original row attached to each new item. This makes it much easier to analyze, sort, or filter your data later.

How it Works

This component works like an unpacker. It looks at your data table and finds specific columns that contain lists or arrays.

  1. Identification: You tell the component which column contains the lists you want to expand (the “Key”).
  2. Expansion: For every single row in your input data, the component looks at that list.
  3. Creation: It creates a new row for each item inside that list.
  4. Copying: It copies the other information from the original row (like names, dates, or IDs) and attaches it to each of the new rows.

For example, if you had one row with a list of 3 products, the output will be 3 separate rows, each showing one of those products along with the other details from the original row.

Connection & Credentials

This component does not require any external credentials or API connections. It processes data directly within the Nappai workflow using the tables you provide.

Operations

This component does not have separate operations. It performs a single, continuous transformation process on the data provided.

Inputs

The following fields are available to configure this component.

  • Data: The source table or records containing the data you want to process. Each record should contain the key specified below.
  • Key to Flatten: The name of the field (column) that contains a list or array that you want to expand. Each item in this list will become a separate record in the output.

Outputs

  • Flattened Data: The resulting table where lists have been expanded into individual rows. This output can be connected to other components for further analysis, filtering, or database insertion.

Output Data Example (JSON)

Here is an example of how the data looks after being processed. Notice how the original single row with a list has become two separate rows. json [ { “customer_id”: 101, “customer_name”: “Alice”, “item”: “Apple”, “category”: “Fruit” }, { “customer_id”: 101, “customer_name”: “Alice”, “item”: “Banana”, “category”: “Fruit” } ]

In this example, the original data likely had a row for “Alice” with a list ["Apple", "Banana"]. The component has split this into two rows, preserving Alice’s ID and Name for both items.

Connectivity

This component is typically used in the middle of a data preparation workflow.

  • Connect To: You can connect the Flattened Data output to components that require detailed, row-by-row analysis, such as filtering components, calculation tools, or database writers.
  • Connect From: It usually receives data from data sources (like spreadsheets, databases, or APIs) that return nested lists or arrays.

Usage Example

Scenario: You are importing a list of orders where each order contains multiple products in a single field called products_list.

  1. You use a Read Data component to pull order information into the workflow.
  2. You connect this to the Flatten By Key component.
  3. In the Key to Flatten field, you select products_list.
  4. The output is now a list where each row represents a single product from an order, making it easy to calculate the total value of each individual item or tag them with specific details.

Tips and Best Practices

  • Check for Empty Lists: If a row has an empty list in the key field, the behavior may vary (often resulting in no output for that specific row). Ensure your data is clean before flattening.
  • Metadata Preservation: The component automatically preserves other fields (like IDs or timestamps) from the original row. You do not need to manually copy these; they are carried over to every new row created.
  • Performance Awareness: Flattening large lists can significantly increase the number of rows. If you are working with very large datasets, be aware that this may increase processing time and memory usage.

Security Considerations

This component operates locally within the Nappai automation environment. It does not transmit data to external third-party services, ensuring that your data remains within your controlled workflow environment. Ensure that the source data provided does not contain sensitive information that you wish to keep confidential, as the flattened output will be accessible to subsequent components in the workflow.