Terms
| Term | Meaning |
|---|---|
| Queue | A named store of messages in a project, standard or fifo. Its ID is a UUID, and its slug starts with que_. Its name (1 to 80 letters, digits, - and _) is unique in the project. The name and type are fixed at creation. |
| Message | A UTF-8 text body and up to 10 string attributes, at most 256 KiB together. Each has a UUID messageId assigned when it’s sent. |
| Receive | A consumer’s request for up to 10 messages. Received messages are in flight: hidden from other consumers until they’re acknowledged or their visibility timeout ends. |
| Receipt handle | An opaque string returned with each received message. It acknowledges the message, or changes its visibility timeout, for that delivery only. |
| Subscription | A queue’s managed consumer: Queues pushes its messages in batches to your HTTPS endpoint. A queue has at most one. Its slug starts with qsb_. See Push subscriptions. |
| Dead-letter queue | A queue that another queue’s redrive policy names: messages received too many times move there. See Dead-letter queues. |
Standard and FIFO queues
| Standard | FIFO | |
|---|---|---|
| Delivery | At least once: a message can be delivered more than once | At least once, in order within each message group |
| Order | Best effort | Strict per message group (groupId, required on every send) |
| Duplicate sends | Stored again | Not stored again within 5 minutes of a send with the same dedupId |
| Delay per message | delaySeconds on each message, or the queue’s |
The queue’s delaySeconds only |
| Throughput | 3,000 send and 3,000 receive requests a second per queue, by default | 300 of each a second per queue, by default; one group’s messages are handled one batch at a time |
Write consumers so handling a message twice is harmless, on either type: a consumer can crash after doing the work and before acknowledging it. See FIFO queues for groups and deduplication.
Queue settings
| Setting | Default | Range | Meaning |
|---|---|---|---|
visibilityTimeoutSeconds |
30 | 0 to 43,200 (12 hours) | How long a received message stays hidden from other consumers |
retentionSeconds |
345,600 (4 days) | 60 to 1,209,600 (14 days) | How long a message is kept after it’s sent |
delaySeconds |
0 | 0 to 900 | How long a new message waits before it can be received |
receiveWaitSeconds |
0 | 0 to 20 | How long a receive waits for messages when it doesn’t say |
redrive |
null |
{ "deadLetterQueue": "<queue id>", "maxReceiveCount": 1–1000 } |
Where messages go after maxReceiveCount receives |
contentBasedDedup |
false |
FIFO only | Deduplicate sends without a dedupId by their body |
Change them with UpdateQueue. A new visibility timeout applies
to receives from then on, and a new retention to messages sent from then on: messages already in
flight keep their deadlines. "redrive": null removes the redrive policy.
The life of a message
- Sent. SendMessages stores it. With a delay it’s delayed; otherwise it’s visible at once.
- Received. A receive claims it and returns it with a receipt handle. It’s in flight
for the visibility timeout, and its
receiveCountgoes up by one. - Then one of these:
- Acknowledged with its receipt handle: it’s deleted.
- Released (its visibility changed to 0), or its visibility timeout ends: it’s visible again, and the next receive gets it.
- Dead-lettered: a receive finds it has already been received
maxReceiveCounttimes, and moves it to the dead-letter queue instead of returning it. - Expired: its queue’s retention ends, counted from when it was sent, received or not.
- Purged, or deleted with its queue.
A queue’s counts give the messages in each state: visible, inFlight and delayed. They’re
approximate, and exact up to 100,000 each; beyond that truncated is true.
Visibility timeouts
The visibility timeout is how long a consumer has to handle a message before another consumer can receive it. Set it longer than your consumer usually takes:
- Per queue, with
visibilityTimeoutSeconds. - Per receive, with the receive’s own
visibilityTimeoutSeconds. - Per message, after receiving it, by changing its visibility:
a consumer that needs longer extends it, and one that can’t handle a message releases it at
once with
0.
A message stays in flight for at most 12 hours from the receive, however often it’s extended.
Receipt handles
Each receive of a message returns a new receipt handle. A handle:
- Acknowledges the message or changes its visibility on
https://queues-live.ezghcloud.com, without a credential. Treat handles as you would a credential for that one message. - Works for that delivery only. Once the message is received again, acknowledged, moved to a
dead-letter queue, purged or expired, the handle is stale: using it fails with
receipt_handle_staleand changes nothing. - Still works after the visibility timeout ends, until another receive takes the message.
So a consumer that loses its access can still acknowledge or extend messages it already holds, until they’re received again; it can’t receive new ones.
Long polling
A receive with waitSeconds above 0 is a long poll: it answers as soon as messages are available,
or with an empty list when the wait ends. Long polls answer within moments of a send, so consumers
don’t need to poll in a loop with sleeps, and an empty answer costs one request per wait instead
of many. Use waitSeconds: 20, or set the queue’s receiveWaitSeconds to 20 so every receive
waits.
Purging and deleting
- PurgeQueue deletes every message sent before the purge, in flight or not; messages sent after it are kept. They disappear at once and are deleted in the background. A queue can be purged once every 60 seconds.
- DeleteQueue deletes the queue, its subscription and its
messages. Waiting receives answer
404, and the messages’ receipt handles become stale. A queue that another queue names as its dead-letter queue can’t be deleted (409 queue_in_use): remove that redrive policy first.
Partitions
A queue’s partitions is 1 when it’s created. Queues raises it, up to 64, when the queue’s send
rate grows, so busy queues spread their messages without any setting. On a FIFO queue a message
group never splits across partitions, so its order holds.