Group Data By Key

Group Data By Key is a simple tool in Nappai that lets you organize a list of records into groups based on a chosen column. Think of it like sorting a stack of cards into piles by the card’s suit or by a customer’s region. Once grouped, you can format each group’s content the way you want and add extra information (metadata) that will travel with the group.

How it Works

The component takes a list of data records (each record is a small “Data” object).

Choose a key column – the column whose value will define each group (e.g., “Region” or “Category”).
Optional metadata columns – you can list extra columns that should be copied into every record of the group.
Template – a text pattern that tells the component how to turn each record into a string. The template can use placeholders like {text}, {data}, or any other field name from the record.
Separator – the character(s) used to join the formatted strings of all records in a group (default is a newline).

The component loops through every record, formats it with the template, collects the metadata, and groups the formatted strings under the same key. Finally, it outputs a new list of Data objects, one per group, containing:

id: a normalized version of the key (lower‑case, spaces replaced with underscores).
text: all formatted strings for that group joined by the separator.
The original key column value.
Any selected metadata columns.

If the result contains more than 1,000 groups, only the first 1,000 are returned to keep the dashboard responsive.

Inputs

Data: The data to group.
Key Column: The column to group by.
Metadata keys: Comma separated list of metadata columns to be added to the document.
Separator: The separator used when joining the formatted strings of each group.
Template: The template to use for formatting the data. It can contain the keys {text}, {data} or any other key in the Data.

Outputs

Processed Data: A list of Data objects, each representing one group. Each object contains the grouped text, the key column value, and any selected metadata.

Usage Example

Connect a data source (e.g., a CSV reader or database query) to the Data input.
Set Key Column to the column you want to group by, such as Region.
(Optional) Enter CustomerID,OrderDate in Metadata keys if you want those fields copied into each group.
Leave Separator as the default newline or change it to ; if you prefer.
In Template, type:
```
Order ID: {OrderID} – Amount: {Amount}
```
This will format each record in the group.
Run the workflow. The Processed Data output will contain one Data object per region, with all orders listed together.

You can then feed this output into a summarization component, a report generator, or any other part of your automation flow.

Filter Data – Select a subset of records before grouping.
Summarize Text – Create a summary of the grouped text.
Create Document – Turn the grouped data into a PDF or Word file.
Send Email – Email the grouped report to stakeholders.

Tips and Best Practices

Keep the Template simple; complex logic should be handled by a separate component.
Use a clear Key Column that has distinct values to avoid unintentionally merging records.
If you need to preserve the original order of records, add an index column and include it in the template.
For large datasets, consider filtering first to reduce the number of groups and keep performance high.
Test the separator choice: a newline is great for readability, but a comma or pipe may be better for CSV exports.

Security Considerations

The component processes data locally; no external APIs are called.
Ensure that any sensitive fields you include in Metadata keys are handled according to your organization’s data‑privacy policies.
If the data contains personally identifiable information (PII), consider masking or encrypting it before passing it to downstream components.