Collection tests
Discover the different collection tests available in CQL.
Collection tests are natural language conditions that you can use to check whether a collection meets certain criteria. These tests include, for example, checking whether a collection contains a certain element or whether an element is in a collection.
The following table summarizes the available string tests for quick reference:
| Test | Description |
|---|---|
| Contains | Checks whether a collection contains a certain element, denoted as 𝐴 ∈ 𝐵. |
| In | Checks whether an element is in a collection, denoted as 𝐴 ∋ 𝐵. |
| Contains all | Checks whether one collection contains all elements of another, denoted as 𝐴 ⊇ 𝐵. |
| Contains none | Checks whether one collection contains none of the elements of another, denoted as 𝐴 ⊉ 𝐵. |
| Contains either | Checks whether one collection shares at least one element with another, denoted as 𝐴 ∩ 𝐵 ≠ ∅. |
| Contains neither | Checks whether one collection contains none of the elements of another, denoted as 𝐴 ∩ 𝐵 = ∅. |
Contains
This test checks whether a collection contains a certain element. It works the same way as the in test, but with the operands reversed.
You can use any collection type, including lists and maps. Keys are ignored when checking whether a map contains an element.
When comparing elements, this test uses the same equivalence rules as the equal operation to ensure consistency in how it determines whether two items are equal.
Syntax
This test has the following syntax:
/*<collection>*/ contains /*<element>*/
You can alternatively use the following syntax:
/*<collection>*/ includes /*<element>*/
Both forms have the same semantics. You can use whichever makes your query more expressive and easier to read.
You can negate the test to verify the contrary:
/*<collection>*/ does not contain /*<element>*/
The same applies to the alternative syntax:
/*<collection>*/ does not include /*<element>*/
Parameters
These are the supported parameters:
- collectioncollection
The collection to check.
- elementany
The element to search for in the collection.
Examples
Here is a simple example that checks whether a list contains a certain element:
["a", "b", "c"] contains "b" // true
To negate the test, you can write:
["a", "b", "c"] does not contain "b" // false
In
This test checks whether an element is in a collection. It works the same way as the contains test, but with the operands reversed.
You can use any collection type, including lists and maps. Keys are ignored when checking whether a map contains an element.
When comparing elements, this test uses the same equivalence rules as the equal operation to ensure consistency in how it determines whether two items are equal.
Syntax
This test has the following syntax:
/*<element>*/ is in /*<collection>*/
You can negate the test to verify the contrary:
/*<element>*/ is not in /*<collection>*/
Parameters
These are the supported parameters:
- elementany
The element to search for in the collection.
- collectioncollection
The collection to check.
Examples
Here is a simple example that checks whether an element is in a list:
"b" is in ["a", "b", "c"] // true
To negate the test, you can write:
"b" is not in ["a", "b", "c"] // false
Contains all
This test checks whether one collection contains all elements of another. It is the opposite of the contains none test.
This operation corresponds to the mathematical concepts of superset and subset. Specifically, it checks whether the collection 𝐴 is a superset of 𝐵 (𝐴 ⊇ 𝐵) or, conversely, whether 𝐵 is a subset of 𝐴 (𝐵 ⊆ 𝐴).
Note that the result is always true if the second collection is empty, because the empty set is a subset of every set.
This might sound funny, but since there are no unicorns in the room, there's no unicorn that isn't shining. So, technically, they all are!
Also, keep in mind that neither the order nor duplicate elements affect the result since collections are treated as sets.
Syntax
This test has the following syntax:
/*<collection>*/ contains all of /*<collection>*/
Alternatively, you can use the following syntax:
/*<collection>*/ includes all of /*<collection>*/
Both forms have the same semantics. You can use whichever makes your query more expressive and easier to read.
You can negate the test to verify the contrary:
/*<collection>*/ does not contain all of /*<collection>*/
The same applies to the alternative syntax:
/*<collection>*/ does not include all of /*<collection>*/
However, consider using the contains none test instead of negating, as it is more expressive and easier to understand.
Parameters
These are the supported parameters:
- collectioncollection
The collection to check.
- subsetcollection
The collection whose elements must be contained in the other collection.
Examples
Here is an example of a collection that contains all the elements of another collection:
["a", "b", "c"] contains all of ["a", "b"] // true
And here is a counterexample:
["a", "b"] contains all of ["a", "b", "c"] // false
To negate the test, you can write:
["a", "b", "c"] does not contain all of ["a", "b"] // false
If the second collection is empty, the result is always true:
["a", "b", "c"] contains all of [] // true
Contains none
This test checks whether one collection contains none of the elements of another. It is the opposite of the contains all test.
This operation corresponds to the mathematical concepts of superset and subset. Specifically, it checks whether the collection 𝐴 is not a superset of 𝐵 (𝐴 ⊉ 𝐵) or, conversely, whether 𝐵 is not a subset of 𝐴 (𝐵 ⊈ 𝐴).
Note that the result is always false if the second collection is empty, because the empty set is a subset of every set. This is different from the contains neither test, which returns true in this case, as it operates on the idea of intersection rather than subset.
Technically, yes. Since there are no unicorns in the room, there's no unicorn that isn't shining. Logic is fun, isn't it?
Also, keep in mind that neither the order nor duplicate elements affect the result since collections are treated as sets.
Syntax
This test has the following syntax:
/*<collection>*/ contains none of /*<collection>*/
Alternatively, you can use the following syntax:
/*<collection>*/ includes none of /*<collection>*/
Both forms have the same semantics. You can use whichever makes your query more expressive and easier to read.
You can negate the test to verify the contrary:
/*<collection>*/ does not contain none of /*<collection>*/
The same applies to the alternative syntax:
/*<collection>*/ does not include none of /*<collection>*/
However, consider using the contains all test instead of negating, as it is more expressive and easier to understand.
Parameters
These are the supported parameters:
- collectioncollection
The collection to check.
- subsetcollection
The collection whose elements must not be contained in the other collection.
Examples
Here is an example of a collection that contains none of the elements of another collection:
["a", "b", "c"] contains none of ["d", "e", "f"] // true
And here is a counterexample:
["a", "b", "c"] contains none of ["a", "d", "e"] // false
To negate the test, you can write:
["a", "b", "c"] does not contain none of ["d", "e", "f"] // false
If the second collection is empty, the result is always false:
["a", "b", "c"] contains none of [] // false
Contains either
This test checks whether one collection contains at least one of the elements of another. It is the opposite of the contains neither test.
This operation corresponds to the mathematical concepts of intersection and disjoint sets. Specifically, it checks whether the intersection of the collection 𝐴 and 𝐵 is not empty (𝐴 ∩ 𝐵 ≠ ∅) or, conversely, whether 𝐴 and 𝐵 are not disjoint (𝐴 ∩ 𝐵 ≠ ∅).
Note that the result is always false if the second collection is empty because the empty set is disjoint from every set.
Also, keep in mind that neither the order nor duplicate elements affect the result since collections are treated as sets.
Syntax
This test has the following syntax:
/*<collection>*/ contains either /*<collection>*/
Alternatively, you can use the following syntax:
/*<collection>*/ includes either /*<collection>*/
Both forms have the same semantics. You can use whichever makes your query more expressive and easier to read.
You can negate the test to verify the contrary:
/*<collection>*/ does not contain either /*<collection>*/
The same applies to the alternative syntax:
/*<collection>*/ does not include either /*<collection>*/
However, consider using the contains neither test instead of negating, as it is more expressive and easier to understand.
Parameters
These are the supported parameters:
- collectioncollection
The collection to check.
- subsetcollection
The collection whose elements must be contained in the other collection.
Examples
Here is an example of a collection that contains at least one of the elements of another collection:
["a", "b", "c"] contains either ["a", "d", "e"] // true
And here is a counterexample:
["a", "b", "c"] contains either ["d", "e", "f"] // false
To negate the test, you can write:
["a", "b", "c"] does not contain either ["a", "d", "e"] // false
If the second collection is empty, the result is always false:
["a", "b", "c"] contains either [] // false
Contains neither
This test checks whether one collection does not contain any of the elements of another. It is the opposite of the contains either test.
This operation corresponds to the mathematical concept of intersection and disjoint sets. Specifically, it checks whether the intersection of the collection 𝐴 and 𝐵 is empty (𝐴 ∩ 𝐵 = ∅) or, equivalently, whether 𝐴 and 𝐵 are disjoint (𝐴 ∩ 𝐵 = ∅).
Note that the result is always true if the second collection is empty because the empty set is disjoint from every set. This is different from the contains none test, which returns false in this case, as it operates on the idea of subset rather than intersection.
Also, keep in mind that neither the order nor duplicate elements affect the result since collections are treated as sets.
Syntax
This test has the following syntax:
/*<collection>*/ contains neither /*<collection>*/
Alternatively, you can use the following syntax:
/*<collection>*/ includes neither /*<collection>*/
Both forms have the same semantics. You can use whichever makes your query more expressive and easier to read.
You can negate the test to verify the contrary:
/*<collection>*/ does not contain neither /*<collection>*/
The same applies to the alternative syntax:
/*<collection>*/ does not include neither /*<collection>*/
However, consider using the contains either test instead of negating, as it is more expressive and easier to understand.
Parameters
These are the supported parameters:
- collectioncollection
The collection to check.
- subsetcollection
The collection whose elements must not be contained in the other collection.
Examples
Here is an example of a collection that does not contain any of the elements of another collection:
["a", "b", "c"] contains neither ["d", "e", "f"] // true
And here is a counterexample:
["a", "b", "c"] contains neither ["a", "d", "e"] // false
To negate the test, you can write:
["a", "b", "c"] does not contain neither ["d", "e", "f"] // false
If the second collection is empty, the result is always true:
["a", "b", "c"] contains neither [] // true