# Lists

> Count, sort, combine, and clean up lists and records.

Built-in step · 24 steps. Web page: https://docs.lodol.com/docs/integrations/built-in/lists

## Steps

### Add item to end

Add an item to the end of a list.

**Inputs**

- List (`items`, list, required): The list to add the item to.
- Item to add (`value`, object, required): The item to add. A list is added as a single item.

**Outputs**: The list with the item added at the end.

**Example output**

```json
[
  "apples",
  "bananas",
  "cherries"
]
```

### Check if list includes item

Check whether a list includes a specific item.

**Inputs**

- List (`items`, list, required): The list to search.
- Item to check (`value`, object, required): The item to look for. It must match an item exactly.

**Outputs**: Whether the list includes the item.

**Example output**

```json
true
```

### Combine two lists

Merge two lists into one, keeping the items of the first list followed by the items of the second. Leave the second list out to merge the lists inside one list into a single list (flatten).

**Inputs**

- First list (`first`, list, required): The list whose items come first.
- Second list (`second`, list): The list whose items come after the first list's. Leave it empty when the first list holds lists to merge into one, like the results a loop gathered.

**Outputs**: One list: the first list's items followed by the second list's.

**Example output**

```json
[
  "apples",
  "bananas",
  "cherries",
  "dates"
]
```

### Compare two lists

Find what two lists have in common and where they differ: what is only in the first, only in the second, in both, and, for records matched by a field, which ones changed. Handy for keeping two apps in sync.

**Inputs**

- First list (`first`, list, required): One list, like the rows of a spreadsheet.
- Second list (`second`, list, required): The list to compare it with, like an app's contacts.
- Match records by (`field`, text): For lists of records, the field that says two records are the same one, like Email or ID. Letter case and spaces don't matter. Leave empty to compare whole items.

**Outputs**: Four lists: only_in_first, only_in_second, in_both (items from the first list), and changed: each matching pair holding a different value in a field both have, as first, second and the names of the fields that differ.

- `changed` (list): Records in both with a different value in a field both have, each as first, second and fields.
- `in_both` (list): Items both lists have, as the first list holds them.
- `only_in_first` (list): Items only the first list has.
- `only_in_second` (list): Items only the second list has.

**Example output**

```json
{
  "changed": [
    {
      "fields": [
        "plan"
      ],
      "first": {
        "email": "ben@example.com",
        "plan": "pro"
      },
      "second": {
        "email": "ben@example.com",
        "plan": "free"
      }
    }
  ],
  "in_both": [
    {
      "email": "ben@example.com",
      "plan": "pro"
    }
  ],
  "only_in_first": [
    {
      "email": "ana@example.com"
    }
  ],
  "only_in_second": []
}
```

### Count different values

Count how many different values a list holds, or how many different values one field takes, like how many customers placed the orders. Blanks don't count.

**Inputs**

- List (`items`, list, required): The list, or list of records, to count.
- Field (`field`, text): For a list of records, the field to count the different values of, like Customer email. Letter case and spaces don't matter.

**Outputs**: How many different values there are.

**Example output**

```json
12
```

### Count items

Count how many items are in a list.

**Inputs**

- List (`items`, list, required): The list to count the items of.

**Outputs**: The number of items in the list.

**Example output**

```json
3
```

### Create a list

Create a list by entering its items one by one.

**Inputs**

- Items (`items`, list, required): The items to put in the list, in order.

**Outputs**: The new list, with the items in the order entered.

**Example output**

```json
[
  "apples",
  "bananas",
  3
]
```

### Edit a record

Keep only some fields of a record, remove fields, rename them, or merge in another record. Given a list of records, like spreadsheet rows, it edits each one.

**Inputs**

- Record (`record`, text, required): The record, or list of records, to edit.
- What to do (`edit`, text, required): How to change the record. One of: `keep` (Keep only some fields), `remove` (Remove fields), `rename` (Rename fields), `merge` (Merge in another record). Default: `keep`.
- Fields (`fields`, list): The names of the fields, like Name and Email. Use dots to reach inside, like address.city. Only when What to do is Keep only some fields or Remove fields.
- New names (`renames`, object): Each field's current name, and the name to give it. Only when What to do is Rename fields.
- Record to merge in (`other`, text): Its fields are added; where both records have a field, its value is the one kept. Only when What to do is Merge in another record.

