# List Helpers

list helpers that help you use advanced array functions to build low code integrations

## Overview

When you are dealing with one or more lists / arrays of data, the List Helpers connector **provides a range of operations to help you manage and manipulate your listed****data as required**.
You can combine data from multiple sources, sort it, extract certain values, find common items, create batches for processing...the "list" goes on!
See our operation summaries below for more ideas and information on your potential list and data manipulation options.

> **Warning:** The List Helpers operations are primarily for dealing with **pre-existing lists** of data coming from other services (via workflow triggers or connectors)
> If you wish to **create a list from scratch** the most common operation to use is the **Append to List** operation found in the [Data Storage](https://tray.ai/documentation/connectors/core/data-storage/) connector.

## List Helper Templates

Below are some relevant templates you may wish to use or learn from. The full range can be found in our [Templates Library](https://tray.io/documentation/templates/).
Templates demonstrate **pre-configured best practices / common use cases** as well as examples of **how to use** this connector and **how best to integrate it** with others.

> **Warning:** **IMPORTANT!** Please make sure you **read the notes and instructional sections on this page before using any of these templates**. A basic understanding of this connector's capabilities will help avoid potential pitfalls during your own build process.

## Important notes

### Your returned items

Note that the List Helper will **always return its results** in the **form of an array INSIDE of an object**.
You will need to form a level of extraction to the results in order play with the array results themselves.

### Data types

Note you can select a number of type formats whenever you are adding an item to a list.
This is not applicable to every property / operation but is very common and great for multiple use cases.
![list-helper-item-type](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-82d3ece0_list-helper-item-type.png)

## Operations

## Add item to list

Allows you to **add an individual item** to a pre-existing list.
Note that the operation doesn't store any data - it just adds to a list and then "forgets" the information.

### Explanation

This will essentially **merge two sets of data** - **a list** and **an** **individual** **item** into one.
The property 'Ensure unique values?' will help make sure there are no duplications.
![list-helper-add-item-to-list](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-bbe254b7_adfadsf.png)
![lh-add-item-output](https://tray.ai/documentation/images/connectors/helper/list-helper/3OaE0vqdAD8eT09IpUBp74_Group%201%20%281%29.png)

> **Info:** **USER TIP:** If you wish to add several items, please see [Add multiple items to list](https://tray.ai/documentation/connectors/helper/list-helper/#add-multiple-items-to-list) below.

## Add multiple items to list

Allows you to **add multiple items** to a pre-existing list

### Explanation

This method essentially merges one data set with **multiple items**.
We recommend that you use the 'Ensure unique values?' property to make sure there are no duplicates.
![list-helper-add-multiple](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-60926019_sdlfyg%201.png)
![list-helper-add-multiple-output](https://tray.ai/documentation/images/connectors/helper/list-helper/6O8RSkwQdVD3ZLYFd8xDGj_Group%202.png)

> **Info:** **USER TIP:** If you wish to join two 'complete' sets of lists together, please see [Concatenate](https://tray.ai/documentation/connectors/helper/list-helper/#concatenate) below.

## Chunk

**Creates smaller list sets** from the original.
You will then need to use the [Loop Connector](#) to loop through each batch (which will often need to be sent to a [sub-processing workflow](https://tray.ai/documentation/platform/processing-data-and-scaling/using-callable-workflows/#processing-large-volumes-of-data) to manage the scale and complexity of your data processing)

### Explanation

Splits a list of items into smaller lists of a **fixed size**.
If the list can’t be split evenly the final chunk will contain the remaining elements.
![list-helper-chunk](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-438a98c7_chunk.png)
![chunk](https://tray.ai/documentation/images/connectors/helper/list-helper/5gh4bPgALhFJitl4DGbGAc_Group%203.png)

## Concatenate

**Joins two lists** together

### Explanation

This will add all of the items from the second list **after** the items from the first list.
![list-helper-concatenate](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-4e863973_lkajsdfhlajds.png)

## Contains

**Checks** your list **for** **specified item**
Returns:

* \*\*True \*\*if found
* \*\*False \*\*if not

### Explanation

**You have to jsonpath an object in order for a truly successful match.**
If you don't your workflow might run without issue but it **could result in a FALSE positive**.
The correct setup would be in reference to an object.
For example if you had two lists and wanted to check if a particular object in list two was present in list one.
![list-helper-contains-1](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-4bfff7eb_asdfad.png)
![lh-contains](https://tray.ai/documentation/images/connectors/helper/list-helper/26DcocjhI8E4wTj0WA6zXf_Group%205.png)

### Important notes

Please read the information provided below before using this operation.

### False positive

When using the string type format simply typing in the word you wish to search for (within a list/ array of objects) will not work.
The image below shows a green run with a `false` result even though `Canada` is clearly displayed within the list.
![list-helper-contains](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-4d213fc1_;alsjdf.png)
![lh-contains-f-positive](https://tray.ai/documentation/images/connectors/helper/list-helper/3wXmdTE1Yx85g2yidmKHGx_Group%206.png)

### Adding Key / Value pairs

If you try and \*\*type in your Key \*\***/ Value pair directly** in typical JSON format - such as `“email”: “l.coleman@rocketmail.com”` - this operation **won't work**.
**Tray.io will escape the quotes** and you **won’t get a match**.

## Count items

**Counts** how many items are in your list

### Explanation

Counts the number of items in any given list.
![list-helper-count-items](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-971293ed_lh-count.png)

## Delete items from list

Allows you to **remove items you specify** from a list

### Explanation

This operation can be used to **delete items that match your specified criteria from a list**.
It r**eturns a whole new list with those items removed**.
In this case all the Key values that contain `A` have been removed. The returned list now starts from `B`.
![list-helper-delete-items](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-fd49bb82_lh-delete-list.png)

## Difference

Allows you to \*\*compare two lists \*\*
**Returns** only the **items that do not exist within the second**

### Explanation

This is particularly useful in situations when you want to **check if your lists have any missing fields or values**.
The **first list** is the **primary** list.
The **second list** should be the list of **items that you would like to filter down (and remove) from the first list**.
The result being a **new list with the aforementioned items removed**.
![list-helper-difference](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-7ecc44da_lh-difference.png)

### Example

Say you have a list of clients in two databases that should have parallel information. You can use **Difference** to check this is so.
The Salesforce list contains four employees. The HubSpot list contains two employees.
Both of the HubSpot empolyees are already within the primary Salesforce list of four.
This is why the **Difference** operation will only return the two employees that remain within the primary Salesforce list. As they are the objects that are 'missing' from the second (HubSpot) list.
![list-helper-difference](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-7ecc44da_lh-difference.png)

### Salesforce list

List of Salesforce Clients from primary database:

```json
\{
 [
  \{
  "id": "sdfgsdfgds",
  "first_name": "Mike"
  \},
  \{
  "id": "kjhagsfjkhg",
  "first_name": "Merve"
  \},
  \{
  "id": "0345rgrgi6AAE",
  "first_name": "Barbabas"
  \},
  \{
  "id": "034ef3r934EwE",
  "first_name": "Clary"
  \}
 ]
\}
```

### HubSpot list

List of HubSpot Clients from second database:

```json
 \{
 [
  \{
  "id": "sdfgsdfgds",
  "first_name": "Mike"
  \},
  \{
  "id": "kjhagsfjkhg",
  "first_name": "Merve"
  \}
 ]
\}
```

### Result list

List of Clients that are missing from the second comparision list (HubSpot):

```json
\{
 [
  \{
  "id": "0345rgrgi6AAE",
  "first_name": "Barbabas"
  \},
  \{
  "id": "034ef3r934EwE",
  "first_name": "Clary"
  \}
 ]
\}
```

> **Info:** **USER TIP**: If you want to create a list of the duplicates found within both lists, use [Intersection](https://tray.ai/documentation/connectors/helper/list-helper/#intersection) instead.

## Filter

Allows you to **filter** your list **for items** for **specific values**

### Explanation

Once the Key is defined you can filter your list for items whose Key / Values match your criteria.
For example here we specified that we wanted to filter for items whose `id` Key contained a `null` Value.
If we wanted to **remove** all objects whose `id` key contained a `null` value, we would change the **'Filter type' **to** 'Exclusive'**.

![list-helper-filter](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-9c6908f8_lh-filter.png)
![lh-in-vs-ex](https://tray.ai/documentation/images/connectors/helper/list-helper/76uiioBv6Y2NpswEDc2HkV_Group%208%20%281%29.png)

## Find object in list

### Explanation

This operation **finds and returns** the very **FIRST object** **that matches the conditions** set.
If **none exist** then **no items** will be returned.
If **more exist they will not be shown in the results**.
![lh-find-object-list](https://tray.ai/documentation/images/connectors/helper/list-helper/7pJpIfArgyVtgR38LNkWaG_dfadsf.png)

### Important notes

Note that **this operation will only return ONE item** from within the original list even if there are multiple objects that meet this criteria

## First

**Returns** the **first item** \*\*found \*\*within your list

### Explanation

Only the first item in a list will be returned.
![list-helper-find-in-list](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-75c31fe9_lh-furst.png)

> **Info:** \*\*USER TIP: \*\*If you wish to return the opposite, please check out the [Last](https://tray.ai/documentation/connectors/helper/list-helper/#last) operation below.

## Get item by index

Allows you to **numerically select** the **item you want to return**

### Explanation

If you know the item number you can pick it out directly from the list.
![list-helper-index](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-aad35550_lh-index.png)

### Important notes

**The count starts from ****`0`****!**
So if you want the fourth item you will need to request the third.

## Get list of page numbers

**Divides** your list **into separate pages**

### Explanation

The total number of items and number of items you want per page will dictate how many pages are returned.
Your r**esults will be in an array format** and **simply list the number of pages created**.
For example if you had 300 records and 100 per page, the list "\[1,2,3]" would be returned.
If you have an **odd number** then a **new page** is created including **the** **remainder**.
![list-helper-page-numbers](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-7c7c876d_lh-pages-listed.png)

## Get unique items by key

Builds a new list of items based on the Key reference

### Explanation

Given a list of items this operation returns a new list which includes the Key referenced.
This operation\*\* automatically excludes duplicates\*\*.
![list-helper-item-by-key](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-6eb8d63c_lh-items-keys%201.png)
![list-helper-item-by-key-1](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-83a6a6f6_Group%209%20%281%29.png)

### Important notes

If there is **more than one item** with the **exact same Key / Value pair** then **only the first item found will be returned**.
For example if multiple items within the original list have `"team"; "Sales"` within their properties only the very first item (with that Key / Value) will be returned in the new list.

## Intersection

For **two given lists** this operation **returns** only the\*\* items that exist in BOTH \*\*lists.

> **Info:** **USER TIP**: If you want to create a list consisting of the unique items found, use [Difference](https://tray.ai/documentation/connectors/helper/list-helper/#difference) instead.

## Iterative transform

Goes through the fields available and **alters them as requested** (capitalize, camelCase etc.)

### Explanation

Given a list of strings this operation goes through each of the items and transforms their values to your preferred format.
It can captialize, change to camelCase etc.
![list-helper-iterative](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-b64de9c8_lzksjdhf.png)

## Join

**Joins** all the list items into a **singular string**

### Explanation

Joins all the items in a list together as a single string. They are separated by a separator type of your choosing.
Remember to include empty spaces if needed.
![list-helper-join](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-bcedd8b2_sfghdkjlk;.png)

## Last

**Returns** the **last item** within a list

### Explanation

Only the final item will be returned.
![list-helper-last](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-60087140_asdfvhgjbknl.png)

> **Info:** \*\*USER TIP: \*\*If you wish to return the opposite, please check out the [First](https://tray.ai/documentation/connectors/helper/list-helper/#first) operation above.

## Pluck

A **list of values** is created from the item property referenced. Useful for extracting e.g. all email addresses for every contact in a list.

### Explanation

The Value of the Key referenced will be found within each list item and returned to you in a new list.
The new list will be in array format.
![list-helper-pluck](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-a6448ef3_asdff.png)

###

## Remove duplicates

Removes all duplicates from a list. Can be used for removing both simple items and objects

### Explanation

Ensures that every item in a list only exists once.
![list-helper-duplicates](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-92671d3c_asgjfdhkl.png)

## Rename keys

Updates the name of a particular field

### Explanation

Renames the Key referenced for all list items.
![list-helper-rename-keys](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-91207d06_fhgjhkl;.png)

###

## Reverse

**Reverses** the **order** of a list

### Explanation

Reverses the order of a list of items.
![list-helper-reverse](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-ec5d6f8f_sdfghj.png)

## Rotate first item

Puts the **first item** in a list **at the bottom**

### Explanation

Takes the first item on the list and automatically puts it at the back.
![list-helper-rotate-first-item](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-352b3db5_sdfghjk,.png)

###

## Simple sort

Sorts a list in **ascending** or **descending** order

### Explanation

Sorts a list of strings and / or numbers into an ascending or descending order.

###

## Slice

Creates a new list based on a **section of your current list**

### Explanation

This returns a new list based on where you specify to start the slicing (inclusive) and where to end (exclusive).

The start and end values are list indexes (the first item in the list has index 0, second item has 1 and so on). Slice gets items from `starting index` up to `end index - 1`
The end index is optional and hence if you don't provide it, you get all elements in the list starting from the start index (inclusive) till the end of the list.
![list-helper-slice](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-8d95ccda_sdfghj.png)

###

## Sort objects

Allows you to put your **items** in **ascending** or \*\*descending \*\*order

### Explanation

Using the property specified this operation sorts the items themselves into either "**ascending**" or "**descending**" order.
![list-helper-sort](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-f95819cd_drftgyhjk.png)

###

## Zip

Takes **two lists and combines them** with key / value pairs created for each item

### Explanation

Takes a list of Keys and a list of Values and combines them.
Returns a single item with corresponding Key / Value pairs.
![list-helper-zip](https://tray.ai/documentation/images/connectors/helper/list-helper/b607e724-cb1a4ab1_dfghjk.png)