Date and time tests
Discover the different date and time tests available in CQL.
Date-time tests are natural language conditions that you can use to check whether dates and times meet certain criteria. These tests include, for example, checking whether a date is before, after, or at a certain time.
The following table summarizes the available date-time tests for quick reference.
| Test | Description |
|---|---|
| Before | Checks whether a date time is before another. |
| After | Checks whether a date time is after another. |
| At time | Checks whether a date time is at a specific time of day. |
Before
This test checks whether a date or instant is before another. It is the opposite of the after test.
When comparing dates, this test first converts both values to an instant based on the time zone set at the application level. Then it compares the instants using the same rules as relational operators to ensure consistency with the less than operation.
For more information about how dates are converted to instants, see the section on Instant conversion.
This test converts its arguments to instants before comparing them, while the less than test simply fails if the arguments are incompatible.
Syntax
This test has the following syntax:
/*<value>*/ before /*<instant>*/
To negate the test, you can write:
/*<value>*/ is not before /*<instant>*/
Parameters
These are the supported parameters:
- valueDate|DateTime
The date time to compare with the reference value.
- referenceDate|DateTime
The date time to compare against.
Examples
Here is a basic example of how to compare two dates:
yesterday is before "2023-12-03" // true
You can use any valid ISO 8601 date-time string as an argument.
After
This test checks whether a date or instant is after another. It is the opposite of the before test.
When comparing dates, this test first converts both values to an instant based on the time zone set at the application level. It then compares the instants using the same rules as relational operators to ensure consistency with the greater than operation.
For more information about how dates are converted to instants, see the section on Instant conversion.
This test converts its arguments to instants before comparing them, while the greater than test simply fails if the arguments are incompatible.
Syntax
This test has the following syntax:
/*<value>*/ after /*<instant>*/
To negate the test, you can write:
/*<value>*/ is not after /*<instant>*/
Parameters
These are the supported parameters:
- valueDate|DateTime
The date time to compare with the reference value.
- referenceDate|DateTime
The date time to compare against.
Examples
Here is a basic example of how to compare two dates:
tomorrow is after "2023-12-03" // true
You can use any valid ISO 8601 date-time string as an argument.
At time
This test checks whether a date or instant is at a specific time of day.
When comparing dates, this test first converts the value to an instant based on the time zone set at the application level. It then checks whether the instant is at the specified time of day.
For more information about how dates are converted to instants, see the section on Instant conversion.
Syntax
This test has the following syntax:
/*<value>*/ is at /*<time>*/
To negate the test, you can write:
/*<value>*/ is not at /*<time>*/
Parameters
These are the supported parameters:
- valueDate|DateTime
The date time to match against the specified time of day.
- timeTime
The time of day. This can be a time value or a valid ISO 8601 time string, such as 12:00:00 or 12:00.
Examples
Here is a basic example of how to check whether it is noon:
now is at "12:00" // false
Because the ISO 8601 standard allows you to omit subcomponents of a time value, you can also write the previous example as:
now is at 12 // false