EXECUTE TASK¶

Syntax¶

EXECUTE TASK <name>

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.

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 DAG. 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 DAG completes its run with this version. For more information about task versions, see Versioning of 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 DAG. The command skips any child tasks that are suspended.

  To recursively resume all dependent tasks tied to a root task in a DAG, 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 DAGs, set the root task to run on its intended production schedule but leave it in a suspended state. When you have tested the DAG successfully, resume the root task. Note that you must resume any suspended child tasks in the DAG for testing; otherwise, they are skipped during runs of the DAG.

• 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 DAG 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 DAG is currently running, the EXECUTE TASK command schedules another run of the DAG to start immediately. If the root task or any child task in the DAG is currently running (i.e. in an EXECUTING state in the TASK_HISTORY output), the EXECUTE TASK command schedules another run of the DAG to start immediately after the current run of the last task in the DAG has completed. That is, the current instance of the task DAG 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 DAG is currently running, or if only child tasks in the DAG are running in an instance, the EXECUTE TASK command schedules another run of the DAG to start immediately. If the root task is currently running in an instance of the DAG, the EXECUTE TASK command schedules another run of the task DAG 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 DAG, 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 Error Notifications for Tasks.

Examples¶

Manually trigger a run of a task named mytask:

EXECUTE TASK mytask;