**Outputs**: The edited record, or the list of edited records when a list was given.

**Example output**

```json
{
  "email": "ana@example.com",
  "name": "Ana"
}
```

### Filter list

Keep only the items in a list that match a condition, and return them as a new list. Build the condition the same way as an “If” step, referring to the current item as “item”.

**Inputs**

- List (`items`, list, required): The list to filter. The condition reads each item in turn as item.
- Keep item if (`condition`, text, required): Only items for which this is true are kept. Refer to the current item as “item” (for example, item.price is greater than 100).

**Outputs**: The items that meet the condition, in their original order.

**Example output**

```json
[
  {
    "price": 150,
    "sku": "B2"
  },
  {
    "price": 300,
    "sku": "C3"
  }
]
```

### Find item position

Find where an item appears in a list. Returns -1 if it is not found.

**Inputs**

- List (`items`, list, required): The list to search.
- Item to find (`value`, object, required): The item to look for. It must match an item exactly.

**Outputs**: The position of the first matching item, counting from 0, or -1 if the item is not in the list.

**Example output**

```json
1
```

### Get first item

Get the first item of a list. If the list is empty, returns an empty list (shown as “Empty list”).

**Inputs**

- List (`items`, list, required): The list to take the first item from.

**Outputs**: The first item in the list, of whatever type it is, or an empty list if the list has no items.

**Example output**

```json
{
  "email": "ana@example.com",
  "id": 101
}
```

### Get last item

Get the last item of a list. If the list is empty, returns an empty list (shown as “Empty list”).

**Inputs**

- List (`items`, list, required): The list to take the last item from.

**Outputs**: The last item in the list, of whatever type it is, or an empty list if the list has no items.

**Example output**

```json
{
  "email": "ben@example.com",
  "id": 102
}
```

### Get one field from every item

Turn a list of records (spreadsheet rows, orders) into a list of one field's values, such as every row's Amount, so you can total, average or join them.

**Inputs**

- List of records (`items`, list, required): The list of records (objects), such as spreadsheet rows or an earlier step's results.
- Field (`field`, text, required): The name of the field or column to take from every record, for example Amount.

**Outputs**: The field's value from each record, in the same order, with null where a record has no value for it.

**Example output**

```json
[
  "12.50",
  "100",
  null
]
```

### Group items by a field

Sort a list of records into groups that share the same value in one field, such as each owner's tasks. Each group has a key (the shared value), its items, and a count. Text matches ignoring case and spaces; records with a blank value are kept together in a group with a blank key.

**Inputs**

- List of records (`items`, list, required): The list of records (objects) to group.
- Field to group by (`field`, text, required): The name of the field or column whose value decides the group, for example Owner email.
- Also work out (`summary`, text): A figure for each group beside its count, like the total sales for each rep. It is added to each group under its name: total, average, min or max. One of: `none` (Nothing more), `total` (The total), `average` (The average), `min` (The smallest), `max` (The largest). Default: `none`.
- Of the field (`of_field`, text): The field holding the numbers, for example Amount. Only when Also work out is The total, The average, The smallest or The largest.

**Outputs**: One group for each distinct value of the field, in the order the values first appear.

**Example output**

```json
[
  {
    "count": 2,
    "items": [
      {
        "owner": "ana@example.com",
        "task": "Write spec"
      },
      {
        "owner": "ana@example.com",
        "task": "Ship"
      }
    ],
    "key": "ana@example.com"
  },
  {
    "count": 1,
    "items": [
      {
        "owner": "ben@example.com",
        "task": "Review PR"
      }
    ],
    "key": "ben@example.com"
  }
]
```

### Insert item

Add an item at a specific position in a list.

**Inputs**

- List (`items`, list, required): The list to insert the item into.
- Position (`index`, number, required): 0 is the first place, and -1 puts the item last.
- Item to insert (`value`, object, required): The item to insert.

**Outputs**: The list with the item inserted at the position given.

**Example output**

```json
[
  "apples",
  "bananas",
  "cherries"
]
```

### Match records from two lists

