Simple Message Queue (SMQ, formerly MNS) supports delayed messages, which postpone message visibility by a specified number of seconds. During the delay period, messages remain in the queue but are invisible to consumers. You can apply delays at the queue level (all messages in a queue) or at the message level (individual messages).
Use cases
Distributed scheduled tasks
Systems that trigger actions at varying intervals -- for example, running a file cleanup job daily or sending push notifications every two minutes -- can model each task as a delayed message. This approach eliminates the need for custom timer infrastructure built on top of a database.
Timeout-based workflows
In e-commerce, an unpaid order is typically canceled after a set window instead of being canceled immediately. Instead of polling a database to check order status, send a delayed message that fires after the timeout period and triggers the cancellation check.
Compared to database-scanning approaches, delayed messages provide two advantages:
Flexible timing: Set delays at any granularity from seconds to days, with no fixed time increments and no deduplication logic.
Scalability: Handle high concurrency without the performance bottlenecks caused by frequent database scans.
Queue-level vs. message-level delays
SMQ provides two levels of delay configuration:
| Level | When to set | Parameter | Effect |
|---|---|---|---|
| Queue-level | When creating a queue | DelaySeconds | All messages sent to the queue are delayed by this value. |
| Message-level | When sending a message | DelaySeconds | Only the specific message is delayed by this value. |
Both levels accept a value from 0 to 604,800 seconds (up to 7 days).
Priority rules
When both a queue-level and a message-level delay are set, the following rules determine which value takes effect:
Message-level DelaySeconds | Queue-level DelaySeconds | Result |
|---|---|---|
| Greater than 0 | Any value (0 or greater) | Message-level delay applies. The queue-level setting is overridden. |
| 0 or not set | Greater than 0 | Queue-level delay applies. |
Example: Queue Queue-A has DelaySeconds set to 600 seconds (10 minutes).
Message1is sent withDelaySeconds= 30. The message becomes visible after 30 seconds, not 600.Message2is sent withDelaySeconds= 1,200. The message becomes visible after 1,200 seconds (20 minutes).Message3is sent without aDelaySecondsvalue. The queue-level delay of 600 seconds applies.
Message lifecycle
Delayed messages follow the same lifecycle as standard messages, with one additional initial state:
| State | Description |
|---|---|
| Being scheduled | The message has been sent to the broker but the delay period has not elapsed. The message is invisible to consumers. |
| Visible | The delay period has ended. The message is available for consumers to receive. |
| Invisible | A consumer has received the message. Other consumers cannot retrieve it during this state. |
| Deleted | The consumer has processed the message and called the deletion operation to remove it from the queue. |
Monitoring
Track delayed messages in the scheduled state with the NumberOfMessagesDelayed metric in Cloud Monitor. For details, see Cloud Monitor metrics.