> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/filter-shape/using-list-or-list-length-to-filter-json-arrays.md).
# Using list or list length to filter JSON arrays
## Introduction
There may be times when you need to define filters based on items in an array field. You can define [list type](#the-list-filter-type) filters to match records based on array field values and/or [list length](#the-list-length-filter-type) filters to match records based on the number of items in an array.
## The list filter type
The `list` filter type matches records based on array field values. Here, you choose which array `field` (within incoming payloads) to filter, followed by:
* An `operator` , to determine how given values should be compared for matching
* The expected `value type` of values received in this array
* Required list items (i.e. array values to be used for matching)
For example:
### Value types, operators & options
Like any other filter, a `list` type filter is defined using value types and operators, summarised below:
Operator
Value type
Other available options
Contains
string, integer, float
-
Does not contain
string, integer, float
-
Equals
string, integer, float
Match order?
Not equals
string, integer, float
Match order?
If the exact order of array field values is important for matching, you should use the `equals` or `not equals` operator and toggle the `match order?` option to `on`.
When multiple list items are defined, you can set the logic to:
* AND (so a record must match all defined values)
* OR (so a record can match one or more defined values)
### Examples
Consider the JSON payload below:
```json
[
{
"name": "John",
"fruit": ["apples", "pears", "oranges"]
},
{
"name": "George",
"fruit": ["pears", "oranges", "apples"]
},
{
"name": "Ringo",
"fruit": ["raspberries", "pears", "grapes"]
},
{
"name": "Paul",
"fruit": ["apples"]
}
]
```
#### Example 1
Match records where the `fruit` field value contains `apples` OR `pears` anywhere in the array. The input would be:
Output would be:
{% code overflow="wrap" %}
```json
[
{"name":"John","fruit":["apples","pears","oranges"]},
{"name":"George","fruit":["pears","oranges","apples"]},
{"name":"Ringo","fruit":["raspberries","pears","grapes"]},
{"name":"Paul","fruit":["apples"]}
]
```
{% endcode %}
#### Example 2
Match records where the `fruit` field value contains exactly `apples` AND `pears` AND `oranges` in this sequence. The input would be:
Output would be:
```json
[{"name":"John","fruit":["apples","pears","oranges"]}]
```
#### Example 3
Match records where the `fruit` field value is equal to `apples` AND `pears` AND `oranges` in ANY sequence. The input would be:
Output would be:
{% code overflow="wrap" %}
```json
[
{"name":"John","fruit":["apples","pears","oranges"]},
{"name":"George","fruit":["pears","oranges","apples"]}
]
```
{% endcode %}
## The list length filter type
The `list length` filter type matches records based on the number of values in an array field. Here, you choose which array `field` (within incoming payloads) to filter, followed by:
* An `operator` , to determine how given values should be compared for matching
* Value (the number of array items to match)
For example:
### Value types, operators & options
The `list length` filter type expects a numeric value - as such, the following operators are available:
| Operator |
| ------------------ |
| `Contains` |
| `Does not contain` |
| `Equals` |
| `Not equals` |
### Examples
Consider the JSON payload below:
```json
[
{
"name": "John",
"fruit": ["apples", "pears", "oranges"]
},
{
"name": "George",
"fruit": ["pears", "oranges", "apples"]
},
{
"name": "Ringo",
"fruit": ["raspberries", "pears", "grapes"]
},
{
"name": "Paul",
"fruit": ["apples"]
}
]
```
#### Example 1
Match records where the `fruit` field value is GREATER THAN `2` . The input would be:
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/filter-shape/using-list-or-list-length-to-filter-json-arrays.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.