Collection macros

Learn how to use macros to work with collections in CQL.

Collection macros are specialized functions written in natural language that allow you to perform operations on collections like arrays or sets. They simplify common tasks like finding the average, counting elements, or extracting sublists.

This is the summary of the available collection macros for quick reference:

MacroDescription
CountCounts the elements in a collection.
MinimumFinds the minimum value in a collection.
MaximumFinds the maximum value in a collection.
SumCalculates the sum of a collection of numbers.
AverageCalculates the average of a collection of numbers.
First elementGets the first element of a collection.
Last elementGets the last element of a collection.
KeysGets the keys of a collection.
SublistGets a sublist of a collection.

Count

This macro counts the elements in a collection.

The count refers to the total number of elements in a given collection, which is also known as its size.

Syntax

This macro has the following syntax:

count of /*<collection>*/
Try in Playground

You can also prefix the macro with a definite article for readability:

the count of /*<collection>*/
Try in Playground

Parameters

These are the supported parameters:

collection

A collection of elements you want to count.

Examples

Here is an example of how to count the number of items in a list:

count of [1, 2, 3] // 3
Try in Playground

You can also count map entries:

count of ["a": 1, "b": 2, "c": 3] // 3
Try in Playground

Minimum

This macro returns the minimum value in a collection.

The minimum is the smallest of all the numbers in the collection. For example, the minimum of the numbers 2, 3, 4, 7, and 9 is 2.

Since an empty collection has no minimum, trying to get the minimum of an empty collection results in an error. So be sure to provide a default value in cases where the collection might be empty.

Syntax

This macro has the following syntax:

minimum of /*<collection>*/
Try in Playground

Alternatively, you can use the abbreviated form:

min of /*<collection>*/
Try in Playground

You can also prefix the macro with a definite article for readability:

the minimum of /*<collection>*/
Try in Playground

Parameters

These are the supported parameters:

collection

A non-empty collection of numbers from which you want to find the minimum. Elements are automatically converted to numbers if necessary.

Examples

Here is an example of how to get the minimum value of a collection of numbers:

minimum of [1.5, 2.5, "3"] // 1.5
Try in Playground

In cases where the collection might be empty, you can provide a default value:

minimum of /*<collection>*/ or else null
Try in Playground

Maximum

This macro returns the maximum value in a collection.

The maximum is the largest of all the numbers in the collection. For example, the maximum of the numbers 2, 3, 4, 7, and 9 is 9.

Since an empty collection has no maximum, trying to get the maximum of an empty collection results in an error. So be sure to provide a default value in cases where the collection might be empty.

Syntax

This macro has the following syntax:

maximum of /*<collection>*/
Try in Playground

Alternatively, you can use the abbreviated form:

max of /*<collection>*/
Try in Playground

You can also prefix the macro with a definite article for readability:

the maximum of /*<collection>*/
Try in Playground

Parameters

These are the supported parameters:

collection

A non-empty collection of numbers from which you want to find the maximum. Elements are automatically converted to numbers if necessary.

Examples

Here is an example of how to get the maximum value of a collection of numbers:

maximum of [1.5, 2.5, "3"] // 3
Try in Playground

In cases where the collection might be empty, you can provide a default value:

maximum of /*<collection>*/ or else null
Try in Playground

Sum

This macro calculates the sum of a collection of numbers.

The sum is the result of adding all the numbers in the collection. For example, the sum of the numbers 2, 3, 4, 7, and 9 is 25. If the collection is empty, the result is zero.

Syntax

This macro has the following syntax:

sum of /*<collection>*/
Try in Playground

You can also prefix the macro with a definite article for readability:

the sum of /*<collection>*/
Try in Playground

Parameters

These are the supported parameters:

collection

The collection of numbers you want to sum. Elements are automatically converted to numbers if necessary.

Examples

Here is an example of how to sum a collection of numbers:

sum of [1, 2, "3"] // 6
Try in Playground

Average

This macro calculates the average of a collection of numbers.

The average is the sum of all the numbers in the collection divided by the number of elements in the collection. For example, the average of the numbers 2, 3, 4, 7, and 9, which add up to 25, is 5.

Since averaging involves division, passing an empty collection will result in an error due to division by zero. So be sure to provide a default value in cases where the collection might be empty.

Syntax

This macro has the following syntax:

average of /*<collection>*/
Try in Playground

You can also prefix the macro with a definite article for readability:

the average of /*<collection>*/
Try in Playground

Parameters

These are the supported parameters:

collection

A non-empty collection of numbers you want to average. Elements are automatically converted to numbers if necessary.

