EXECUTE TASK¶

Syntax¶

EXECUTE TASK <name>

EXECUTE TASK <name> RETRY LAST

Parameters¶

name

Identifier for the standalone task or root task to run. If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case-sensitive.

RETRY LAST

Re-execute the last failed task of the task graph with name restarting from where the tasks failed.

To re-execute a task the following conditions must be met:

• The last task graph run must be in state FAILED or CANCELED.

• The task graph must not have been modified since it was last run.

• The task graph must have been executed, or retried, in the last 14 days.

To view task history see either the TASK_HISTORY table function or Snowsight task history.

Note

RETRY LAST creates a new graph run which begins execution at the last failed task(s).

Specifically, all FAILED or CANCELED task runs are immediately re-executed, and associated child tasks are scheduled if all of their predecessors execute successfully.

Additionally the new task graph run produced by the retry will have an ATTEMPT NUMBER that is one greater than the previous failed graph run, and share the same GRAPH_RUN_GROUP_ID as the retried, or original task graph run.

Usage notes¶

• Executing a task requires either the OWNERSHIP or OPERATE privilege on the task.

  When the EXECUTE TASK command triggers a task run, Snowflake verifies that the role with the OWNERSHIP privilege on the task also has the USAGE privilege on the warehouse assigned to the task, as well as the global EXECUTE TASK privilege; if not, an error is produced.

  Tasks always run with the privileges of the original owner role, even if a different role with the OPERATE privilege uses EXECUTE TASK to run the task.

• The SQL command can only execute a standalone task or the root task in a task graph. If a child task is input, the command returns a user error.

• Manually executing a standalone or root task establishes a version of the task. The standalone task or entire task graph completes its run with this version. For more information about task versions, see Versioning of task runs.

• A suspended root task is run without resuming the task; there is no need to explicitly resume the root task before you execute this SQL command. However, EXECUTE TASK does not automatically resume child tasks in the task graph. The command skips any child tasks that are suspended.

  To recursively resume all dependent tasks tied to a root task in a task graph, query the SYSTEM$TASK_DEPENDENTS_ENABLE function rather than enabling each task individually (using ALTER TASK … RESUME).

  As a best practice when testing new or modified task graphs, set the root task to run on its intended production schedule but leave it in a suspended state. When you have tested the task graph successfully, resume the root task. Note that you must resume any suspended child tasks in the task graph for testing; otherwise, they are skipped during runs of the task graph.

• If the root task is currently running (i.e. in an EXECUTING state in the TASK_HISTORY output), the EXECUTE TASK command schedules another run of the task to start immediately after the current run is completed.

• If the root task is currently scheduled (i.e. in a SCHEDULED state in the TASK_HISTORY output), the scheduled run is replaced with the requested run as usual, with the current timestamp as the scheduled time. However, if the scheduled time has passed (but the task has not yet transitioned to an EXECUTING state), then the scheduled run occurs as usual. That is, the scheduled run is not replaced with the requested run.

• The ALLOW_OVERLAPPING_EXECUTION parameter set on a root task determines whether overlapping instances of the task graph are allowed. The behavior of requested task runs differs depending on the parameter value:

  ALLOW_OVERLAPPING_EXECUTION = FALSE (default value)

  If no instance of the task graph is currently running, the EXECUTE TASK command schedules another run of the task graph to start immediately. If the root task or any child task in the task graph is currently running (i.e. in an EXECUTING state in the TASK_HISTORY output), the EXECUTE TASK command schedules another run of the task graph to start immediately after the current run of the last task in the task graph has completed. That is, the current instance of the task graph must complete its run before the requested task begins. If the root task is currently scheduled (i.e. in a SCHEDULED state in the TASK_HISTORY output), the scheduled run is replaced with the requested run, with the current timestamp as the scheduled time. However, if the scheduled time has passed (but the task has not yet transitioned to an EXECUTING state), then the scheduled run occurs. That is, the scheduled run is not replaced with the requested run.

  ALLOW_OVERLAPPING_EXECUTION = TRUE

  If no instance of the task graph is currently running, or if only child tasks in the task graph are running in an instance, the EXECUTE TASK command schedules another run of the task graph to start immediately. If the root task is currently running in an instance of the task graph, the EXECUTE TASK command schedules another run of the task graph to start immediately after the current run of the root task has completed. If the root task is currently scheduled (i.e. in a SCHEDULED state in the TASK_HISTORY output) in an instance of the task graph, the scheduled run is replaced with the requested run as usual, with the current timestamp as the scheduled time. However, if the scheduled time has passed (but the task has not yet transitioned to an EXECUTING state), then the scheduled run occurs. That is, the scheduled run is not replaced with the requested run.

• While calls to the EXECUTE TASK command are handled synchronously, task runs are asynchronous operations.

• Task runs triggered by this SQL command use the task version that was current when the command was executed. If a task is modified after the command was executed but before the run begins, the changes are not applied until the next scheduled run.

  If this SQL command is executed multiple times while a run of the task is ongoing, all of the command executions except for the last one are ignored. When the next run begins, the task version that was current when the last execution was made is used.

• If a task fails with an unexpected error, you can receive a notification about the error. For more information on configuring task error notifications refer to Enabling notifications for tasks.

• To view the task information you can either:

  • Open Snowsight and select Monitoring » Task History.

  • Call the COMPLETE_TASK_GRAPHS table function, and examine the results.

Examples¶

Manually trigger a run of a task named mytask:

EXECUTE TASK mytask;