th queue: send and receive messages

About

The Queue Service passes messages from the part of your system that creates work to workers that do it. A received message is hidden for the visibility timeout; acknowledge it (delete it with its receipt) when the job is done, or it is handed out again. Messages are delivered at least once, so make jobs safe to repeat.

Setting	Default	Range
`--visibility-timeout`	30 seconds	0 seconds – 12 hours
`--retention`	4 days	1 minute – 14 days
`--delay`	0	0 – 15 minutes
`--max-receives`	0 (no limit)	0 – 1,000, then to the `--dead-letter` queue

A message is at most 256 KiB, body and attributes together. Durations take 30s, 5m, 2h, 4d or 1d12h. The message commands use a Queue Service access key (a short-lived one when you are signed in, or TH_QUEUE_KEY_ID / TH_QUEUE_SECRET). See also How Queue Service works.

How-to guides

Create a queue with a dead-letter queue

Shell

th queue create jobs-dlq
th queue create jobs --visibility-timeout 60s --max-receives 5 --dead-letter jobs-dlq

A message received more than 5 times without being acknowledged moves to jobs-dlq, where you can look at it with th queue peek jobs-dlq.

Send messages

Shell

th queue send jobs '{"order": 1042}'
th queue send jobs --file job.json --attr type=invoice
echo "hello" | th queue send jobs -
th queue send jobs '{"order": 1043}' --delay 10s

Receive and acknowledge

Receive: th queue receive jobs --max 10. Each message is printed with its receipt.
Do the work.
Acknowledge each one: th queue ack jobs RECEIPT…. Or pass --ack to receive to acknowledge right after printing.

Shell

th queue receive jobs --max 10 --wait 20s
th queue ack jobs <receipt-1> <receipt-2>

Tail a queue

th queue tail waits for messages, prints each one and acknowledges it, until you press Ctrl+C. Use --no-ack to watch without consuming (the messages come back after their visibility timeout), and --format json for one JSON object per line.

Shell

th queue tail jobs
th queue tail jobs --no-ack --format json | jq .body

Commands

Command	Description
`th queue create`	Creates a queue.
`th queue list`	Lists the Project's queues with their backlog.
`th queue describe`	Shows a queue's settings, endpoint and backlog.
`th queue update`	Changes a queue's settings; settings left out stay as they are.
`th queue send`	Sends one message.
`th queue receive`	Receives up to `--max` messages (1-10, default 1), waiting up to `--wait` (at most 20s) for a first one.
`th queue ack`	Acknowledges (deletes) received messages by their receipts.
`th queue tail`	Receives messages as they arrive (long polling) and prints them, one block each (one JSON object per line with `--format` json).
`th queue peek`	Shows up to 10 waiting messages without receiving them (they stay in the queue and their receive count does not change).
`th queue purge`	Removes every message of a queue; the queue stays.
`th queue delete`	Deletes a queue with all its messages.

`th queue create`

Creates a queue.

Syntax

Shell

th queue create NAME [--region REGION] [--visibility-timeout 30s]
    [--retention 4d] [--delay 0s] [--max-receives N --dead-letter QUEUE]

Names are 1-80 characters of A-Z, a-z, 0-9, _ and -. Settings left out take the service defaults. Durations take 30s, 5m, 2h, 4d or 1d12h.

Examples

Workers get 60 seconds per message

Shell

th queue create jobs --visibility-timeout 60s

Move failing messages to jobs-dlq

Shell

th queue create jobs --max-receives 5 --dead-letter jobs-dlq

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.

Parameters

Name	Type	Description
`--visibility-timeout`	string	How long a received message stays hidden (e.g. 30s, 5m, 12h)
`--retention`	string	How long a message is kept (e.g. 1h, 4d, 14d)
`--delay`	string	Delay before a new message can be received (e.g. 0s, 10s, 15m)
`--max-receives`	number	Receives before a message moves to the dead-letter queue (0 = no limit)
`--dead-letter`	string	Dead-letter queue of the same Project ("" or none to clear)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue list`

Lists the Project's queues with their backlog.

Syntax

Shell

th queue list

Examples

Queues and their backlog

Shell

th queue list

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue describe`

Shows a queue's settings, endpoint and backlog.

Syntax

Shell

th queue describe NAME

Examples

Settings, endpoint and backlog

Shell

