Flows, tasks, and runs

A flow is a workflow definition. A run is one execution of that definition with a particular set of inputs.

On this page

The building blocks Define dependencies through values Local and hosted execution Versions, names, and promotion Next steps

The building blocks

Concept	What it means	Example
Task	A unit of Python work with its own name and retry policy	Read orders, validate records, update a warehouse
Flow	A collection of task calls and their dependencies	A daily revenue pipeline
Graph / DAG	Tasks connected in dependency order, with no cycles	Read → validate → aggregate → write
Node	A configurable building block with input/output ports in the visual builder	HTTP ingestion or a data quality check
Flow version	A registered definition and associated code version	The version returned by a deployment upload
Deployment	A named selection of a flow version for an environment	`daily-revenue-develop`
Run	An execution with inputs, state, timestamps, and task results	Yesterday's revenue calculation
Environment	A workspace's configuration and deployment target	`develop` and a separately created `production`
Organization / workspace	The account boundary for members and resources	Your engineering team's Dagy workspace

Define dependencies through values

Python

from dagy import flow, task

@task
def read_orders():
    return [{"amount": 25}, {"amount": 40}]

@task
def total(orders):
    return sum(order["amount"] for order in orders)

@flow
def revenue():
    return total(read_orders())

A real flow uses a task's returned value as the argument to the next task. See the complete, executable quickstart. While Dagy builds the graph, task calls describe future work. Keep network calls and other side effects inside tasks: the flow body itself executes during graph construction.

Independent tasks can execute concurrently in supported runtimes. A task that needs another task's output waits for it. A failed dependency can cause downstream tasks to be skipped. Retry and cancellation do not reverse data already written to another service.

Local and hosted execution

Use my_flow.run_local() to explicitly execute a graph on your machine, including after you have configured a hosted account. Calling my_flow() directly executes the Python body and returns its value; this does not provide the same graph scheduling and persisted local history.

For hosted execution, package and deploy the code, then submit a run against the returned deployment name. A successful submission means Dagy accepted the run; poll its status to determine the final outcome. Connect to Dagy covers the complete path.

Versions, names, and promotion

Treat the server's returned flow version and deployment name as authoritative. The packaging and upload workflow can assign a version; do not assume a label in a source file is always the final deployed identifier. Reusing a deployment name can update which version it points to.

Namespaces help organize flows, and tags are a string-to-string map for metadata. They are separate from environment selection and do not create an authorization boundary. Environments belong to a workspace; workspace membership and permissions control access.

Promotion selects an existing flow version in another environment. It does not copy secrets or variables, and currently requires checking runtime and dependency-package settings separately. Follow deployment and promotion before promoting a flow.

Next steps

Start with the Python quickstart, then learn about runtime selection and run operations.