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.

TestDescription
BeforeChecks whether a date time is before another.
AfterChecks whether a date time is after another.
At timeChecks 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.

Croct's mascot neutral
How does it differ from the less-than test?

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

To negate the test, you can write:

/*<value>*/ is not before /*<instant>*/
Try in Playground

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 "2024-05-22" // true
Try in Playground

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.

Croct's mascot neutral
How does it differ from the greater-than test?

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

To negate the test, you can write:

/*<value>*/ is not after /*<instant>*/
Try in Playground

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 "2024-05-22" // true
Try in Playground

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

To negate the test, you can write:

/*<value>*/ is not at /*<time>*/
Try in Playground

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

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