# 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.nected.ai/nected-docs/references/pre-configured-operators/list-operators.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