th queue describe jobs

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue update`

Changes a queue's settings; settings left out stay as they are.

Syntax

Shell

th queue update NAME [--visibility-timeout 30s] [--retention 4d]
    [--delay 0s] [--max-receives N] [--dead-letter QUEUE|none]

Durations take 30s, 5m, 2h, 4d or 1d12h.

Examples

Keep messages 14 days

Shell

th queue update jobs --retention 14d

Stop using a dead-letter queue

Shell

th queue update jobs --dead-letter none

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.

Parameters

Name	Type	Description
`--visibility-timeout`	string	How long a received message stays hidden (e.g. 30s, 5m, 12h)
`--retention`	string	How long a message is kept (e.g. 1h, 4d, 14d)
`--delay`	string	Delay before a new message can be received (e.g. 0s, 10s, 15m)
`--max-receives`	number	Receives before a message moves to the dead-letter queue (0 = no limit)
`--dead-letter`	string	Dead-letter queue of the same Project ("" or none to clear)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue send`

Sends one message.

Syntax

Shell

th queue send NAME [MESSAGE | - | --file FILE] [--attr KEY=VALUE ...] [--delay 10s]

The body is MESSAGE, the contents of FILE, or standard input when MESSAGE is "-". A message is at most 256 KiB (body and attributes). --delay hides it for up to 15m first (default: the queue's).

Examples

Send a JSON body

Shell

th queue send jobs '{"order": 1042}'

Body from a file, with an attribute

Shell

th queue send jobs --file job.json --attr type=invoice

Body from standard input

Shell

echo "hello" | th queue send jobs -

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.
`MESSAGE\|-`Optional	The message body, or `-` to read it from standard input. Leave it out when you use `--file`.

Parameters

Name	Type	Description
`--file`	string	Read the body from FILE
`--attr`	list	Attribute KEY=VALUE (repeatable)
`--delay`	string	Delay before it can be received (e.g. 10s, 5m)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue receive`

Receives up to --max messages (1-10, default 1), waiting up to --wait (at most 20s) for a first one.

Syntax

Shell

th queue receive NAME [--max 10] [--wait 20s] [--visibility 30s] [--ack]

Received messages stay hidden for the visibility timeout; acknowledge each one you handled (th queue ack NAME RECEIPT) or it is handed out again. --ack acknowledges them right after printing.

Examples

Take up to 10 messages

Shell

th queue receive jobs --max 10

Take one and acknowledge it at once

Shell

th queue receive jobs --ack

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.

Parameters

Name	Type	Default	Description
`--max`	number	`1`	How many messages to take, 1-10
`--wait`	string		Long-poll up to this long for a first message (at most 20s)
`--visibility`	string		Hide received messages this long instead of the queue's timeout
`--ack`	flag		Acknowledge (delete) the messages after printing them

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue ack`

Acknowledges (deletes) received messages by their receipts.

Syntax

Shell

th queue ack NAME RECEIPT...

Acknowledging a message again is not an error.

Examples

Acknowledge a handled message

Shell

th queue ack jobs <receipt>

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.
`RECEIPT…`Required	The receipt printed with each received message. Give several to acknowledge them together.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue tail`

Receives messages as they arrive (long polling) and prints them, one block each (one JSON object per line with --format json).

Syntax

Shell

th queue tail NAME [--no-ack] [--max 10] [--visibility 30s]

Each printed message is acknowledged unless --no-ack is given, so tail works as a consumer; with --no-ack the messages are handed out again after their visibility timeout. Press Ctrl+C to stop.

Examples

Consume messages until Ctrl+C

Shell

th queue tail jobs

Watch without consuming, one JSON object per line

Shell

th queue tail jobs --no-ack --format json

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.

Parameters

Name	Type	Default	Description
`--max`	number	`10`	Messages per receive, 1-10 (default 10)
`--visibility`	string		Hide received messages this long instead of the queue's timeout
`--ack`	flag	`true`	Acknowledge each printed message (default true; `--no-ack` leaves them) `--no-ack` turns it off.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue peek`

Shows up to 10 waiting messages without receiving them (they stay in the queue and their receive count does not change).

Syntax

Shell

th queue peek NAME

Examples

Look at waiting messages without receiving them

Shell

th queue peek jobs-dlq

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue purge`

Removes every message of a queue; the queue stays.

Syntax

Shell

th queue purge NAME [--quiet]

--quiet skips the prompt.

Examples

Remove every message, no prompt

Shell

th queue purge jobs --quiet

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th queue delete`

Deletes a queue with all its messages.

Syntax

Shell

th queue delete NAME [--quiet]

--quiet skips the prompt.

Examples

Delete the queue and its messages

Shell

th queue delete jobs

Positional arguments

Name	Description
`NAME`Required	The queue name: 1–80 characters of A-Z, a-z, 0-9, _ and -.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

Help centre: the th command line