Add the fields of the matching record in a second list to each record, like a spreadsheet lookup (VLOOKUP): each order gets its customer's name and plan, matched by email.

**Inputs**

- Records (`first`, list, required): The records to add fields to, like orders.
- Look up in (`second`, list, required): The records to take the fields from, like customers.
- Match by (`field`, text, required): The field the records share, like Email. Letter case and spaces don't matter.
- Field in the second list (`other_field`, text): When the second list names it differently, like Customer email. Leave empty when the name is the same.
- Records without a match (`keep`, text): Keep records that have no match as they are, or leave them out. One of: `all` (Keep them), `matches` (Leave them out). Default: `all`.

**Outputs**: The records, each with the matching record's fields added. A field both records have keeps the first record's value unless it is blank.

**Example output**

```json
[
  {
    "email": "ana@example.com",
    "name": "Ana",
    "order": 1042,
    "plan": "pro"
  }
]
```

### Remove an item

Remove an item from a list wherever it appears.

**Inputs**

- List (`items`, list, required): The list to remove the item from.
- Item (`value`, text, required): The item to remove. Every copy of it is removed.

**Outputs**: The list without the item.

**Example output**

```json
[
  "apples",
  "cherries"
]
```

### Remove duplicates

Remove repeated items from a list, or records that repeat a field, like two rows for one email address. Can also remove empty items.

**Inputs**

- List (`items`, list, required): The list to remove repeated items from.
- Match records by (`field`, text): For a list of records, the field that makes two records the same, like Email. The first of each is kept. Letter case and spaces don't matter. Leave empty to compare whole items.
- Empty items (`remove_empty`, true/false): Keep empty items, or remove them too. Default: `false`.

**Outputs**: The list with repeated items removed, keeping the first of each.

**Example output**

```json
[
  "ana@example.com",
  "ben@example.com"
]
```

### Remove item by position

Remove the item at a specific position in a list.

**Inputs**

- List (`items`, list, required): The list to remove the item from.
- Position (`index`, number, required): 0 is the first item, and -1 is the last.

**Outputs**: The list without the item at the position given.

**Example output**

```json
[
  "bananas",
  "cherries"
]
```

### Reverse list

Reverse the order of items in a list.

**Inputs**

- List (`items`, list, required): The list to reverse.

**Outputs**: The list's items in reverse order.

**Example output**

```json
[
  3,
  2,
  1
]
```

### Shuffle list

Put the items of a list in a random order. Returns all of the items, just reordered.

**Inputs**

- List (`items`, list, required): The list to shuffle.

**Outputs**: The list's items in a random order.

**Example output**

```json
[
  "dee",
  "ben",
  "ana",
  "cy"
]
```

### Sort list

Sort a list in ascending (first/smallest to last/largest) or descending (last/largest to first/smallest) order.

**Inputs**

- List (`items`, list, required): The list to sort. Numbers, and text that holds a number, sort by value, and dates sort by date.
- Direction (`direction`, text): The order to sort in. One of: `ascending`, `descending`. Default: `ascending`.
- Sort records by (`field`, text): For a list of records, the field to sort them by, like Amount or Created. Records without it go last.

**Outputs**: The list's items sorted in ascending or descending order.

**Example output**

```json
[
  3,
  7,
  42
]
```

### Split a list into batches

Split a list into smaller lists of a set size, for an app that takes so many items at a time. Loop over the batches to send each one.

**Inputs**

- List (`items`, list, required): The list to split.
- Items per batch (`size`, number, required): How many items each batch holds. The last may hold fewer. At least 1.

**Outputs**: The batches, each a list, in the original order.

**Example output**

```json
[
  [
    "a",
    "b"
  ],
  [
    "c",
    "d"
  ],
  [
    "e"
  ]
]
```

### Take part of list

Take a section of a list, such as the first five items or the last three.

**Inputs**

- List (`items`, list, required): The list to take a section of.
- Start position (`start`, number, required): This item is included. Use a negative number to count from the end (-1 is the last item).
- End position (`end`, number): This item is not included. Leave blank to go through the end of the list. Use a negative number to count from the end (-1 is the last item).

**Outputs**: The items from the start position up to, but not including, the end position.

**Example output**

```json
[
  "a",
  "b",
  "c"
]
```