Assigning priority to tasks in Hatchet

Hatchet allows you to assign different priority values to your tasks depending on how soon you want them to run. priority can be set to either 1, 2, or 3, (low, medium, and high, respectively) with relatively higher values resulting in that task being picked up before others of the same type. By default, runs in Hatchet have a priority of 1 (low) unless otherwise specified.

🪓

Priority only affects multiple runs of a single workflow. If you have two different workflows (A and B) and set A to globally have a priority of 3, and B to globally have a priority of 1, this does not guarantee that if there is one task from A and one from B in the queue, that A’s task will be run first.

However, within A, if you enqueue one task with priority 3 and one with priority 1, the priority 3 task will be run first.

A couple of common use cases for assigning priorities are things like:

Having high-priority (e.g. paying, new, etc.) customers be prioritized over lower-priority ones, allowing them to get faster turnaround times on their tasks.
Having tasks triggered via your API run with higher priority than the same tasks triggered by a cron.

Setting priority for a task or workflow

There are a few different ways to set priorities for tasks or workflows in Hatchet.

Workflow-level default priority

First, you can set a default priority at the workflow level:

examples/priority/worker.py

DEFAULT_PRIORITY = 1
SLEEP_TIME = 0.25

priority_workflow = hatchet.workflow(
    name="PriorityWorkflow",
    default_priority=DEFAULT_PRIORITY,
    concurrency=ConcurrencyExpression(
        max_runs=1,
        expression="'true'",
        limit_strategy=ConcurrencyLimitStrategy.GROUP_ROUND_ROBIN,
    ),
)

src/v1/examples/priority/workflow.ts

export const priorityWf = hatchet.workflow({
  name: 'priorityWf',
  defaultPriority: Priority.LOW,
});

examples/v1/workflows/priority.go

defaultPriority := int32(1)

workflow := factory.NewWorkflow[PriorityInput, Result](
	create.WorkflowCreateOpts[PriorityInput]{
		Name:            "priority",
		DefaultPriority: &defaultPriority,
	},
	hatchet,
)

This will assign the same default priority to all runs of this workflow (and all of the workflow’s corresponding tasks), but will have no effect without also setting run-level priorities, since every run will use the same default.

Priority-on-trigger

When you trigger a run, you can set the priority of the triggered run to override its default priority.

examples/priority/trigger.py

low_prio = priority_workflow.run_no_wait(
    options=TriggerWorkflowOptions(
        ## 👀 Adding priority and key to metadata to show them in the dashboard
        priority=1,
        additional_metadata={"priority": "low", "key": 1},
    )
)

high_prio = priority_workflow.run_no_wait(
    options=TriggerWorkflowOptions(
        ## 👀 Adding priority and key to metadata to show them in the dashboard
        priority=3,
        additional_metadata={"priority": "high", "key": 1},
    )
)

src/v1/examples/priority/run.ts

const run = priority.run(new Date(Date.now() + 60 * 60 * 1000), { priority: Priority.HIGH });

examples/v1/run/priority.go

priority := int32(3)

runId, err := priorityWorkflow.RunNoWait(ctx, v1_workflows.PriorityInput{
	UserId: "1234",
}, client.WithPriority(priority))

Similarly, you can also assign a priority to scheduled and cron workflows.