> For the complete documentation index, see [llms.txt](https://docs.nected.ai/nected-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nected.ai/nected-docs/references/pre-configured-operators/list-operators.md).
# List Operators
List operators in Nected give you a no-code way to run conditions, comparisons, and calculations on lists in your rule inputs — whether those lists come from a static JSON attribute or from a dynamic data source/API.
They’re useful when your data contains **arrays of objects or values** and you want to check patterns, match specific items, or perform aggregations (sum, average, count, etc.) without writing custom code.
### List Operators in a Gist:
| Operator | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Is Empty** | Returns true if the list has no elements. |
| **Not Empty** | Passes if the list has one or more elements. |
| **Equals** | Returns true if both lists contain the exact same elements in the same order. |
| **Not Equals** | Returns true if the lists differ in any way. |
| **In** | Checks if a value exists within the list. |
| **Not In** | Returns true if the value is not present in the list. |
| **Includes Text** | Checks if the list contains a specific item. |
| **Excludes Text** | Passes if the list does not contain a specific item. |
| **Match All** | Validates if all specified items are present in the list. |
| **Not Match All** | Passes if any specified item is missing from the list. |
| **All Items Match** | Returns true if **every item** in the list meets the defined sub-condition(s). |
| **No Item Match** | Returns true if **none** of the items meet the defined sub-condition(s). |
| **Any Item Match** | Returns true if **at least one** item in the list meets the defined sub-condition(s). |
| **Same Field Values** | Checks if all items have the same value for the selected field; can be set to expect `True` (same) or `False` (not all same). |
| **Distinct Field Values** | Checks if all items have distinct values for the selected field; can be set to expect `True` (all distinct) or `False` (duplicates allowed). |
| **Sum Items** | Sums the values of a numeric field across all (or filtered) list items, then compares the sum to a given number using numeric operators. |
| **Sum Product Items** | Calculates the sum of the product of two numeric fields across all (or filtered) items, then compares to a given number. |
| **Min Items** | Finds the minimum value of a numeric field across list items and compares it to a threshold. |
| **Max Items** | Finds the maximum value of a numeric field across list items and compares it to a threshold. |
| **Avg Items** | Calculates the average value of a numeric field across list items and compares it to a threshold. |
| **Count Items** | Counts the number of list items that meet an optional sub-condition, then compares the count to a given number. |
| **Count Distinct Items** | Counts the number of **unique values** in the selected field across list items (optionally filtered), then compares it to a given number. |
### **When to Use the List Operators?**
List operators are applicable **only** when you’re working with **list attributes** in your rule.\
A **list attribute** is any field in your input data whose value is an array (`[]`).
You can have list attributes in two ways:
1. **Statically** – by adding them directly to your sample input in the rule editor (for example, `order.items` inside a JSON field).
2. **Dynamically** – by fetching them from an external database or API that returns a list field.
For a full guide on adding and managing list attributes, see the [List Input Attributes documentation](https://docs.nected.ai/nected-docs/rules/input-source/list-input-attributes).
Once a list attribute is part of your input, you can use **list operators** to apply logical tests, field comparisons, or aggregate calculations over that list — without looping or writing code.
### **How to Use List Operators?**
Below is the detailed step-by-step process to apply a list operator in your rule:
#### **Step 1 – Select a List Attribute**
In your rule editor (Decision Table or Simple Rule), from the dropdown, choose the field in your input that is a list (e.g., `order.items` or `employeeList`).
* If your list contains objects, you’ll see nested fields when you expand it.
* If it’s a list of primitive values (numbers, strings), the operator will work directly on the list.
#### **Step 2 – Pick a List Operator**
1. Click on the **Operator** dropdown for that row. You can use both common/generic operators and the list operators.
2. Scroll to the **List Operators** section or type the name of the operator in the search bar (e.g., “Sum Items”).
3. Select the operator you need — the UI will change to show relevant configuration fields.
#### Step 3 – Configure List Operators (by category)
After you've selected the operators, here's a generic step to configure that operator:
1. **Fill Required Fields**
1. Depending on the operator, provide the necessary parameters:
1. **Filter Key** – choose a specific field within each list item (for Field-Value and Aggregate operators).
2. **Op** – select the comparison type (numeric, boolean, or string, depending on operator).
3. **Value** – enter the number, string, or boolean to compare against (if required).
4. **Multiple Filter Keys** – for Sum Product Items, select two numeric fields.
2. **Configure the Sub-Condition (Mandatory for Certain Operators)**
1. If the operator shows a **`condition_x`** link, click it to open the mini rule builder.
2. Define at least one condition for filtering items (even if it’s a pass-all condition like “id Is Not Null”).
3. Set **Property**, **Op**, **Value**, and combine rules with the **Any/All** toggle or **Add Group** for nested logic.
Below are all list operators you can pick in the Operator dropdown, grouped by how they behave. For each group you’ll see: what fields the UI asks for, how to fill them, and a small pseudocode example.
**A) Basic List operators**
**Operators:** `Is Empty`, `Not Empty`, `Equals`, `Not Equals`, `In`, `Not In`, `Includes Text`, `Excludes Text`, `Match All`, `Not Match All`
**What the UI asks for ?**
* **Is Empty / Not Empty**: no extra values.
* **In / Not In / Includes Text / Excludes Text**: one value.
* **Match All / Not Match All**: multiple values.
* **Equals / Not Equals**: a list value to compare (or a token reference).
**How it works ?**
* **Is Empty / Not Empty**: checks length of the list.
* **Equals / Not Equals**: compares two lists (order‑sensitive).
* **In / Not In**: checks whether a **single value** is a member of the list.
* **Includes Text / Excludes Text**: checks presence/absence of a **single** item in the list.
* **Match All / Not Match All**: verifies whether **all** of the specified values are in the list (or not).
How to Use Basic List Operators?
These operators are straightforward and require minimal configuration. Here’s the typical flow:
* **Select your list attribute** in the left-hand column (either a static list or one coming from a data source).
* **Pick the operator** from the **List** category — e.g., *Is Empty*, *Not Empty*, *In*, *Includes Text*, etc.
* **Provide values (if required)**:
* Operators like **Is Empty** or **Not Empty** need **no value** — they simply check the list's state.
* Operators like **In**, **Not In**, **Includes Text**, **Excludes Text**, **Match All**, **Not Match All**, **Equals**, and **Not Equals** require you to enter one or more values to check against the list contents.
* **Run or test your rule** to validate that the condition matches your expectations.
{% hint style="success" %}
All the next three operator types — *Item-Level Match Operators*, *Field-Value Consistency Operators*, and *Aggregate Operators* — support **additional filtering conditions**. This lets you apply the operator **only to items that meet specific criteria** before the main evaluation runs. Using this filter smartly can make your rules far more precise.
{% endhint %}
**B) Match Operators**
**Operators:** `All Items Match`, `Any Item Match`, `No Item Match`
**What the UI asks for?**
These do not ask for a numeric field or value.\
You’ll see a **`condition_x`** link with a pencil icon. Clicking it opens the **mini rule builder** for a **mandatory sub-condition** that is applied to each item of the list.\
Inside the mini rule builder, you must set:
* **Property** – the item field to check (e.g., `weight`, `status`).
* **Op** – comparison operator (e.g., `Equals`, `Greater than`).
* **Value** – comparison value.
* **Any/All toggle** – choose how multiple sub-rules are combined (**Any** = OR, **All** = AND).
* **Add Group** – create nested AND/OR logic if needed.
{% hint style="info" %}
**Note:** If you truly want to evaluate *all items* in the list without filtering, you still need to add at least one sub-rule that will always pass (e.g., `id` **Is Not Null**). This is because the sub-condition is required.
{% endhint %}
**How it works**
* **All Items Match**: true if **every** item in the list satisfies the sub‑condition.
* **Any Item Match**: true if **at least one** item satisfies the sub‑condition.
* **No Item Match**: true if **none** of the items satisfy the sub‑condition.
How to Use Item-Level Match Operators?
* **Select your list attribute** from the left-hand column.
* **Choose one of the match operators** from the List category.
* A `condition_` link with a pencil icon will appear. Click it to open the **mini rule builder**.
* **Define the sub-condition** for each item:
* Pick the **item property** (e.g., `weight`).
* Choose the comparison operator (e.g., `Greater than`).
* Enter the value to compare (e.g., `10`).
* Save the sub-condition — the operator now evaluates whether:
* **All Items Match** → every item satisfies the condition.
* **Any Item Match** → at least one item satisfies the condition.
* **No Item Match** → no items satisfy the condition
{% hint style="info" %}
These operators also expose `value` and matchItem index. The token `value` shows how many values from the input actually got matched. Its useful, if you want to draw an analysis based on the total matched item numbers.
{% endhint %}
**C) Same/Distinct Field Operators (New)**
**Operators:** `Same Field Values`, `Distinct Field Values`
* **Select filter key (field)** – pick the item field to check (e.g., `height`, `length`).
* **Op (Boolean)** – choose `Is True` or `Is False` depending on the desired check.
* **`condition_x`** – opens the **mini rule builder** for a **mandatory sub-condition** applied to items before checking sameness or distinctness.
Inside the mini rule builder, you must set:
* **Property**, **Op**, **Value** (same as in Match Operators).
* **Any/All toggle** to combine sub-rules.
* **Add Group** for complex logic.
{% hint style="info" %}
**Note:** To check the field values across *all items* with no filtering, add a sub-rule that always passes (e.g., `id` **Is Not Null**).
{% endhint %}
**How it works**
* **Same Field Values**
* `Is True` → all items have exactly the same value in the chosen field
* `Is False` → not all items share the same value
* **Distinct Field Values**
* `Is True` → all items have different values in the chosen field
* `Is False` → there is at least one duplicate
How to Use Field-Value Consistency Operators?
1. **Select your list attribute** from the left-hand column.
2. **Choose the operator** from the List category.
3. Select the **field** from each item to evaluate (e.g., `category`).
4. Set **Op** to `Is True` or `Is False`:
* For *Same Field Values*: `Is True` means all values match; `Is False` means at least one differs.
* For *Distinct Field Values*: `Is True` means all values are unique; `Is False` means duplicates exist.
5. (Optional) Add a sub-condition via `condition_` to filter which items are included in the che
**D) Aggregate Operators**
**Operators:** `Sum Items`, `Sum Product Items`, `Min Items`, `Max Items`, `Avg Items`, `Count Items`, `Count Distinct Items`
**What the UI asks for?**
1. **Select filter key**\
The numeric field to aggregate across items (e.g., `weight`, `price`, `score`).
1. For **Sum Items**, pick a single numeric field.
2. For **Sum Product Items**, pick exactly two numeric fields (displayed as tokens separated by the multiplication symbol `×`). The product of these two fields is computed for each item, and then summed across all items in scope.
3. For **Min Items**, **Max Items**, and **Avg Items**, pick one numeric field to evaluate.
4. For **Count Distinct Items**, pick the field whose unique values you want to count.
2. **Op (numeric comparison)**\
Select how to compare the computed aggregate result to your threshold. Available options are:
1. `Equals` – result exactly matches the threshold.
2. `Not Equals` – result is different from the threshold.
3. `Greater than` – result is strictly larger than the threshold.
4. `Less than` – result is strictly smaller than the threshold.
5. `Greater than or equals` – result is larger than or exactly equal to the threshold.
6. `Less than or equals` – result is smaller than or exactly equal to the threshold.
3. **Enter value**\
Specify the numeric threshold for the comparison. For example:
1. *Sum Items*: Sum of `weight` < `500`.
2. *Avg Items*: Average `score` >= `4`.
3. *Count Distinct Items*: Count of unique `customerId` <= `50`.
4. **Sub-condition:**\
Click the **`condition_x`** link to open the mini rule builder. Here you define which list items are included in the aggregation. You **must** create at least one sub-condition — even if you want to include all items. In that case, add a rule that always passes (e.g., `id` **Is Not Null**).
Inside the mini rule builder, set:
* **Property** – the item field to check (e.g., `status`, `length`, `category`).
* **Op** – choose the comparison operator (e.g., `Equals`, `Greater than`).
* **Value** – the value to compare against.
* **Any/All toggle** – choose **Any** (OR) or **All** (AND) for multiple conditions.
* **Add Group** – create nested AND/OR groupings for more complex logic.
**How it works**
* The operator computes a numeric result across items (sum/min/max/avg/count).
* That computed number is compared to the threshold using the chosen numeric operator.
* Row evaluates to **true/false** based on that comparison.
* These operators also expose a numeric **`value`** (the computed number) and may expose other helper outputs; see the Results section.
How to Use Aggregate Operators?
1. **Select your list attribute** from the left-hand column.
2. **Choose an aggregate operator** from the List category.
3. Select the **numeric field** to aggregate (e.g., `weight`).
* For *Sum Product Items*, select two or more numeric fields to multiply per item before summing.
4. Choose a **numeric comparison operator** (`Equals`, `Greater than`, etc.).
5. Enter the **threshold value** to compare against.
6. (Optional) Add a sub-condition via `condition_` to filter items before aggregation.
#### **Step 4 – (Optional) Add a Sub-Condition Filter**
* For many aggregation operators (`Sum Items`, `Count Items`, etc.), there is an **optional** sub-condition link.
* This lets you run the aggregation only on list items that meet certain criteria (e.g., only count items where `status = "active"`).
#### **Step 5 – Test the Rule**
* After setting up the operator, add your return/action value in the **Result** column.
* Click **Test Rule** and provide a sample input containing the list data.
* Review the test output — for numeric operators, check the computed `value`; for boolean/matching operators, check if the pass/fail result matches expectations.
Perfect catch—thanks. You’re right: the **result outputs** shouldn’t be buried inside the setup steps, and they’re **only** available for the **new list operators**. Here’s a clean standalone section you can drop in after the “How to use” part.
Here’s the rewritten section so **all output tokens are introduced right at the top**, `inputData` is included, and the structure is more reader-friendly:
### Results from List Operators
When you use the **new list operators** (introduced in the latest release), Nected exposes **extra result tokens** that you can use to reuse the operator’s computation downstream without recalculating it.
These tokens are available both:
* **Inside sub-conditions** (for filtering logic)
* **In the Result column** (only for result types: **List**, **JSON**, **JS**, and **Formula**)
**Available Tokens**
| Token | Type | Description | Example |
| ------------------------------ | ------- | -------------------------------------------------------------------------------- | ---------------------------------------- |
| `{{condition_x}}` | boolean | True/false result of the operator row. | `{{condition_4}}` |
| `{{condition_x.inputData}}` | list | List of items passed into the operator **after** the sub-condition filter. | `{{condition_4.inputData[0].age}}` |
| `{{condition_x.matchedItems}}` | list | List of items that matched the operator’s check (match/sameness operators only). | `{{condition_6.matchedItems[0].weight}}` |
| `{{condition_x.value}}` | number | Computed numeric result (aggregate operators only). | `{{condition_4.value}}` |
***
**Applies to New Operators Only**
* **Match Operators** → All Items Match, No Item Match, Any Item Match
* **Field-Value Consistency Operators** → Same Field Values, Distinct Field Values
* **Aggregate Operators** → Sum Items, Sum Product Items, Min Items, Max Items, Avg Items, Count Items, Count Distinct Items
> Old list operators (e.g., Is Empty, Not Empty, Includes Text, Equals) return **only** a boolean pass/fail and do not expose these tokens.
***
**1) `inputData` — all new operators**
The **filtered list of items** that the operator processed.
* **In sub-conditions:** lets you reference the processed items for further filtering.
* **In results:** available in **List**, **JSON**, **JS**, and **Formula** result types.
```handlebars
{{condition_4.inputData}} # full list
{{condition_4.inputData[0]}} # first item (object or primitive)
{{condition_4.inputData[0].price}} # field from the first object item
```
***
**2) Boolean pass/fail — all new operators**
The row-level true/false based on your configuration. Usually not referenced directly — drives the row’s hit/miss logic.
```handlebars
{{condition_4}} # true or false
```
***
**3) `matchedItems` — match & sameness operators only**
The list of items that met the sub-condition or were included in sameness/distinctness checks.
```handlebars
{{condition_6.matchedItems}} # full list
{{condition_6.matchedItems[0]}} # first matched item
{{condition_6.matchedItems[0].weight}} # field from first matched object
```
***
**4) `value` — aggregate operators only**
The computed numeric result. The boolean row result comes from comparing this value against your configured threshold.
```handlebars
{{condition_4.value}} # e.g., 480
```
**Example Uses in the Result Column**
**Sum Items (cart total you also want to output):**
```
Field: cart.items → Sum Items of price
Comparison: Less than 500
Result: "total": {{condition_4.value}} # e.g., 480
```
**Count Items (count active employees):**
```
Field: employees → Count Items where status == "active"
Comparison: Greater than 10
Result: "activeCount": {{condition_6.value}} # integer
```
**Any Item Match (return first delayed order ID):**
```
Field: orders → Any Item Match where status == "delayed"
Result: "firstDelayedId": {{condition_7.matchedItems[0].id}}
```
***
### Notes & gotchas
* **Only new operators** expose `matchedItems` and/or a numeric `value`. Old operators are boolean-only.
* If you set a **sub-condition**, `matchedItems` reflects the items that passed that sub-condition (the list you operated on).
* For **lists of primitives**, the picker shows `index[n]` and `value` helpers for easy extraction (as in your screenshot). For **lists of objects**, dot into fields via `matchedItems[n].field`.
* The `value` from aggregates is **just the computed number**; it doesn’t carry the comparison. Use it freely in outputs or further calculations.
