<@ULVA73B9P> does returning a `PrefectFutureList` ...
# ask-marvin
k
@Marvin does returning a
PrefectFutureList
from a flow (called as a local subflow) result in the list being resolved into the mapped task results? Is there docs about this?
m
thought for 153.5 seconds
Yes — but not into the raw mapped results. If a flow returns a
PrefectFutureList
, Prefect resolves the contained futures when the flow finishes, and the caller receives their states, not the task result values themselves. So for a local subflow call:
Copy code
python
@flow
def child():
    return my_task.map([1, 2, 3])

@flow
def parent():
    x = child()
    print(type(x))
    return x
the returned value is effectively: - resolved from
PrefectFutureList[PrefectFuture]
- into a plain
list[State]
not
list[result]
In other words: the futures are resolved, but to
State
objects, not to the mapped task outputs.
There is code in Prefect 3.x that explicitly does this: - flow completion calls
resolve_futures_to_states(...)
- and if the result is a
PrefectFutureList
, it is downcast to a normal
list
so you don’t end up with a
PrefectFutureList
containing non-futures There’s also a test covering this behavior. Docs The most relevant docs I found are in the flows concepts page: - Flows concept docs Relevant points there: - nested/local subflows resolve passed task futures into data - when a flow returns futures/states, Prefect determines the final state by resolving futures to states That docs page hints at the behavior, but it does not seem to clearly spell out the exact
PrefectFutureList -> list[State]
return-type behavior. For that, the source/tests are more definitive. Practical takeaway If you want actual mapped values from the subflow, resolve them inside the subflow before returning, e.g. return concrete data instead of the future list. Example:
Copy code
python
@task
def add_one(x):
    return x + 1

@flow
def child():
    futures = add_one.map([1, 2, 3])
    return [f.result() for f in futures]

@flow
def parent():
    return child()
Then
parent()
gets
[2, 3, 4]
, not a list of states. If you want, I can also show a tiny reproducible example demonstrating the exact returned types for: - top-level flow - local subflow -
return_state=True
cases