Batch or queue? Choosing the right tool for long-running work

Any job that outlives a single request needs to be broken up. Drupal gives you two mechanisms for that, and they solve different problems.

Batch: a person is waiting

The Batch API runs work in chunks across successive requests while showing a progress bar. It suits operations an administrator triggers and watches: bulk edits, a one-off import, an update routine. The browser drives it, so if the person closes the tab, the work stops.

Queue: nobody is waiting

The Queue API records items of work to be processed later, usually by cron or a dedicated worker. It suits anything triggered by the system rather than a person: sending notifications, regenerating derivatives, syncing to a third-party API. Processing is decoupled from the request that created the item.

The rules that keep queues healthy

• Make items small and self-describing. Store an identifier, not a loaded object — the entity may have changed by the time the worker runs.
• Make processing idempotent. An item may be processed more than once after a timeout; running twice must not corrupt anything.
• Handle failure explicitly. Decide whether a failed item should be released for retry or discarded, and log the difference.
• Watch depth, not just errors. A queue that grows faster than it drains is a failure in progress.

A practical default

If a human triggered it and expects to see it finish, use Batch. If the system triggered it and nobody is watching, use a queue — and give yourself a way to see how deep it is.