Collection modifiers
Learn how to manipulate collections in CQL.
Collection modifiers are natural language functions for manipulating lists, sets, and maps. These functions are useful for tasks that involve rearranging collection, such as removing duplicates, sorting, and filtering.
This is the summary of the available collection modifiers for quick reference:
| Modifier | Description |
|---|---|
| Deduplicate | Remove duplicate elements from a collection. |
| Sort | Sort the elements of a collection based on a specified order and mode. |
Deduplicate
This modifier removes duplicate elements from a collection. This is useful when you want your collection to behave like a set, where each element only appears once.
When removing duplicate elements, this modifier uses the same equivalence rules as the equal operation to ensure consistency in how it determines whether two items are equal.
For maps, there are a few things to keep in mind:
- Keys are not considered for deduplication.
- The order and keys are preserved in the resulting map.
- The first key encountered is retained for duplicate values.
Syntax
This modifier has the following syntax:
/*<collection>*/ without duplicates
Parameters
These are the supported parameters:
- collectioncollection
The collection to deduplicate.
Examples
Here is a basic example of using this modifier with a list:
["a", "b", "a", "c"] without duplicates // ["a", "b", "c"]
You can also use it to deduplicate a map:
["a": 1, "b": 2, "c": 1] without duplicates // ["a": 1, "b": 2]
Sort
This modifier sorts the elements of a collection based on a specified order and mode.
When sorting, this modifier uses the same comparison rules as the relational operators to ensure consistency in how it determines the order of two items. And, as with comparisons, attempting to sort a collection that contains elements that are not comparable will result in an error.
You can also use this modifier to sort maps. Although the keys are not used for sorting, they are preserved in the resulting map.
Syntax
The basic syntax for this modifier is as follows:
/*<collection>*/ sorted
You can optionally specify an order and/or mode for sorting:
/*<collection>*/ sorted /*<order>*/ /*<mode>*/
Note that both /*<order>*/ and /*<mode>*/ are literal words and cannot be specified dynamically using expressions.
The following table describes the supported orders:
| Order | Description |
|---|---|
| ascending | Sort the elements in ascending order (e.g., from the smallest to the largest). This is the default order. |
| descending | Sort the elements in descending order (e.g., from the largest to the smallest). |
And these are the supported modes and the types they support:
| Mode | Supported type | Description |
|---|---|---|
| alphabetical | String | Sort the elements alphabetically. |
| alphanumerical | String | Sort the elements alphanumerically, also known as natural sorting. This mode differs from alphabetical because numbers are sorted numerically rather than lexicographically. For example, 10 sorts after 2 in alphabetical mode but before 2 in alphanumerical mode. |
| numerical | Number or string | Sort the elements numerically. This mode differs from alphanumerical in that it supports comparing numeric strings, integers, decimals, and floats — not just numbers. |
By default, the modifier uses the ascending order and the natural sorting mode, which follows the same comparison rules as the relational operators.
Parameters
These are the supported parameters:
- collectioncollection
The collection to sort.
Examples
Here is a basic example of using this modifier with a list:
[3, 1, 2] sorted // [1, 2, 3]
You can also use this modifier to sort a map:
["a": 3, "b": 1, "c": 2] sorted // ["b": 1, "c": 2, "a": 3]
To sort a collection in a different order, you can specify the direction:
[1, 3, 2] sorted descending // [3, 2, 1]
And to sort a collection in a specific way, you can specify the mode:
["a", "10", "2"] sorted numerical // ["2", "10", "a"]