Examples

Here is an example of how to calculate the average of a collection of numbers:

average of [1.5, "2.5", 3.5] // 2.5
Try in Playground

In cases where the collection might be empty, you can provide a default value:

average of /*<collection>*/ or else 0
Try in Playground

First element

This macro gets the first element of a collection.

To determine the first element, this macro uses the order of the collection and not the key or index of the element.

Note that trying to get the first element of an empty collection results in an error, so be sure to provide a default value in cases where the collection might be empty.

Croct's mascot neutral
Why not return null instead?

An error helps distinguish between empty collections and those with null elements, so you can easily handle both cases.

Syntax

This macro has the following syntax:

first of /*<collection>*/
Try in Playground

You can also prefix the macro with a definite article for readability:

the first of /*<collection>*/
Try in Playground

Parameters

These are the supported parameters:

collection

A non-empty collection from which you want to get the first element.

Examples

Here is an example of how to get the first element of a list:

first of [1, 2, 3] // 1
Try in Playground

You can also get the first element of a map:

first of ["a": 1, "b": 2, "c": 3] // 1
Try in Playground

To get the first key of a map, you can use the keys macro:

first of keys of ["a": 1, "b": 2, "c": 3] // "a"
Try in Playground

If the collection might be empty and you want to return null instead of an error, you can use a fallback operator:

first of /*<collection>*/ or else null
Try in Playground

Last element

This macro gets the last element of a collection.

To determine the last element, this macro uses the order of the collection and not the key or index of the element.

Note that trying to get the last element of an empty collection results in an error, so be sure to provide a default value in cases where the collection might be empty.

Croct's mascot neutral
Why not return null instead?

An error helps distinguish between empty collections and those with null elements, so you can easily handle both cases.

Syntax

This macro has the following syntax:

last of /*<collection>*/
Try in Playground

You can also prefix the macro with a definite article for readability:

the last of /*<collection>*/
Try in Playground

Parameters

These are the supported parameters:

collection

A non-empty collection from which you want to get the last element.

Examples

Here is an example of how to get the last element of a list:

last of [1, 2, 3] // 3
Try in Playground

You can also get the last element of a map:

last of ["a": 1, "b": 2, "c": 3] // 3
Try in Playground

To get the last key of a map, you can use the keys macro:

last of keys of ["a": 1, "b": 2, "c": 3] // "c"
Try in Playground

Keys

This macro gets all the keys or indices of a collection.

The output for maps is the list of keys in the order in which they appear in the map. For lists, the result is the zero-based indices of the elements in the list.

Syntax

This macro has the following syntax:

keys of /*<collection>*/
Try in Playground

You can also prefix the macro with a definite article for readability:

the keys of /*<collection>*/
Try in Playground

Parameters

These are the supported parameters:

collection

The collection from which you want to get the keys or indices.

Examples

Here is an example of how to get the keys of a map:

keys of ["a": 1, "b": 2, "c": 3] // ["a", "b", "c"]
Try in Playground

If you pass a list, you get its indices:

keys of [1, 2, 3] // [0, 1, 2]
Try in Playground

Sublist

This macro selects a range of elements from a collection.

You select a range by specifying a start index and an optional end index. The output is a new collection consisting of elements within the specified range. If you do not specify an end index, the result will include all elements from the start index to the end of the collection.

Although this macro is mainly intended for lists, you can also use it with maps. In this case, the keys and order are preserved in the output.

Syntax

The full syntax for this macro is as follows:

sublist of /*<collection>*/ from /*<start>*/ to /*<end>*/
Try in Playground

To omit the end index, use the following syntax:

sublist of /*<collection>*/ from /*<start>*/
Try in Playground

You can also prefix the macro with a definite article for readability:

the sublist of /*<collection>*/ from /*<start>*/ to /*<end>*/
Try in Playground

Parameters

The following list describes the supported parameters:

collection

The collection from which you want to select a range of elements.

start

The zero-based index of the first element in the range, inclusive.

end(optional)

The zero-based index of the last element in the range, exclusive.

If you omit this parameter, the result will include all elements from the start index to the end of the collection.

Examples

Here is an example of how to get a range of elements from a list:

sublist of [1, 2, 3, 4, 5] from 1 to 3 // [2, 3]
Try in Playground

You can also get a range of elements from a map:

sublist of ["a": 1, "b": 2, "c": 3] from 1 to 2 // ["b": 2]
Try in Playground

To get all elements from a given index, omit the end index:

sublist of [1, 2, 3, 4, 5] from 2 // [3, 4, 5]
Try in Playground