Introduction

A cron expression represents a set of times, using 6 space-separated fields.

Seconds Minutes Hours Day Month Week

i.e., 秒 分 时 日 月 周

The meaning of each field is as follows:

Field name    | Allowed values  | Allowed special characters
----------    | --------------  | --------------------------
Seconds       | 0-59            | * / , - #
Minutes       | 0-59            | * / , -
Hours         | 0-23            | * / , -
Day           | 1-31            | * / , - ?
Month         | 1-12 or JAN-DEC | * / , -
Week          | 0-6 or SUN-SAT  | * / , - ?

warning

Month and week field values are case-insensitive. For example, SUN, Sun, and sun are equally accepted.

Special Characters

Asterisk (*)

An asterisk means that the cron expression will match all values. For example, using an asterisk in the fifth field (Month) means every month.

Slash (/)

Slash is used to describe increments of ranges. For instance, using 3-59/15 in the second field means executing every 15 minutes starting from the 3rd minute to the 59th minute of every hour.

Comma (,)

Comma is used to separate items of a list. For example, using MON,WED,FRI in the fifth field will indicate execution on Monday, Wednesday, and Friday of each week.

Hyphen (-)

Hyphen is used to define ranges. For example, using 9-17 in the third field indicates from 9 AM to 5 PM (inclusive) every day.

Ignore Sign (#)

The ignore sign means the cron expression will bypass the use of this field. Currently, only the seconds field supports this symbol, for seamlessly converting 6 segment cron pattern to 5 segment linux crontab pattern.

Question Mark (?)

A question mark can be used instead of * to leave the Day or Week field blank.

Predefined Formats

You can use several predefined times instead of a cron expression.

Entry                  | Description                                | Equivalent To
-----                  | -----------                                | -------------
@yearly (or @annually) | Run once a year, midnight, Jan. 1st        | 0 0 0 1 1 *
@monthly               | Run once a month, midnight, first of month | 0 0 0 1 * *
@weekly                | Run once a week, midnight between Sat/Sun  | 0 0 0 * * 0
@daily (or @midnight)  | Run once a day, midnight                   | 0 0 0 * * *
@hourly                | Run once an hour, beginning of hour        | 0 0 * * * *

Intervals

You can also define a task to run at a fixed interval, starting when added. This is supported by formatting the cron specification as follows:

@every <duration>

where duration is a string accepted by time.ParseDuration (http://golang.org/pkg/time/#ParseDuration).

For instance, @every 1h30m10s would mean executing every 1 hour, 30 minutes, and 10 seconds after the task is added.

warning

Intervals do not consider the execution overhead time of tasks. For example, if a task takes 3 minutes to complete and is scheduled to run every 5 minutes, there will only be 2 minutes of idle time between each task.

Expression Examples

Notes 🔥

All programming language-level 6 segment cron pattern designs, practically, have certain design flaws due to the inaccuracy of underlying timers. Since cron pattern is accurate to the second, when delay reaches the second level, tasks may be lost. Moreover, if the golang engine scheduling is relatively slow, such delays can easily reach the second level, leading to logical issues within the program.

Considering that most scenarios do not require such precise control of scheduling at the second level, starting from framework version v2.7, we offer an ignore symbol # for the seconds field to convert 6 segment cron pattern into 5 segment linux crontab pattern, making it more robust. If the scenario requires second-level granularity scheduling, consider using the gtimer timer; however, bear in mind that no timer is entirely accurate and you cannot completely rely on the underlying system time.