def get_output(workflow_id: str,
*,
name: Optional[str] = None) -> ray.ObjectRef:
"""Get the output of a running workflow.
Args:
workflow_id: The workflow to get the output of.
name: If set, fetch the specific step instead of the output of the
workflow.
Examples:
>>> from ray import workflow
>>> start_trip = ... # doctest: +SKIP
>>> trip = start_trip.options(name="trip").step() # doctest: +SKIP
>>> res1 = trip.run_async(workflow_id="trip1") # doctest: +SKIP
>>> # you could "get_output()" in another machine
>>> res2 = workflow.get_output("trip1") # doctest: +SKIP
>>> assert ray.get(res1) == ray.get(res2) # doctest: +SKIP
>>> step_output = workflow.get_output("trip1", "trip") # doctest: +SKIP
>>> assert ray.get(step_output) == ray.get(res1) # doctest: +SKIP
Returns:
An object reference that can be used to retrieve the workflow result.
"""
ensure_ray_initialized()
return execution.get_output(workflow_id, name)
def resume_all(include_failed: bool = False) -> Dict[str, ray.ObjectRef]:
"""Resume all resumable workflow jobs.
This can be used after cluster restart to resume all tasks.
Args:
with_failed: Whether to resume FAILED workflows.
Examples:
>>> workflow_step = failed_job.step()
>>> output = workflow_step.run_async(workflow_id="failed_job")
>>> try:
>>> ray.get(output)
>>> except Exception:
>>> print("JobFailed")
>>> jobs = workflow.list_all()
>>> assert jobs == [("failed_job", workflow.FAILED)]
>>> assert workflow.resume_all(
>>> include_failed=True).get("failed_job") is not None
Returns:
A list of (workflow_id, returned_obj_ref) resumed.
"""
ensure_ray_initialized()
return execution.resume_all(include_failed)
def get_actor(actor_id: str) -> "VirtualActor":
"""Get an virtual actor.
Args:
actor_id: The ID of the actor.
Returns:
A virtual actor.
"""
ensure_ray_initialized()
return virtual_actor_class.get_actor(actor_id, storage_base.get_global_storage())
def list_all(
status_filter: Optional[
Union[Union[WorkflowStatus, str], Set[Union[WorkflowStatus, str]]]
] = None
) -> List[Tuple[str, WorkflowStatus]]:
"""List all workflows matching a given status filter.
Args:
status: If given, only returns workflow with that status. This can
be a single status or set of statuses. The string form of the
status is also acceptable, i.e.,
"RUNNING"/"FAILED"/"SUCCESSFUL"/"CANCELED"/"RESUMABLE".
Examples:
>>> from ray import workflow
>>> long_running_job = ... # doctest: +SKIP
>>> workflow_step = long_running_job.step() # doctest: +SKIP
>>> wf = workflow_step.run_async( # doctest: +SKIP
... workflow_id="long_running_job")
>>> jobs = workflow.list_all() # doctest: +SKIP
>>> assert jobs == [ ("long_running_job", workflow.RUNNING) ] # doctest: +SKIP
>>> ray.get(wf) # doctest: +SKIP
>>> jobs = workflow.list_all({workflow.RUNNING}) # doctest: +SKIP
>>> assert jobs == [] # doctest: +SKIP
>>> jobs = workflow.list_all(workflow.SUCCESSFUL) # doctest: +SKIP
>>> assert jobs == [ # doctest: +SKIP
... ("long_running_job", workflow.SUCCESSFUL)]
Returns:
A list of tuple with workflow id and workflow status
"""
ensure_ray_initialized()
if isinstance(status_filter, str):
status_filter = set({WorkflowStatus(status_filter)})
elif isinstance(status_filter, WorkflowStatus):
status_filter = set({status_filter})
elif isinstance(status_filter, set):
if all(isinstance(s, str) for s in status_filter):
status_filter = {WorkflowStatus(s) for s in status_filter}
elif not all(isinstance(s, WorkflowStatus) for s in status_filter):
raise TypeError(
"status_filter contains element which is not"
" a type of `WorkflowStatus or str`."
f" {status_filter}"
)
elif status_filter is None:
status_filter = set(WorkflowStatus.__members__.keys())
else:
raise TypeError(
"status_filter must be WorkflowStatus or a set of WorkflowStatus."
)
return execution.list_all(status_filter)
def get_metadata(workflow_id: str,
name: Optional[str] = None) -> Dict[str, Any]:
"""Get the metadata of the workflow.
This will return a dict of metadata of either the workflow (
if only workflow_id is given) or a specific workflow step (if
both workflow_id and step name are given). Exception will be
raised if the given workflow id or step name does not exist.
If only workflow id is given, this will return metadata on
workflow level, which includes running status, workflow-level
user metadata and workflow-level running stats (e.g. the
start time and end time of the workflow).
If both workflow id and step name are given, this will return
metadata on workflow step level, which includes step inputs,
step-level user metadata and step-level running stats (e.g.
the start time and end time of the step).
Args:
workflow_id: The workflow to get the metadata of.
name: If set, fetch the metadata of the specific step instead of
the metadata of the workflow.
Examples:
>>> from ray import workflow
>>> trip = ... # doctest: +SKIP
>>> workflow_step = trip.options( # doctest: +SKIP
... name="trip", metadata={"k1": "v1"}).step()
>>> workflow_step.run( # doctest: +SKIP
... workflow_id="trip1", metadata={"k2": "v2"})
>>> workflow_metadata = workflow.get_metadata("trip1") # doctest: +SKIP
>>> assert workflow_metadata["status"] == "SUCCESSFUL" # doctest: +SKIP
>>> assert workflow_metadata["user_metadata"] == {"k2": "v2"} # doctest: +SKIP
>>> assert "start_time" in workflow_metadata["stats"] # doctest: +SKIP
>>> assert "end_time" in workflow_metadata["stats"] # doctest: +SKIP
>>> step_metadata = workflow.get_metadata("trip1", "trip") # doctest: +SKIP
>>> assert step_metadata["step_type"] == "FUNCTION" # doctest: +SKIP
>>> assert step_metadata["user_metadata"] == {"k1": "v1"} # doctest: +SKIP
>>> assert "start_time" in step_metadata["stats"] # doctest: +SKIP
>>> assert "end_time" in step_metadata["stats"] # doctest: +SKIP
Returns:
A dictionary containing the metadata of the workflow.
Raises:
ValueError: if given workflow or workflow step does not exist.
"""
ensure_ray_initialized()
return execution.get_metadata(workflow_id, name)
def get_status(workflow_id: str) -> WorkflowStatus:
"""Get the status for a given workflow.
Args:
workflow_id: The workflow to query.
Examples:
>>> workflow_step = trip.step()
>>> output = workflow_step.run(workflow_id="trip")
>>> assert workflow.SUCCESSFUL == workflow.get_status("trip")
Returns:
The status of that workflow
"""
ensure_ray_initialized()
if not isinstance(workflow_id, str):
raise TypeError("workflow_id has to be a string type.")
return execution.get_status(workflow_id)
def cancel(workflow_id: str) -> None:
"""Cancel a workflow.
Args:
workflow_id: The workflow to cancel.
Examples:
>>> workflow_step = some_job.step()
>>> output = workflow_step.run_async(workflow_id="some_job")
>>> workflow.cancel(workflow_id="some_job")
>>> assert [("some_job", workflow.CANCELED)] == workflow.list_all()
Returns:
None
"""
ensure_ray_initialized()
if not isinstance(workflow_id, str):
raise TypeError("workflow_id has to be a string type.")
return execution.cancel(workflow_id)
def cancel(workflow_id: str) -> None:
"""Cancel a workflow. Workflow checkpoints will still be saved in storage. To
clean up saved checkpoints, see `workflow.delete()`.
Args:
workflow_id: The workflow to cancel.
Examples:
>>> workflow_step = some_job.step()
>>> output = workflow_step.run_async(workflow_id="some_job")
>>> workflow.cancel(workflow_id="some_job")
>>> assert [("some_job", workflow.CANCELED)] == workflow.list_all()
Returns:
None
"""
ensure_ray_initialized()
if not isinstance(workflow_id, str):
raise TypeError("workflow_id has to be a string type.")
return execution.cancel(workflow_id)
def resume(workflow_id: str) -> ray.ObjectRef:
"""Resume a workflow.
Resume a workflow and retrieve its output. If the workflow was incomplete,
it will be re-executed from its checkpointed outputs. If the workflow was
complete, returns the result immediately.
Examples:
>>> trip = start_trip.step()
>>> res1 = trip.run_async(workflow_id="trip1")
>>> res2 = workflow.resume("trip1")
>>> assert ray.get(res1) == ray.get(res2)
Args:
workflow_id: The id of the workflow to resume.
Returns:
An object reference that can be used to retrieve the workflow result.
"""
ensure_ray_initialized()
return execution.resume(workflow_id)
def prepare_inputs():
ensure_ray_initialized()
return serialization_context.make_workflow_inputs(flattened_args)
