Comparison tests
Discover the different comparison tests available in CQL.
Comparison tests are natural language conditions that you can use to compare two values for equality or order. These tests include, for example, checking whether a value is equal, greater than, or less than another value.
The comparison tests behave exactly like comparison operations, which means you can use them interchangeably in most cases. It is just a more expressive way of writing conditions.
The following table summarizes the available comparison tests for quick reference:
| Test | Description |
|---|---|
| Equal | Checks whether two values are equal. |
| Less than | Checks whether a value is less than another value. |
| Less than or equal | Checks whether a value is less than or equal to another. |
| Greater than | Checks whether a value is greater than another value. |
| Greater than or equal | Checks whether a value is greater than or equal to another. |
| Between | Checks whether a value is between two other values. |
Equal
This test checks whether two values are equal, with the option to specify a comparison mode.
By default, this test uses the same equivalence rules as the equal operation, making them almost interchangeable, except for the order of evaluation. However, specifying a comparison mode makes the test behave differently.
Syntax
This test has the following syntax:
/*<value>*/ is equal to /*<reference>*/
When comparing a value to a literal, you can use the following shorthand syntax:
/*<value>*/ is /*<literal>*/
Both forms have the same semantics, but the shorthand syntax only works with literals and does not support specifying the comparison mode.
Always use the full syntax when comparing a value to a non-literal, such as a variable or expression. Using the shorthand form will result in a syntax error.
For inequality, you can use the following syntax:
/*<value>*/ is not equal to /*<reference>*/
You can optionally specify a comparison mode:
/*<value>*/ is equal to /*<reference>*/ /*<mode>*/
The following table describes the supported modes:
| Mode | Description |
|---|---|
| ignoring case | Compare strings ignoring case. For example, "foo" is equal to "FOO" in this mode. |
| ignoring time | Compare date-time values ignoring time. For example, 2023-12-03T00:00:00 is equal to 2023-12-03T23:59:59 in this mode. |
| ignoring fraction | Compare numbers ignoring the decimal part. For example, 1.5 is equal to 1.9 in this mode. |
| considering numbers | Compare values numerically, even if they are strings. For example, 1 is equal to "1.0" in this mode. |
By default, the comparison behaves exactly like the equal operation.
Parameters
These are the supported parameters:
- valuecomparable
The value to check for equality.
- referencecomparable
The other value to compare against.
Examples
Here is a basic example of how to check whether a value is equal to another value:
1 + 2 is equal to 3 // true
You can also use the shorthand syntax for literals. The following example is equivalent to the previous one:
1 + 2 is 3 // true
The shorthand syntax works only with literals, so the following example is invalid:
1 + 2 is result // 🚨 Invalid
You can specify a comparison mode to change the comparison behavior. For example, the following condition checks whether a string is equal to another, ignoring case:
"foo" is equal to "FOO" ignoring case // true
In the same way, you can check whether a date-time value is equal to another, ignoring time:
"2023-12-03" is equal to "2023-12-03T23:59:59" ignoring time // true
Less than
This test checks whether a value is less than another value. In terms of semantics, this test is equivalent to the less than operation.
Syntax
This test has the following syntax:
/*<value>*/ is less than /*<reference>*/
To negate the test, you can write:
/*<value>*/ is not less than /*<reference>*/
Parameters
These are the supported parameters:
- valuecomparable
The value to compare with a reference value.
- referencecomparable
The reference value for comparison.
Examples
Here is a basic example of how to check whether a value is less than another value:
1 + 2 is less than 4 // true
Less than or equal
This test checks whether a value is less than or equal to another. In terms of semantics, this test is equivalent to the less than or equal operation.
Syntax
This test has the following syntax:
/*<value>*/ is less than or equal to /*<reference>*/
To negate the test, you can write:
/*<value>*/ is not less than or equal to /*<reference>*/
Parameters
These are the supported parameters:
- valuecomparable
The value to compare with the reference value.
- referencecomparable
The value to compare against.
Examples
Here is a basic example of how to check whether a value is less than or equal to another:
1 + 2 is less than or equal to 3 // true
Greater than
This test checks whether a value is greater than another value. In terms of semantics, this test is equivalent to the greater than operation.
Syntax
This test has the following syntax:
/*<value>*/ is greater than /*<reference>*/
To negate the test, you can write:
/*<value>*/ is not greater than /*<reference>*/
Parameters
These are the supported parameters:
- valuecomparable
The value to compare with the reference value.
- referencecomparable
The value to compare against.
Examples
Here is a basic example of how to check whether a value is greater than another value:
1 + 2 is greater than 1 // true
Greater than or equal
This test checks whether a value is greater than or equal to another. In terms of semantics, this test is equivalent to the greater or equal operation.
Syntax
This test has the following syntax:
/*<value>*/ is greater than or equal to /*<reference>*/
To negate the test, you can write:
/*<value>*/ is not greater than or equal to /*<reference>*/
Parameters
These are the supported parameters:
- valuecomparable
The value to compare with the reference value.
- referencecomparable
The value to compare against.
Examples
Here is a basic example of how to check whether a value is greater than or equal to another:
1 + 2 is greater than or equal to 3 // true
Between
This test checks whether a value is between two other values. In terms of semantics, this test is equivalent to chaining relational operations.
You can choose whether the test is inclusive or exclusive. That is, you can decide whether or not the value can be equal to the lower or upper bound. By default, the test is inclusive.
This test inherits the short-circuit optimization from the logical operation. This means that if the lower-bound condition fails, the evaluation of the upper-bound condition is skipped.
Syntax
This test has the following syntax:
/*<value>*/ is between /*<lower-bound>*/ and /*<upper-bound>*/
To negate the test, you can write:
/*<value>*/ is not between /*<lower-bound>*/ and /*<upper-bound>*/
You can also specify whether the test is inclusive or exclusive:
/*<value>*/ is between /*<lower-bound>*/ and /*<upper-bound>*/ <bound-type>
The following bound types are supported:
| Bound type | Description |
|---|---|
| inclusive | Includes the lower and upper bounds when checking whether the value is between them. This is the default bound type. |
| exclusive | Excludes the lower and upper bounds when checking whether the value is between them. |
Parameters
These are the supported parameters:
- valuecomparable
The value to compare with two other values.
- lower-boundcomparable
The lower bound.
- upper-boundcomparable
The upper bound.
Examples
Here is a basic example of how to check whether a value is between two other values:
1 is between 1 and 3 // true
To make the test exclusive, you can write:
1 is between 1 and 3 exclusive // false
It also works with date and time values:
today is between yesterday and tomorrow // true