Skip to main content

Priority

View Markdown
TLDR

Assign a Priority key from 1 to 5 to Workflows, Activities, and Child Workflows. When Tasks are backlogged, Temporal dispatches higher-priority Tasks first. Use Priority when urgent work should move ahead of a backlog.

Overview​

Priority orders Task dispatches within a shared Task Queue. Lower Priority key values represent higher priority, so 1 is the highest priority and 5 is the lowest.

Priority applies to dispatch. It does not preempt running Tasks or reserve Worker capacity.

Problem​

Without Priority, backlogged Tasks are generally dispatched in first-in-first-out (FIFO) order within a Task Queue partition. A large batch can fill the backlog before urgent work arrives, delaying time-sensitive Tasks.

Separate Task Queues can isolate the backlogs, but require more routing and Worker configuration.

Solution​

Assign a Priority key to each Workflow, Activity, or Child Workflow. Within a Task Queue partition, the Matching Service dispatches the highest-priority backlogged Tasks first. Without Fairness, Tasks with the same Priority key are dispatched in FIFO order.

Tasks use Priority key 3 by default. Activities and Child Workflows inherit the parent Workflow's Priority key unless they set their own.

The diagram assumes all three levels have backlogged Tasks. Lower-priority Tasks wait for higher-priority backlogs to drain.

Implementation​

Priority is enabled by default in Temporal Cloud and self-hosted Temporal. Set a Priority key in Workflow start options or in Activity and Child Workflow options.

See Task Queue Priority for SDK and command-line examples, inheritance behavior, and self-hosted configuration.

When to use​

Use Priority when urgent and routine work share a Task Queue and Worker pool. For example, payment Tasks can dispatch ahead of inventory updates or batch reports.

Priority is a poor fit when high-priority work remains continuously backlogged because lower-priority Tasks can starve. Use separate Task Queues and Worker pools for capacity isolation. Use Fairness for tenant-aware dispatch within a Priority level.

Benefits and trade-offs​

Priority uses one Task Queue and Worker pool without additional routing. It supports five priority levels. Strict ordering can starve lower-priority Tasks and does not provide Worker capacity isolation.

Comparison with alternatives​

ApproachBacklog dispatchWorker capacity isolation
Priority on a shared Task QueueHigher-priority Tasks firstNone
Fairness on a shared Task QueueWeighted across groups within a Priority levelNone
Separate Task Queues with shared computeIndependent backlogsNone
Separate Task Queues with dedicated computeIndependent backlogsYes

Best practices​

  • Define a small set of levels. For example, use 1 for urgent work, 3 for normal work, and 5 for batch work.
  • Use inheritance. Set an Activity or Child Workflow's Priority key only when it should differ from its parent Workflow.

Common pitfalls​

  • Assigning Priority key 1 to all work. Priority cannot order Tasks when they all use the same key.
  • Expecting Priority across Task Queue partitions. Each partition orders its backlog independently.
  • Expecting Priority across Worker Deployment Versions. Each version has a separate backlog. Priority applies within each version's backlog.
  • Expecting FIFO order within a Priority level when using Fairness. Fairness controls dispatch within each Priority level.
  • Expecting every Task to pass through priority dispatch. Synchronous matching can send a Task directly to an idle poller. Eager Task Execution bypasses matching.
  • Ignoring lower-priority starvation. A sustained higher-priority backlog can prevent lower-priority Tasks from dispatching.

Patterns​