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:

ModifierDescription
DeduplicateRemove duplicate elements from a collection.
SortSort 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
Try in Playground

Parameters

These are the supported parameters:

collection
collection

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"]
Try in Playground

You can also use it to deduplicate a map:

["a": 1, "b": 2, "c": 1] without duplicates // ["a": 1, "b": 2]
Try in Playground

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
Try in Playground

You can optionally specify an order and/or mode for sorting:

/*<collection>*/ sorted /*<order>*/ /*<mode>*/
Try in Playground

Note that both /*<order>*/ and /*<mode>*/ are literal words and cannot be specified dynamically using expressions.

The following table describes the supported orders:

OrderDescription
ascendingSort the elements in ascending order (e.g., from the smallest to the largest). This is the default order.
descendingSort the elements in descending order (e.g., from the largest to the smallest).

And these are the supported modes and the types they support:

ModeSupported typeDescription
alphabeticalStringSort the elements alphabetically.
alphanumericalStringSort 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.
numericalNumber or stringSort 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:

collection

The collection to sort.

Examples

Here is a basic example of using this modifier with a list:

[3, 1, 2] sorted // [1, 2, 3]
Try in Playground

You can also use this modifier to sort a map:

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

To sort a collection in a different order, you can specify the direction:

[1, 3, 2] sorted descending // [3, 2, 1]
Try in Playground

And to sort a collection in a specific way, you can specify the mode:

["a", "10", "2"] sorted numerical // ["2", "10", "a"]
Try in Playground