mirror/hatchet
1
0
Fork 0
mirror of https://github.com/hatchet-dev/hatchet.git synced 2026-04-22 01:40:12 -05:00
Code Issues Packages Projects Releases Wiki Activity

fix: finish rewriting triggering overview

Browse Source
This commit is contained in:
mrkaye97
2026-03-18 14:52:11 -04:00
parent 5aaadea353
commit 164bb42ea8
1 changed files with 26 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/docs/pages/v1/running-your-task.mdx
+26 -84
View File
@@ -6,11 +6,13 @@ import Keywords from "@/components/Keywords";
# Running Tasks
You can invoke tasks and workflows in a number of ways.
Once you've [defined some tasks](/v1/tasks) and registered them on a [worker](/v1/workers), you're ready to run them!
## Run and wait
Hatchet lets you run tasks in a number of ways, which support different application needs. In broad strokes, these are [fire-and-wait](#fire-and-wait), various forms of [fire-and-forget-style triggering](#fire-and-forget), and scheduling tasks to run either [periodically](#crons) or at some [specific time in the future](#scheduled-runs).
Invoke a task and block until it completes and returns a result. Use this for synchronous workflows like fanout, LLM calls, or any time the task's output is needed before continuing.
## Fire-and-wait
Fire-and-wait is a common way of triggering a task which blocks until it completes and returns a result. This is particularly useful for situations where you want to do something with the result of your task. For instance, if your tasks generates some LLM output which you want to return to the user or persist in the database, you might trigger a task, wait for it to complete, collect its result, and then continue on with your application logic.
<UniversalTabs items={["Python", "Typescript", "Go", "Ruby"]}>
<Tabs.Tab title="Python">
@@ -49,83 +51,13 @@ Call `run` on the `Task` object to invoke it. This blocks until the task complet
</Tabs.Tab>
</UniversalTabs>
### Spawning children
## Fire-and-forget
You can also spawn tasks and workflows from within another task. This is useful for composing tasks together, fanning out batched tasks, or creating conditional workflows. The Hatchet SDKs will automatically tie the child run to its parent in the dashboard for easier debugging.
<UniversalTabs items={["Python", "Typescript", "Go", "Ruby"]} variant="hidden">
<Tabs.Tab title="Python">
<Snippet
src={snippets.python.child.simple_fanout.running_a_task_from_within_a_task}
/>
</Tabs.Tab>
<Tabs.Tab title="Typescript">
<Snippet
src={snippets.typescript.simple.run.spawning_tasks_from_within_a_task}
/>
</Tabs.Tab>
<Tabs.Tab title="Go">
<Snippet src={snippets.go.simple.main.spawning_tasks_from_within_a_task} />
</Tabs.Tab>
<Tabs.Tab title="Ruby">
<Snippet src={snippets.ruby.child.simple_fanout.running_a_task_from_within_a_task} />
</Tabs.Tab>
</UniversalTabs>
### Running tasks in parallel
<UniversalTabs items={["Python", "Typescript", "Go", "Ruby"]} variant="hidden">
<Tabs.Tab title="Python">
Since `aio_run` returns a coroutine, you can spawn multiple tasks in parallel and await them with `asyncio.gather`.
<Snippet src={snippets.python.child.trigger.running_multiple_tasks} />
</Tabs.Tab>
<Tabs.Tab title="Typescript">
Since `run` returns a promise, you can spawn multiple tasks in parallel and await them with `Promise.all`.
<Snippet src={snippets.typescript.simple.run.running_multiple_tasks} />
</Tabs.Tab>
<Tabs.Tab title="Go">
You can run multiple tasks in parallel by calling `Run` in goroutines and using a `sync.WaitGroup` to wait for them to complete.
<Snippet src={snippets.go.simple.main.running_multiple_tasks} />
</Tabs.Tab>
<Tabs.Tab title="Ruby">
In Ruby, multiple tasks can be spawned in parallel using `run_many`.
<Snippet src={snippets.ruby.child.trigger.running_multiple_tasks} />
</Tabs.Tab>
</UniversalTabs>
<Callout type="info">
While you can run multiple tasks in parallel using the `Run` method, this is
not recommended for large numbers of tasks. Instead, use [bulk run
methods](/v1/bulk-run) for large parallel task execution.
</Callout>
## Fire and forget
Fire-and-forget-style triggering enqueues a task without waiting for the result. This is useful for background jobs like sending emails, processing uploads, or kicking off long-running pipelines.
On the other hand, fire-and-forget-style triggering enqueues a task without waiting for the result. This is useful for background jobs like sending emails, processing uploads, or kicking off long-running pipelines where the application does _not_ need to wait for the result to continue along.
<UniversalTabs items={["Python", "Typescript", "Go", "Ruby"]}>
<Tabs.Tab title="Python">
<Snippet src={snippets.python.trigger_methods.workflow.define_a_task} />
Call `run_no_wait` on a `Task` or `Workflow` object to enqueue it fire-and-forget. This returns a `WorkflowRunRef` you can use to access the run ID and result later.
<Snippet src={snippets.python.trigger_methods.workflow.sync} />
@@ -141,10 +73,6 @@ Note that the type of `input` here is a Pydantic model that matches the input sc
Call `run_no_wait` on the `Task` object to enqueue it without waiting for the result. This returns a `WorkflowRunRef`.
<Snippet
src={snippets.typescript.simple.enqueue.enqueuing_a_workflow_fire_and_forget}
/>
</Tabs.Tab>
<Tabs.Tab title="Go">
@@ -162,9 +90,7 @@ Call `run_no_wait` on the `Task` object to enqueue it without waiting for the re
</Tabs.Tab>
</UniversalTabs>
### Subscribing to results later
`run_no_wait` returns a `WorkflowRunRef` with a listener for the task result, letting you subscribe to the result later.
When running a task fire-and-forget-style, you can also always retrieve the result later on. The workflow run ref that's returned from these trigger methods has a result method, which lets you retrieve the result of the triggered task if you need it later.
<UniversalTabs items={["Python", "Typescript", "Go", "Ruby"]} variant="hidden">
<Tabs.Tab title="Python">
@@ -189,10 +115,26 @@ or await `aio_result`:
</Tabs.Tab>
</UniversalTabs>
### Triggering from events
Another method of fire-and-forget triggering is triggering via [pushing events](/v1/events) to Hatchet. If a task is configured to be triggered by an event, then when the event is pushed to Hatchet, a corresponding run will be triggered using the payload of the event as the input to the run.
You can push events to Hatchet directly using the SDKs, or via [webhooks](/v1/webhooks), which are converted into Hatchet events internally on ingestion.
## Crons
Another common way to run tasks is on a cron schedule, which Hatchet [supports natively](/v1/cron-runs). Crons are useful for running tasks that are expected to run at the same time every day, such as data processing pipelines, reconciliation jobs, and so on.
Note that Hatchet supports second-level cron granularity, although in most cases using the minutes as the most granular level is perfectly fine.
## Scheduled runs
Finally, Hatchet also supports [scheduling a run to be triggered at a specific time in the future](/v1/scheduled-runs). This is particularly useful for situations where you want to wait a known about of time before running some task, such as sending a follow up email or a welcome email to a new user, or allowing your customers to choose when they want something to run, such as sending a reminder, for instance.
### Triggering from the dashboard
There are a number of pages in the dashboard that have a `Trigger Run` button. You can provide run parameters such as input, additional metadata, and a scheduled time.
Finally, there are a number of pages in the dashboard that have a `Trigger Run` button. You can provide run parameters such as input, additional metadata, and a scheduled time.
![Create Scheduled Run](../../public/schedule-dash.gif)
<Keywords keywords="trigger, enqueue, fire-and-forget, fire-and-wait, run, fanout" />
<Keywords keywords="trigger, enqueue, fire-and-forget, fire-and-wait, run, event, webhook, cron, schedule" />