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 | json filter 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 TypeSyntaxExample
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

Creates an empty list.

Parameters

None.

Examples

// Input
{ "operation": "empty", "data": {} }

// Output
{ "result": [] }

of

Creates a list from provided items.

Parameters

ParameterTypeRequiredDefaultDescription
itemsarrayNo[]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

Creates a list of numbers within a specified range.

Parameters

ParameterTypeRequiredDefaultDescription
startnumberNo0The start of the range
endnumberYes-The end of the range (exclusive)
stepnumberNo1The 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

Adds one or more items to the end of a list.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
itemanyNo-A single item to add
itemsarrayNo-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

Concatenates two lists together.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The first list
otherarrayNo[]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

Extracts a portion of a list.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
startnumberNo0Start index (inclusive)
endnumberNolist lengthEnd 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

Gets an item at a specific index. Supports negative indexing.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
indexnumberNo0The 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

Gets the first item in a list.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]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

Gets the last item in a list.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list

Examples

// Input
{ "operation": "last", "data": { "list": [1, 2, 3] } }

// Output
{ "result": 3 }

size

Gets the number of items in a list.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list

Examples

// Input
{ "operation": "size", "data": { "list": [1, 2, 3, 4, 5] } }

// Output
{ "result": 5 }

isEmpty

Checks if a list is empty.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]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

Checks if a list contains a specific item.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
itemanyYes-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

Filters items by matching property values.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
matchobjectNo{}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

Filters items using multiple criteria with various operators. Supports filtering across different fields with AND logic.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
criteriaobject or arrayYes-Single criterion or array of criteria

Criterion Object:

FieldTypeRequiredDefaultDescription
fieldstringYes-Property path (dot notation supported)
operatorstringNoeqComparison operator
valueanyNo-Value to compare against

Available Operators:

OperatorDescriptionExample Value
eqEqual to30
neqNot equal to30
gtGreater than30
gteGreater than or equal to30
ltLess than30
lteLess than or equal to30
containsString contains substring"ar"
startsWithString starts with"A"
endsWithString ends with"son"
inValue is in array["NYC", "LA"]
notInValue is not in array["NYC", "LA"]
existsProperty exists and is not null-
notExistsProperty 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

Sorts a list of primitive values.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
orderstringNoascSort 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

Sorts a list of objects by one or more properties.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
keystringNo*-Single property to sort by
keysarrayNo*-Multiple properties to sort by
orderstringNoascSort order for single key
ordersarrayNo['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

Reverses the order of items in a list.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list

Examples

// Input
{ "operation": "reverse", "data": { "list": [1, 2, 3, 4, 5] } }

// Output
{ "result": [5, 4, 3, 2, 1] }

Slicing & Pagination

take

Takes the first n items from a list.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
nnumberNo1Number of items to take

Examples

// Input
{ "operation": "take", "data": { "list": [1, 2, 3, 4, 5], "n": 3 } }

// Output
{ "result": [1, 2, 3] }

takeLast

Takes the last n items from a list.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
nnumberNo1Number of items to take

Examples

// Input
{ "operation": "takeLast", "data": { "list": [1, 2, 3, 4, 5], "n": 3 } }

// Output
{ "result": [3, 4, 5] }

drop

Drops the first n items from a list.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
nnumberNo1Number of items to drop

Examples

// Input
{ "operation": "drop", "data": { "list": [1, 2, 3, 4, 5], "n": 2 } }

// Output
{ "result": [3, 4, 5] }

chunk

Splits a list into chunks of a specified size.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
sizenumberNo1Size 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

Paginates a list with full pagination metadata.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
pagenumberNo1Page number (1-indexed)
pageSizenumberNo10Items per page

Result Object

FieldTypeDescription
itemsarrayItems on the current page
pagenumberCurrent page number
pageSizenumberItems per page
totalItemsnumberTotal number of items
totalPagesnumberTotal number of pages
hasNextPagebooleanWhether there's a next page
hasPreviousPagebooleanWhether 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

Groups items by a property value.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
keystringYes-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

Creates an object indexed by a property value. Useful for quick lookups.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
keystringYes-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

Calculates the sum of values.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
keystringNo-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

Calculates the average of values.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
keystringNo-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

Finds the minimum value or item with minimum property value.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
keystringNo-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

Finds the maximum value or item with maximum property value.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
keystringNo-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

Counts items, optionally matching specific criteria.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
matchobjectNo-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

Joins list items into a string with a separator.

Parameters

ParameterTypeRequiredDefaultDescription
listarrayNo[]The source list
separatorstringNo,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:

ErrorCause
filterBy: criteria is requiredMissing criteria in filterBy
filterBy: each criterion must have a fieldMissing field in a criterion
filterBy: operator 'xyz' not supportedUnknown operator used
paginate: page must be >= 1Page number less than 1
paginate: pageSize must be >= 1Page size less than 1
{operation}: list must be an arrayNon-array passed as list
List operation 'xyz' not supportedUnknown operation

Operations Summary

CategoryOperationsCount
Initializationempty, of, range3
Basicpush, concat, slice3
Queryget, first, last, size, isEmpty, contains6
Filteringfilter, filterBy2
Sortingsort, sortBy, reverse3
Slicingtake, takeLast, drop, chunk, paginate5
GroupinggroupBy, keyBy2
Aggregationsum, avg, min, max, count5
Utilityjoin1
Total30