# 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>*/

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.

### Syntax

This test has the following syntax:

/*<collection>*/ contains neither /*<collection>*/

Alternatively, you can use the following syntax:

/*<collection>*/ includes neither /*<collection>*/

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