Inbox functions in the Radio DuckDB extension
Function category
Inbox
3 functionsQueryable table views of received messages — across all subscriptions or filtered to one. Drain like any DuckDB table; the buffer is in-process and FIFO per subscription.
Signature
Description
Returns the messages held in every subscription's receive queue: subscription_id, subscription_url, message_id, message_type (message, error, connection, disconnection), receive_time, seen_count, channel and the message payload as BLOB (use decode(message) for UTF-8 text). Reading a message increments its seen_count; messages stay in the queue until they are evicted by newer ones or the subscription is closed.
DuckDB 2.0 build: the queue is read when the query runs, so a prepared statement sees current messages on every EXECUTE.
SELECT receive_time, channel, decode(message) AS text FROM radio_received_messages() WHERE message_type = 'message' ORDER BY receive_time DESC LIMIT 100;
SELECT channel, decode(message) AS text, seen_count FROM radio_received_messages();
Related functions
- radio_subscription_received_messages() — Returns the messages in one subscription's receive queue: `message_id`, `receive_time`, `seen_count`, `channel` and `message` (`BLOB`)
- radio_flush() — Waits up to `timeout` for every subscription's transmit queue to finish (send, or give up on) its pending messages
Signature
Arguments (Positional)
| Argument | Type | Mode | Description |
|---|---|---|---|
Argument
url
|
Type
VARCHAR
|
Mode Positional | Description |
Argument
channel
|
Type
VARCHAR
|
Mode Positional | Description |
Argument
message
|
Type
BLOB | VARCHAR
2 concrete typesBLOBVARCHAR
|
Mode Positional | Description |
Description
Adds a message to a subscription's receive queue as if it had arrived from the network and returns its message_id. Useful for testing SQL that consumes radio_* tables without a real upstream. Wakes any waiting radio_listen.
DuckDB 2.0 build: the message may be VARCHAR (previously only BLOB, so non-ASCII text had to be cast) and the channel may be NULL.
SELECT * FROM radio_subscription_received_message_add('loopback://demo', 'news', 'héllo');
Signature
Arguments (Positional)
| Argument | Type | Mode | Description |
|---|---|---|---|
Argument
url
|
Type
VARCHAR
|
Mode Positional | Description |
Description
Returns the messages in one subscription's receive queue: message_id, receive_time, seen_count, channel and message (BLOB). Reading increments seen_count. Raises an error if the URL is not subscribed.
SELECT receive_time, decode(message) AS text FROM radio_subscription_received_messages('wss://stream.example.com/events') ORDER BY receive_time DESC;
SELECT message_id, decode(message) AS text FROM radio_subscription_received_messages('loopback://demo');