List Connector
The List Connector provides a comprehensive set of list/array operations for filtering, sorting, pagination, aggregation, and transformation.
Using Context Variables
When using context variables with LiquidJS templates, arrays require special handling.
Important: Do not wrap array variables in quotes. Use the| jsonfilter to properly serialize them.
❌ Incorrect - Produces [object Object] strings:
{
"list": "{{ context.data.items }}",
"match": { "active": true }
}✅ Correct - Use | json filter without quotes:
{
"list": {{ context.data.items | json }},
"match": { "active": true }
}General rule for LiquidJS templates in connector configs:
| Variable Type | Syntax | Example |
|---|---|---|
| String | "{{ variable }}" | "separator": "{{ context.delimiter }}" |
| Array/Object | {{ variable | json }} | "list": {{ context.items | json }} |
| Number | {{ variable }} | "page": {{ context.currentPage }} |
| Boolean | {{ variable }} | "precise": {{ context.usePrecise }} |
Operations
Initialization
empty
emptyCreates an empty list.
Parameters
None.
Examples
// Input
{ "operation": "empty", "data": {} }
// Output
{ "result": [] }of
ofCreates a list from provided items.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
items | array | No | [] | The items for the list |
Examples
// Input
{ "operation": "of", "data": { "items": [1, 2, 3, 4, 5] } }
// Output
{ "result": [1, 2, 3, 4, 5] }// Input with objects
{ "operation": "of", "data": { "items": [{ "name": "Alice" }, { "name": "Bob" }] } }
// Output
{ "result": [{ "name": "Alice" }, { "name": "Bob" }] }range
rangeCreates a list of numbers within a specified range.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
start | number | No | 0 | The start of the range |
end | number | Yes | - | The end of the range (exclusive) |
step | number | No | 1 | The increment between values |
Examples
// Input
{ "operation": "range", "data": { "start": 0, "end": 5 } }
// Output
{ "result": [0, 1, 2, 3, 4] }// Input with step
{ "operation": "range", "data": { "start": 0, "end": 10, "step": 2 } }
// Output
{ "result": [0, 2, 4, 6, 8] }// Input with non-zero start
{ "operation": "range", "data": { "start": 5, "end": 10 } }
// Output
{ "result": [5, 6, 7, 8, 9] }Basic Operations
push
pushAdds one or more items to the end of a list.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
item | any | No | - | A single item to add |
items | array | No | - | Multiple items to add |
Examples
// Add single item
{ "operation": "push", "data": { "list": [1, 2, 3], "item": 4 } }
// Output
{ "result": [1, 2, 3, 4] }// Add multiple items
{ "operation": "push", "data": { "list": [1, 2, 3], "items": [4, 5, 6] } }
// Output
{ "result": [1, 2, 3, 4, 5, 6] }concat
concatConcatenates two lists together.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The first list |
other | array | No | [] | The second list |
Examples
// Input
{ "operation": "concat", "data": { "list": [1, 2, 3], "other": [4, 5, 6] } }
// Output
{ "result": [1, 2, 3, 4, 5, 6] }slice
sliceExtracts a portion of a list.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
start | number | No | 0 | Start index (inclusive) |
end | number | No | list length | End index (exclusive) |
Examples
// Input
{ "operation": "slice", "data": { "list": [1, 2, 3, 4, 5], "start": 1, "end": 4 } }
// Output
{ "result": [2, 3, 4] }// Slice from index to end
{ "operation": "slice", "data": { "list": [1, 2, 3, 4, 5], "start": 2 } }
// Output
{ "result": [3, 4, 5] }Query Operations
get
getGets an item at a specific index. Supports negative indexing.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
index | number | No | 0 | The index (-1 for last, -2 for second last, etc.) |
Examples
// Get by index
{ "operation": "get", "data": { "list": [10, 20, 30, 40, 50], "index": 2 } }
// Output
{ "result": 30 }// Negative indexing
{ "operation": "get", "data": { "list": [10, 20, 30, 40, 50], "index": -1 } }
// Output
{ "result": 50 }first
firstGets the first item in a list.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
Examples
// Input
{ "operation": "first", "data": { "list": [1, 2, 3] } }
// Output
{ "result": 1 }// Empty list
{ "operation": "first", "data": { "list": [] } }
// Output
{ "result": undefined }last
lastGets the last item in a list.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
Examples
// Input
{ "operation": "last", "data": { "list": [1, 2, 3] } }
// Output
{ "result": 3 }size
sizeGets the number of items in a list.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
Examples
// Input
{ "operation": "size", "data": { "list": [1, 2, 3, 4, 5] } }
// Output
{ "result": 5 }isEmpty
isEmptyChecks if a list is empty.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
Examples
// Empty list
{ "operation": "isEmpty", "data": { "list": [] } }
// Output
{ "result": true }// Non-empty list
{ "operation": "isEmpty", "data": { "list": [1] } }
// Output
{ "result": false }contains
containsChecks if a list contains a specific item.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
item | any | Yes | - | The item to search for |
Examples
// Item exists
{ "operation": "contains", "data": { "list": [1, 2, 3], "item": 2 } }
// Output
{ "result": true }// Item does not exist
{ "operation": "contains", "data": { "list": [1, 2, 3], "item": 5 } }
// Output
{ "result": false }Filtering
filter
filterFilters items by matching property values.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
match | object | No | {} | Object with property values to match |
Examples
// Filter by single property
{
"operation": "filter",
"data": {
"list": [
{ "name": "Alice", "age": 30 },
{ "name": "Bob", "age": 25 },
{ "name": "Charlie", "age": 30 }
],
"match": { "age": 30 }
}
}
// Output
{ "result": [{ "name": "Alice", "age": 30 }, { "name": "Charlie", "age": 30 }] }// Filter by multiple properties
{
"operation": "filter",
"data": {
"list": [
{ "name": "Alice", "age": 30, "city": "NYC" },
{ "name": "Bob", "age": 30, "city": "LA" },
{ "name": "Charlie", "age": 30, "city": "NYC" }
],
"match": { "age": 30, "city": "NYC" }
}
}
// Output
{ "result": [{ "name": "Alice", "age": 30, "city": "NYC" }, { "name": "Charlie", "age": 30, "city": "NYC" }] }filterBy
filterByFilters items using multiple criteria with various operators. Supports filtering across different fields with AND logic.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
criteria | object or array | Yes | - | Single criterion or array of criteria |
Criterion Object:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
field | string | Yes | - | Property path (dot notation supported) |
operator | string | No | eq | Comparison operator |
value | any | No | - | Value to compare against |
Available Operators:
| Operator | Description | Example Value |
|---|---|---|
eq | Equal to | 30 |
neq | Not equal to | 30 |
gt | Greater than | 30 |
gte | Greater than or equal to | 30 |
lt | Less than | 30 |
lte | Less than or equal to | 30 |
contains | String contains substring | "ar" |
startsWith | String starts with | "A" |
endsWith | String ends with | "son" |
in | Value is in array | ["NYC", "LA"] |
notIn | Value is not in array | ["NYC", "LA"] |
exists | Property exists and is not null | - |
notExists | Property is undefined or null | - |
Examples
// Single criterion
{
"operation": "filterBy",
"data": {
"list": [
{ "name": "Alice", "age": 30, "city": "NYC" },
{ "name": "Bob", "age": 25, "city": "LA" },
{ "name": "Charlie", "age": 35, "city": "NYC" }
],
"criteria": { "field": "city", "operator": "eq", "value": "NYC" }
}
}
// Output
{ "result": [{ "name": "Alice", "age": 30, "city": "NYC" }, { "name": "Charlie", "age": 35, "city": "NYC" }] }// Multiple criteria (AND logic)
{
"operation": "filterBy",
"data": {
"list": [
{ "name": "Alice", "age": 30, "city": "NYC" },
{ "name": "Bob", "age": 25, "city": "LA" },
{ "name": "Charlie", "age": 35, "city": "NYC" }
],
"criteria": [
{ "field": "city", "operator": "eq", "value": "NYC" },
{ "field": "age", "operator": "gte", "value": 30 }
]
}
}
// Output (NYC AND age >= 30)
{ "result": [{ "name": "Alice", "age": 30, "city": "NYC" }, { "name": "Charlie", "age": 35, "city": "NYC" }] }// Using 'in' operator
{
"operation": "filterBy",
"data": {
"list": [
{ "name": "Alice", "city": "NYC" },
{ "name": "Bob", "city": "LA" },
{ "name": "Charlie", "city": "Chicago" }
],
"criteria": { "field": "city", "operator": "in", "value": ["NYC", "LA"] }
}
}
// Output
{ "result": [{ "name": "Alice", "city": "NYC" }, { "name": "Bob", "city": "LA" }] }// Using 'contains' operator
{
"operation": "filterBy",
"data": {
"list": [
{ "name": "Alice" },
{ "name": "Charlie" },
{ "name": "Bob" }
],
"criteria": { "field": "name", "operator": "contains", "value": "ar" }
}
}
// Output
{ "result": [{ "name": "Charlie" }] }// Nested property with dot notation
{
"operation": "filterBy",
"data": {
"list": [
{ "user": { "profile": { "status": "active" } }, "score": 85 },
{ "user": { "profile": { "status": "inactive" } }, "score": 92 },
{ "user": { "profile": { "status": "active" } }, "score": 78 }
],
"criteria": [
{ "field": "user.profile.status", "operator": "eq", "value": "active" },
{ "field": "score", "operator": "gt", "value": 80 }
]
}
}
// Output
{ "result": [{ "user": { "profile": { "status": "active" } }, "score": 85 }] }// Using 'exists' operator
{
"operation": "filterBy",
"data": {
"list": [
{ "name": "Alice", "email": "[email protected]" },
{ "name": "Bob" },
{ "name": "Charlie", "email": null }
],
"criteria": { "field": "email", "operator": "exists" }
}
}
// Output
{ "result": [{ "name": "Alice", "email": "[email protected]" }] }Sorting
sort
sortSorts a list of primitive values.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
order | string | No | asc | Sort order: asc or desc |
Examples
// Ascending order
{ "operation": "sort", "data": { "list": [3, 1, 4, 1, 5, 9, 2, 6], "order": "asc" } }
// Output
{ "result": [1, 1, 2, 3, 4, 5, 6, 9] }// Descending order
{ "operation": "sort", "data": { "list": [3, 1, 4, 1, 5, 9, 2, 6], "order": "desc" } }
// Output
{ "result": [9, 6, 5, 4, 3, 2, 1, 1] }sortBy
sortBySorts a list of objects by one or more properties.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
key | string | No* | - | Single property to sort by |
keys | array | No* | - | Multiple properties to sort by |
order | string | No | asc | Sort order for single key |
orders | array | No | ['asc'] | Sort orders for multiple keys |
*Either key or keys should be provided.
Examples
// Sort by single property
{
"operation": "sortBy",
"data": {
"list": [
{ "name": "Charlie", "age": 35 },
{ "name": "Alice", "age": 30 },
{ "name": "Bob", "age": 25 }
],
"key": "age"
}
}
// Output
{ "result": [{ "name": "Bob", "age": 25 }, { "name": "Alice", "age": 30 }, { "name": "Charlie", "age": 35 }] }// Sort by single property descending
{
"operation": "sortBy",
"data": {
"list": [
{ "name": "Charlie", "age": 35 },
{ "name": "Alice", "age": 30 },
{ "name": "Bob", "age": 25 }
],
"key": "age",
"order": "desc"
}
}
// Output
{ "result": [{ "name": "Charlie", "age": 35 }, { "name": "Alice", "age": 30 }, { "name": "Bob", "age": 25 }] }// Sort by multiple properties
{
"operation": "sortBy",
"data": {
"list": [
{ "name": "Charlie", "age": 30 },
{ "name": "Alice", "age": 30 },
{ "name": "Bob", "age": 25 }
],
"keys": ["age", "name"],
"orders": ["asc", "asc"]
}
}
// Output (sorted by age, then by name)
{ "result": [{ "name": "Bob", "age": 25 }, { "name": "Alice", "age": 30 }, { "name": "Charlie", "age": 30 }] }reverse
reverseReverses the order of items in a list.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
Examples
// Input
{ "operation": "reverse", "data": { "list": [1, 2, 3, 4, 5] } }
// Output
{ "result": [5, 4, 3, 2, 1] }Slicing & Pagination
take
takeTakes the first n items from a list.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
n | number | No | 1 | Number of items to take |
Examples
// Input
{ "operation": "take", "data": { "list": [1, 2, 3, 4, 5], "n": 3 } }
// Output
{ "result": [1, 2, 3] }takeLast
takeLastTakes the last n items from a list.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
n | number | No | 1 | Number of items to take |
Examples
// Input
{ "operation": "takeLast", "data": { "list": [1, 2, 3, 4, 5], "n": 3 } }
// Output
{ "result": [3, 4, 5] }drop
dropDrops the first n items from a list.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
n | number | No | 1 | Number of items to drop |
Examples
// Input
{ "operation": "drop", "data": { "list": [1, 2, 3, 4, 5], "n": 2 } }
// Output
{ "result": [3, 4, 5] }chunk
chunkSplits a list into chunks of a specified size.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
size | number | No | 1 | Size of each chunk |
Examples
// Input
{ "operation": "chunk", "data": { "list": [1, 2, 3, 4, 5, 6, 7, 8], "size": 3 } }
// Output
{ "result": [[1, 2, 3], [4, 5, 6], [7, 8]] }paginate
paginatePaginates a list with full pagination metadata.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
page | number | No | 1 | Page number (1-indexed) |
pageSize | number | No | 10 | Items per page |
Result Object
| Field | Type | Description |
|---|---|---|
items | array | Items on the current page |
page | number | Current page number |
pageSize | number | Items per page |
totalItems | number | Total number of items |
totalPages | number | Total number of pages |
hasNextPage | boolean | Whether there's a next page |
hasPreviousPage | boolean | Whether there's a previous page |
Examples
// Page 2 of results
{
"operation": "paginate",
"data": {
"list": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25],
"page": 2,
"pageSize": 10
}
}
// Output
{
"result": {
"items": [11, 12, 13, 14, 15, 16, 17, 18, 19, 20],
"page": 2,
"pageSize": 10,
"totalItems": 25,
"totalPages": 3,
"hasNextPage": true,
"hasPreviousPage": true
}
}// First page
{
"operation": "paginate",
"data": {
"list": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
"page": 1,
"pageSize": 10
}
}
// Output
{
"result": {
"items": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
"page": 1,
"pageSize": 10,
"totalItems": 15,
"totalPages": 2,
"hasNextPage": true,
"hasPreviousPage": false
}
}// Last page (partial)
{
"operation": "paginate",
"data": {
"list": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
"page": 2,
"pageSize": 10
}
}
// Output
{
"result": {
"items": [11, 12, 13, 14, 15],
"page": 2,
"pageSize": 10,
"totalItems": 15,
"totalPages": 2,
"hasNextPage": false,
"hasPreviousPage": true
}
}Grouping
groupBy
groupByGroups items by a property value.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
key | string | Yes | - | Property to group by |
Examples
// Input
{
"operation": "groupBy",
"data": {
"list": [
{ "name": "Alice", "city": "NYC" },
{ "name": "Bob", "city": "LA" },
{ "name": "Charlie", "city": "NYC" }
],
"key": "city"
}
}
// Output
{
"result": {
"NYC": [{ "name": "Alice", "city": "NYC" }, { "name": "Charlie", "city": "NYC" }],
"LA": [{ "name": "Bob", "city": "LA" }]
}
}keyBy
keyByCreates an object indexed by a property value. Useful for quick lookups.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
key | string | Yes | - | Property to index by |
Examples
// Input
{
"operation": "keyBy",
"data": {
"list": [
{ "id": "a", "name": "Alice" },
{ "id": "b", "name": "Bob" },
{ "id": "c", "name": "Charlie" }
],
"key": "id"
}
}
// Output
{
"result": {
"a": { "id": "a", "name": "Alice" },
"b": { "id": "b", "name": "Bob" },
"c": { "id": "c", "name": "Charlie" }
}
}Aggregation
sum
sumCalculates the sum of values.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
key | string | No | - | Property to sum (for object arrays) |
Examples
// Sum primitives
{ "operation": "sum", "data": { "list": [1, 2, 3, 4, 5] } }
// Output
{ "result": 15 }// Sum property values
{
"operation": "sum",
"data": {
"list": [{ "price": 10 }, { "price": 20 }, { "price": 30 }],
"key": "price"
}
}
// Output
{ "result": 60 }avg
avgCalculates the average of values.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
key | string | No | - | Property to average (for object arrays) |
Examples
// Average primitives
{ "operation": "avg", "data": { "list": [10, 20, 30] } }
// Output
{ "result": 20 }// Average property values
{
"operation": "avg",
"data": {
"list": [{ "age": 20 }, { "age": 30 }, { "age": 40 }],
"key": "age"
}
}
// Output
{ "result": 30 }min
minFinds the minimum value or item with minimum property value.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
key | string | No | - | Property to compare (for object arrays) |
Examples
// Min of primitives
{ "operation": "min", "data": { "list": [5, 2, 8, 1, 9] } }
// Output
{ "result": 1 }// Item with min property value
{
"operation": "min",
"data": {
"list": [
{ "name": "Alice", "age": 30 },
{ "name": "Bob", "age": 25 },
{ "name": "Charlie", "age": 35 }
],
"key": "age"
}
}
// Output (returns entire object)
{ "result": { "name": "Bob", "age": 25 } }max
maxFinds the maximum value or item with maximum property value.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
key | string | No | - | Property to compare (for object arrays) |
Examples
// Max of primitives
{ "operation": "max", "data": { "list": [5, 2, 8, 1, 9] } }
// Output
{ "result": 9 }// Item with max property value
{
"operation": "max",
"data": {
"list": [
{ "name": "Alice", "age": 30 },
{ "name": "Bob", "age": 25 },
{ "name": "Charlie", "age": 35 }
],
"key": "age"
}
}
// Output (returns entire object)
{ "result": { "name": "Charlie", "age": 35 } }count
countCounts items, optionally matching specific criteria.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
match | object | No | - | Object with property values to match |
Examples
// Count all items
{ "operation": "count", "data": { "list": [1, 2, 3, 4, 5] } }
// Output
{ "result": 5 }// Count matching items
{
"operation": "count",
"data": {
"list": [
{ "name": "Alice", "active": true },
{ "name": "Bob", "active": false },
{ "name": "Charlie", "active": true }
],
"match": { "active": true }
}
}
// Output
{ "result": 2 }Utility
join
joinJoins list items into a string with a separator.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
list | array | No | [] | The source list |
separator | string | No | , | Separator between items |
Examples
// Default separator (comma)
{ "operation": "join", "data": { "list": ["a", "b", "c"] } }
// Output
{ "result": "a,b,c" }// Custom separator
{ "operation": "join", "data": { "list": ["a", "b", "c"], "separator": " - " } }
// Output
{ "result": "a - b - c" }// Empty separator
{ "operation": "join", "data": { "list": ["a", "b", "c"], "separator": "" } }
// Output
{ "result": "abc" }Error Handling
The connector throws descriptive errors for invalid inputs:
| Error | Cause |
|---|---|
filterBy: criteria is required | Missing criteria in filterBy |
filterBy: each criterion must have a field | Missing field in a criterion |
filterBy: operator 'xyz' not supported | Unknown operator used |
paginate: page must be >= 1 | Page number less than 1 |
paginate: pageSize must be >= 1 | Page size less than 1 |
{operation}: list must be an array | Non-array passed as list |
List operation 'xyz' not supported | Unknown operation |
Operations Summary
| Category | Operations | Count |
|---|---|---|
| Initialization | empty, of, range | 3 |
| Basic | push, concat, slice | 3 |
| Query | get, first, last, size, isEmpty, contains | 6 |
| Filtering | filter, filterBy | 2 |
| Sorting | sort, sortBy, reverse | 3 |
| Slicing | take, takeLast, drop, chunk, paginate | 5 |
| Grouping | groupBy, keyBy | 2 |
| Aggregation | sum, avg, min, max, count | 5 |
| Utility | join | 1 |
| Total | 30 |
Updated 19 days ago