Queues provide distributed, FIFO (First-In-First-Out) queues for managing data flow between Modal Functions and Sandboxes.
Access the Queues API import { ModalClient } from "modal" ; const modal = new ModalClient (); const queue = await modal . queues . fromName ( "my-queue" );
Methods modal.queues.fromName(name, params?)Reference a Queue by name.
Optional parameters If true, creates the Queue if it doesn’t exist.
const queue = await modal . queues . fromName ( "tasks" , { createIfMissing: true , });
modal.queues.ephemeral(params?)Create a temporary, nameless Queue. It persists until closeEphemeral() is called.
The ephemeral Queue object.
const queue = await modal . queues . ephemeral (); // Use the queue... queue . closeEphemeral (); // Clean up
modal.queues.delete(name, params?)Delete a named Queue.
Name of the Queue to delete.
Optional parameters If true, don’t throw an error if the Queue doesn’t exist.
await modal . queues . delete ( "old-queue" );
Deletion is irreversible and will affect any Apps currently using the Queue.
Queue object Properties Unique identifier for the Queue.
Name of the Queue, if it was looked up by name.
Methods put(value, params?)Add an item to the end of the Queue.
The value to enqueue (will be serialized).
Optional parameters How long to wait if the Queue is full in milliseconds (default: indefinite).
Partition to add item to (default partition if not set).
TTL for the partition in milliseconds (default: 1 day).
await queue . put ( "task-1" ); await queue . put ({ id: 123 , data: "example" }); // With timeout await queue . put ( "task-2" , { timeoutMs: 5000 }); // Use a partition await queue . put ( "high-priority" , { partition: "urgent" });
If the Queue is full, this will retry with exponential backoff until timeoutMs is reached.
putMany(values, params?)Add multiple items to the end of the Queue.
Array of values to enqueue.
await queue . putMany ([ "task-1" , "task-2" , "task-3" ]);
get(params?)Remove and return the next item from the Queue.
Optional parameters How long to wait if the Queue is empty in milliseconds (default: indefinite).
Partition to fetch from (default partition if not set).
The next item from the Queue.
const item = await queue . get (); console . log ( item ); // With timeout try { const item = await queue . get ({ timeoutMs: 5000 }); } catch ( err ) { // QueueEmptyError if timeout is reached console . log ( "Queue was empty" ); }
getMany(n, params?)Remove and return up to n items from the Queue.
Maximum number of items to retrieve.
Array of items (may be fewer than n if Queue doesn’t have enough items).
const items = await queue . getMany ( 10 ); console . log ( `Got ${ items . length } items` );
len(params?)Get the number of items in the Queue.
Optional parameters Partition to compute length for.
Return total length across all partitions.
Number of items in the Queue.
const length = await queue . len (); console . log ( `Queue has ${ length } items` ); // Total across all partitions const totalLength = await queue . len ({ total: true });
clear(params?)Remove all items from the Queue.
await queue . clear (); // Clear all partitions await queue . clear ({ all: true });
iterate(params?)Iterate through items in the Queue without removing them.
Optional parameters How long to wait between items before exiting iteration in milliseconds.
An async iterator of items.
for await ( const item of queue . iterate ()) { console . log ( item ); } // With timeout for await ( const item of queue . iterate ({ itemPollTimeoutMs: 1000 })) { console . log ( item ); }
closeEphemeral()Delete an ephemeral Queue. Only works with ephemeral Queues.
const queue = await modal . queues . ephemeral (); // Use queue... queue . closeEphemeral ();
Example: Producer-consumer pattern import { ModalClient } from "modal" ; const modal = new ModalClient (); const queue = await modal . queues . fromName ( "tasks" , { createIfMissing: true , }); // Producer: Add tasks to queue for ( let i = 0 ; i < 100 ; i ++ ) { await queue . put ({ taskId: i , data: `task- ${ i } ` }); } console . log ( `Added ${ await queue . len () } tasks` ); // Consumer: Process tasks while ( true ) { try { const task = await queue . get ({ timeoutMs: 5000 }); console . log ( `Processing task ${ task . taskId } ` ); // Process task... } catch ( err ) { console . log ( "No more tasks, done!" ); break ; } }
Example: Batch processing with partitions import { ModalClient } from "modal" ; const modal = new ModalClient (); const queue = await modal . queues . fromName ( "priority-tasks" , { createIfMissing: true , }); // Add tasks to different priority partitions await queue . putMany ( [ "urgent-1" , "urgent-2" ], { partition: "high" } ); await queue . putMany ( [ "normal-1" , "normal-2" , "normal-3" ], { partition: "normal" } ); // Process high priority first const highPriority = await queue . getMany ( 10 , { partition: "high" }); console . log ( "High priority tasks:" , highPriority ); // Then normal priority const normalPriority = await queue . getMany ( 10 , { partition: "normal" }); console . log ( "Normal priority tasks:" , normalPriority );