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:
| Macro | Description |
|---|---|
| Count | Counts the elements in a collection. |
| Minimum | Finds the minimum value in a collection. |
| Maximum | Finds the maximum value in a collection. |
| Sum | Calculates the sum of a collection of numbers. |
| Average | Calculates the average of a collection of numbers. |
| First element | Gets the first element of a collection. |
| Last element | Gets the last element of a collection. |
| Keys | Gets the keys of a collection. |
| Sublist | Gets 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>*/
You can also prefix the macro with a definite article for readability:
the count of /*<collection>*/
Parameters
These are the supported parameters:
- collectioncollection
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
You can also count map entries:
count of ["a": 1, "b": 2, "c": 3] // 3
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>*/
Alternatively, you can use the abbreviated form:
min of /*<collection>*/
You can also prefix the macro with a definite article for readability:
the minimum of /*<collection>*/
Parameters
These are the supported parameters:
- collectioncollection
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
In cases where the collection might be empty, you can provide a default value:
minimum of /*<collection>*/ or else null
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>*/
Alternatively, you can use the abbreviated form:
max of /*<collection>*/
You can also prefix the macro with a definite article for readability:
the maximum of /*<collection>*/
Parameters
These are the supported parameters:
- collectioncollection
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
In cases where the collection might be empty, you can provide a default value:
maximum of /*<collection>*/ or else null
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>*/
You can also prefix the macro with a definite article for readability:
the sum of /*<collection>*/
Parameters
These are the supported parameters:
- collectioncollection
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
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>*/
You can also prefix the macro with a definite article for readability:
the average of /*<collection>*/
Parameters
These are the supported parameters:
- collectioncollection
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
In cases where the collection might be empty, you can provide a default value:
average of /*<collection>*/ or else 0
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.
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>*/
You can also prefix the macro with a definite article for readability:
the first of /*<collection>*/
Parameters
These are the supported parameters:
- collectioncollection
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
You can also get the first element of a map:
first of ["a": 1, "b": 2, "c": 3] // 1
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"
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
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.
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>*/
You can also prefix the macro with a definite article for readability:
the last of /*<collection>*/
Parameters
These are the supported parameters:
- collectioncollection
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
You can also get the last element of a map:
last of ["a": 1, "b": 2, "c": 3] // 3
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"
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>*/
You can also prefix the macro with a definite article for readability:
the keys of /*<collection>*/
Parameters
These are the supported parameters:
- collectioncollection
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"]
If you pass a list, you get its indices:
keys of [1, 2, 3] // [0, 1, 2]
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>*/
To omit the end index, use the following syntax:
sublist of /*<collection>*/ from /*<start>*/
You can also prefix the macro with a definite article for readability:
the sublist of /*<collection>*/ from /*<start>*/ to /*<end>*/
Parameters
The following list describes the supported parameters:
- collectioncollection
The collection from which you want to select a range of elements.
- startinteger
The zero-based index of the first element in the range, inclusive.
- end(optional)integer
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]
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]
To get all elements from a given index, omit the end index:
sublist of [1, 2, 3, 4, 5] from 2 // [3, 4, 5]