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:

TestDescription
EqualChecks whether two values are equal.
Less thanChecks whether a value is less than another value.
Less than or equalChecks whether a value is less than or equal to another.
Greater thanChecks whether a value is greater than another value.
Greater than or equalChecks whether a value is greater than or equal to another.
BetweenChecks 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>*/
Try in Playground

When comparing a value to a literal, you can use the following shorthand syntax:

/*<value>*/ is /*<literal>*/
Try in Playground

Both forms have the same semantics, but the shorthand syntax only works with literals and does not support specifying the comparison mode.

For inequality, you can use the following syntax:

/*<value>*/ is not equal to /*<reference>*/
Try in Playground

You can optionally specify a comparison mode:

/*<value>*/ is equal to /*<reference>*/ /*<mode>*/
Try in Playground

The following table describes the supported modes:

ModeDescription
ignoring caseCompare strings ignoring case. For example, "foo" is equal to "FOO" in this mode.
ignoring timeCompare date-time values ignoring time. For example, 2024-07-21T00:00:00 is equal to 2024-07-21T23:59:59 in this mode.
ignoring fractionCompare numbers ignoring the decimal part. For example, 1.5 is equal to 1.9 in this mode.
considering numbersCompare 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
Try in Playground

You can also use the shorthand syntax for literals. The following example is equivalent to the previous one:

1 + 2 is 3 // true
Try in Playground

The shorthand syntax works only with literals, so the following example is invalid:

1 + 2 is result // 🚨 Invalid
Try in Playground

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

In the same way, you can check whether a date-time value is equal to another, ignoring time:

"2024-07-21" is equal to "2024-07-21T23:59:59" ignoring time // true
Try in Playground

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

To negate the test, you can write:

/*<value>*/ is not less than /*<reference>*/
Try in Playground

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

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

To negate the test, you can write:

/*<value>*/ is not less than or equal to /*<reference>*/
Try in Playground

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

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

To negate the test, you can write:

/*<value>*/ is not greater than /*<reference>*/
Try in Playground

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

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

To negate the test, you can write:

/*<value>*/ is not greater than or equal to /*<reference>*/
Try in Playground

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

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

To negate the test, you can write:

/*<value>*/ is not between /*<lower-bound>*/ and /*<upper-bound>*/
Try in Playground

You can also specify whether the test is inclusive or exclusive:

/*<value>*/ is between /*<lower-bound>*/ and /*<upper-bound>*/ <bound-type>
Try in Playground

The following bound types are supported:

Bound typeDescription
inclusiveIncludes the lower and upper bounds when checking whether the value is between them. This is the default bound type.
exclusiveExcludes 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
Try in Playground

To make the test exclusive, you can write:

1 is between 1 and 3 exclusive // false
Try in Playground

It also works with date and time values:

today is between yesterday and tomorrow // true
Try in Playground