Nest By Operator

Overview

Nesting arrays is a simple concept of nesting an array inside another array. You can think of it like Russian nesting dolls, where one doll fits inside a larger one. The largest doll is the parent, and the smaller ones are the children. The Nest By operator lets you create a nested table (array of objects) in the connected parent table. You'll configure the operator with a parent key that'll remain un-nested for each row. You'll then provide a child name key where your new nested array will exist. This configuration will let you group rows of data by a parent key value. For instance, you can nest by a parent key that has the same value across multiple rows. All rows with the same parent key value will group together into one row. The remaining fields will nest as individual rows in the same child name array.

NOTE  Keys that are not consistent across all arrays will be dropped, which can result in data loss.

You'll find the Nest By operator under the Table group to the left of the Data Workflow canvas.

What You'll Learn

In this article, you'll learn:

About the Info Window

Here's what the Nest By operator looks like, along with its Info window:

And here's a breakdown of each setting in the Info window:

Setting Description

Category

Grayed out and non-adjustable setting indicating the operation type.

Label

Sets the label for your operator. The label you enter here shows beneath your operator on your Data Workflow canvas.

This field is optional, but set a label if you use more than one of the same operator type. A label helps you identify your operators without opening any Info windows.

Parent Keys

The Parent Key is how you'll group your information. The nested array will contain as many rows as keys are sharing the Parent Key value. All rows with the same Parent Key value will group into one row. All values except the Parent Key will nest as an array under the Child Name you configure for the operator.

You can also provide more than one Parent Key. This means that rows must match both keys to become nested.

Child Name

This is the key name of the nested array that you're creating. You'll see this Child Name carried through into the DevTools Console. Without a Child Name, it's difficult to find your nested array in the DevTools Console.

Adding a Nest By Operator

In this use case, you'll use the Nest By operator to group by the duplicate account numbers in your Data Table. You'll do this by setting the table's account number as the operator's key.

Here's how the completed use case will look in the Module Builder:

Here's how the completed use case will work in Express View, including a peek at the DevTools Console:

What You’ll Need

To set up this use case, you’ll need:

  • 1 Data Table component

  • 1 Button component

  • 1 Data Workflow component

To set up your Data Workflow, you’ll need:

  • 1 Input operator

  • 1 Nest By operator

  • 1 Console operator

NOTE  These instructions assume you have a module open, saved, and with a title.

Configure the Data Table Component

First, you'll set up a Data Table with a list of customers, account values, and account numbers.

1. In the Module Builder, drag and drop a Data Table component onto your canvas.
2. Enter dtAccountInfo in the Label and Property Name fields.
3. In the data table, enter the following:

accountNumber

 firstName

lastName

 accountValue

12345

Josephine

Darakjy

543891

12346

Lenna

Paprocki

1000000

12346

Sage

Wieser

1000000

12347

Abel

Maclead

7432572

12348

Ernie

Stenseth

5000000

12349

Valentine

Gillian

5439294

12346

Dyan

Oldroyd

17890

12347

Fatima

Saylors

19578

12347

Willow

Kusko

54389

NOTE  You purposely added duplicate information to show the power of the Nest By operator.

4. Click Save.

Configure the Button Component

To trigger the Data Workflow, you'll add a Button component.

1. Drag and drop a Button component onto your canvas. Place your Button component below your Data Workflow component.
2. Enter btnNestByNumber in the Property ID field.
3. Enter Nest by Account Number in the Label Text field.
4. Select Event as the Action Type.
5. Enter dwfNestByNumber in the Trigger on Click field.

6. Click Save.

Configure the Data Workflow Component

Now you'll set up your Data Workflow to input and nest information from your Data Table.

1. Drag and drop a Data Workflow component onto your canvas. Place your Data Workflow below your Data Table component.
2. Enter dwfNestByNumber in the Canvas Label Text and Property Name fields.

Configure the Input Operator

1. Drag and drop an Input operator onto your Data Workflow canvas.
2. Configure the Input operator's Info window as follows:
Setting Value

Category

Input

Component

dtAccountInfo

Required

No

Source

Default

Configure the Nest By Operator

1. Drag and drop a Nest By operator onto your Data Workflow canvas.
2. Configure the Nest By operator's Info window as follows:
Setting Value

Category

Nest By

Label

Nest by accountNumber

Parent Keys

accountNumber

Child Name

account
3. Connect the output port (right) of the Input operator to the input port (left) of the Nest By operator.

Configure the Console Operator

1. Drag and drop another Console operator onto your Data Workflow canvas.
2. Configure the Console operator's Info window as follows:

Setting

Value

Category

Console

Label

Nest by Account Number
3. Connect the output port (right) of the Nest By operator to the input port (left) of the Console operator.
4. Click Save.
5. Save your module.

Preview your module in Express View, and open the DevTools Console. Click your button and you'll see the 9 table rows now grouped into 5 rows. Each new array now has the Child Name of account. You can also see these new arrays are nested together by accountNumber.

Changing a Nest By Operator’s Settings

You can revisit and make changes to this operator.

1. Click the Data Workflow component.

A 5-button toolbar displays above the component on hover-over.

2. Click the (Settings) button to open the Data Workflow canvas.
3. Click the operator to open its Info Window.
4. Make changes to the operator's settings as needed.
5. Click Save.
6. Save your module.

Copying a Nest By Operator

You can make a copy of your operator using familiar keyboard settings. You can copy and paste an exact copy of your operator, matching all settings.

1. Hover over the Data Workflow component.

A 5-button toolbar displays above the component on hover-over.

2. Click the (Settings) button to open the Data Workflow canvas.
3. Click the operator you want to duplicate.
4. On your keyboard, press Command + C (Mac OS) or Ctrl + C (Windows/Linux) to copy the operator.

TIP  You can copy more than one operator at a time. Hold Command or Ctrl on your keyboard and click all the operators you want to copy. Follow the rest of the steps as usual.

5. On your keyboard, press Command + V (Mac OS) or Ctrl + V (Windows/Linux) to paste the copied operator(s) to the Data Workflow canvas.
6. Click Save.
7. Save your module.

TIP  Did you know you can copy an operator and paste it into a different Data Workflow? You'll use the same steps outlined above.

Removing a Nest By Operator

Lastly, you can delete this operator from your Data Workflow canvas. You can also use these same steps to delete a connection between two operators.

1. Hover over the Data Workflow component.

A 5-button toolbar displays above the component on hover-over.

2. Click the (Settings) button to open the Data Workflow canvas.
3. Click the operator you want to delete.
4. On your keyboard, press Delete.

NOTE  Once you delete this operator, make sure to connect your remaining operators. If your Data Workflow path doesn't end with an Output or Console operator, your Data Workflow won't work. So, once you delete an operator, make sure to update any remaining paths to end at an Output or Console operator.

5. Click Save.
6. Save your module.

Lab

You can view this complete use case here: https://training.unqork.io/#/form/6054dbf44cf09403450f91de/edit.