Runnables

Runnables in the Hatchet SDK are things that can be run, namely tasks and workflows. The two main types of runnables you'll encounter are:

Workflow, which lets you define tasks and call all of the run, schedule, etc. methods
Standalone, which is a single task that's returned by hatchet.task and can be run, scheduled, etc.

Workflow

Bases: BaseWorkflow[TWorkflowInput]

A Hatchet workflow, which allows you to define tasks to be run and perform actions on the workflow.

Workflows in Hatchet represent coordinated units of work that can be triggered, scheduled, or run on a cron schedule. Each workflow can contain multiple tasks that can be arranged in dependencies (DAGs), have customized retry behavior, timeouts, concurrency controls, and more.

Example:

from pydantic import BaseModel
from hatchet_sdk import Hatchet

class MyInput(BaseModel):
    name: str

hatchet = Hatchet()
workflow = hatchet.workflow("my-workflow", input_type=MyInput)

@workflow.task()
def greet(input, ctx):
    return f"Hello, {input.name}!"

# Run the workflow
result = workflow.run(MyInput(name="World"))

Workflows support various execution patterns including:

One-time execution with run() or aio_run()
Scheduled execution with schedule()
Cron-based recurring execution with create_cron()
Bulk operations with run_many()

Tasks within workflows can be defined with @workflow.task() or @workflow.durable_task() decorators and can be arranged into complex dependency patterns.

Methods

Name	Description
`task`	A decorator to transform a function into a Hatchet task that runs as part of a workflow.
`durable_task`	A decorator to transform a function into a durable Hatchet task that runs as part of a workflow.
`on_failure_task`	A decorator to transform a function into a Hatchet on-failure task that runs as the last step in a workflow that had at least one task fail.
`on_success_task`	A decorator to transform a function into a Hatchet on-success task that runs as the last step in a workflow that had all upstream tasks succeed.
`run`	Run the workflow synchronously and wait for it to complete.
`aio_run`	Run the workflow asynchronously and wait for it to complete.
`run_no_wait`	Synchronously trigger a workflow run without waiting for it to complete.
`aio_run_no_wait`	Asynchronously trigger a workflow run without waiting for it to complete.
`run_many`	Run a workflow in bulk.
`aio_run_many`	Run a workflow in bulk asynchronously.
`run_many_no_wait`	Run a workflow in bulk without waiting for all runs to complete.
`aio_run_many_no_wait`	Run a workflow in bulk without waiting for all runs to complete.
`schedule`	Schedule a workflow to run at a specific time.
`aio_schedule`	Schedule a workflow to run at a specific time.
`create_cron`	Create a cron job for the workflow.
`aio_create_cron`	Create a cron job for the workflow.
`create_bulk_run_item`	Create a bulk run item for the workflow. This is intended to be used in conjunction with the various `run_many` methods.
`list_runs`	List runs of the workflow.
`aio_list_runs`	List runs of the workflow.
`create_filter`	Create a new filter.
`aio_create_filter`	Create a new filter.

Attributes

`name`

The (namespaced) name of the workflow.

`tasks`

`id` `cached`

Get the ID of the workflow.

Name	Type	Description	Default
`name`	`str \| None`	The name of the task. If not specified, defaults to the name of the function being wrapped by the `task` decorator.	`None`
`schedule_timeout`	`Duration`	The maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time.	`timedelta(minutes=5)`
`execution_timeout`	`Duration`	The maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time.	`timedelta(seconds=60)`
`parents`	`list[Task[TWorkflowInput, Any]] \| None`	A list of tasks that are parents of the task. Note: Parents must be defined before their children.	`None`
`retries`	`int`	The number of times to retry the task before failing.	`0`
`rate_limits`	`list[RateLimit] \| None`	A list of rate limit configurations for the task.	`None`
`desired_worker_labels`	`dict[str, DesiredWorkerLabel] \| list[DesiredWorkerLabel] \| None`	A dictionary of desired worker labels that determine to which worker the task should be assigned. See documentation and examples on affinity and worker labels for more details.	`None`
`backoff_factor`	`float \| None`	The backoff factor for controlling exponential backoff in retries.	`None`
`backoff_max_seconds`	`int \| None`	The maximum number of seconds to allow retries with exponential backoff to continue.	`None`
`concurrency`	`int \| list[ConcurrencyExpression] \| None`	A list of concurrency expressions for the task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy, which means that only `N` runs of the task may execute at any given time.	`None`
`wait_for`	`list[Condition \| OrGroup] \| None`	A list of conditions that must be met before the task can run.	`None`
`skip_if`	`list[Condition \| OrGroup] \| None`	A list of conditions that, if met, will cause the task to be skipped.	`None`
`cancel_if`	`list[Condition \| OrGroup] \| None`	A list of conditions that, if met, will cause the task to be canceled.	`None`

Name	Type	Description	Default
`name`	`str \| None`	The name of the task. If not specified, defaults to the name of the function being wrapped by the `task` decorator.	`None`
`schedule_timeout`	`Duration`	The maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time.	`timedelta(minutes=5)`
`execution_timeout`	`Duration`	The maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time.	`timedelta(seconds=60)`
`parents`	`list[Task[TWorkflowInput, Any]] \| None`	A list of tasks that are parents of the task. Note: Parents must be defined before their children.	`None`
`retries`	`int`	The number of times to retry the task before failing.	`0`
`rate_limits`	`list[RateLimit] \| None`	A list of rate limit configurations for the task.	`None`
`desired_worker_labels`	`dict[str, DesiredWorkerLabel] \| list[DesiredWorkerLabel] \| None`	A dictionary of desired worker labels that determine to which worker the task should be assigned. See documentation and examples on affinity and worker labels for more details.	`None`
`backoff_factor`	`float \| None`	The backoff factor for controlling exponential backoff in retries.	`None`
`backoff_max_seconds`	`int \| None`	The maximum number of seconds to allow retries with exponential backoff to continue.	`None`
`concurrency`	`int \| list[ConcurrencyExpression] \| None`	A list of concurrency expressions for the task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy, which means that only `N` runs of the task may execute at any given time.	`None`
`wait_for`	`list[Condition \| OrGroup] \| None`	A list of conditions that must be met before the task can run.	`None`
`skip_if`	`list[Condition \| OrGroup] \| None`	A list of conditions that, if met, will cause the task to be skipped.	`None`
`cancel_if`	`list[Condition \| OrGroup] \| None`	A list of conditions that, if met, will cause the task to be canceled.	`None`
`eviction_policy`	`EvictionPolicy \| None`	An optional eviction policy controlling when this durable task can be evicted from a worker slot while waiting.	`DEFAULT_DURABLE_TASK_EVICTION_POLICY`

Name	Type	Description	Default
`name`	`str \| None`	The name of the on-failure task. If not specified, defaults to the name of the function being wrapped by the `on_failure_task` decorator.	`None`
`schedule_timeout`	`Duration`	The maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time.	`timedelta(minutes=5)`
`execution_timeout`	`Duration`	The maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time.	`timedelta(seconds=60)`
`retries`	`int`	The number of times to retry the on-failure task before failing.	`0`
`rate_limits`	`list[RateLimit] \| None`	A list of rate limit configurations for the on-failure task.	`None`
`backoff_factor`	`float \| None`	The backoff factor for controlling exponential backoff in retries.	`None`
`backoff_max_seconds`	`int \| None`	The maximum number of seconds to allow retries with exponential backoff to continue.	`None`
`concurrency`	`int \| list[ConcurrencyExpression] \| None`	A list of concurrency expressions for the on-failure task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy, which means that only `N` runs of the task may execute at any given time.	`None`

Name	Type	Description	Default
`name`	`str \| None`	The name of the on-success task. If not specified, defaults to the name of the function being wrapped by the `on_success_task` decorator.	`None`
`schedule_timeout`	`Duration`	The maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time.	`timedelta(minutes=5)`
`execution_timeout`	`Duration`	The maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time.	`timedelta(seconds=60)`
`retries`	`int`	The number of times to retry the on-success task before failing	`0`
`rate_limits`	`list[RateLimit] \| None`	A list of rate limit configurations for the on-success task.	`None`
`backoff_factor`	`float \| None`	The backoff factor for controlling exponential backoff in retries.	`None`
`backoff_max_seconds`	`int \| None`	The maximum number of seconds to allow retries with exponential backoff to continue.	`None`
`concurrency`	`int \| list[ConcurrencyExpression] \| None`	A list of concurrency expressions for the on-success task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy, which means that only `N` runs of the task may execute at any given time.	`None`

We use cookies