EXECUTE TASK¶

Manually triggers a single run of a task (either a standalone task or the root task in a task graph) independent of the schedule defined for the task.

By default, the command runs asynchronously and returns after scheduling the run. Specify AWAIT to wait for the task or task graph to complete before the command returns.

A successful run of a root task triggers a cascading run of child tasks in the task graph as their precedent task completes, as though the root task had run on its defined schedule.

Additionally, you can manually trigger the re-execution of a previously failed task.

See also:: CREATE TASK , DESCRIBE TASK , ALTER TASK , DROP TASK , SHOW TASKS

Syntax¶

EXECUTE TASK <name>
  [ USING CONFIG = <configuration_string> ]
  [ AWAIT ]

EXECUTE TASK <name> RETRY LAST

EXECUTE TASK <name> RETRY GRAPH RUN GROUP '<graph_run_group_id>'

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.

USING CONFIG = configuration_string

Specifies a configuration string in valid JSON format for this single execution. This parameter creates a new execution with the dynamically specified configuration, but doesn’t modify the task definition.

Snowflake merges the dynamic configuration with the default configuration, which is the CONFIG parameter that you set in the task definition with CREATE or ALTER. For matching fields, Snowflake uses the dynamically specified values. For non-matching fields, Snowflake uses the values from the default configuration. For an example, see Use a dynamic CONFIG.

The configuration string follows the same format as the CONFIG parameter in CREATE TASK or ALTER TASK:

CONFIG = $${"string1": value1 [, "string2": value2, ...] }$$

Example:

CONFIG = $${"learning_rate": 0.2, "environment": "testing"}$$

To wait for a run with this configuration to complete, specify AWAIT after the configuration string. For details, see Synchronous execution with AWAIT.

AWAIT

Runs the task or task graph synchronously and waits for the run to complete. For run behavior, timeouts, and output, see Synchronous execution with AWAIT.

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 last failed graph run’s first attempt must have been executed in the last 14 days.

To view task history, see either the TASK_HISTORY table function or the Tasks page on Snowsight.

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.

RETRY GRAPH RUN GROUP 'graph_run_group_id'

Re-execute starting from the failed tasks of a specific previous graph run, identified by its GRAPH_RUN_GROUP_ID. Use this variant when you want to retry a specific graph run rather than the most recent one. RETRY LAST always targets the latest run.

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

The latest run of the specified graph run group must be complete (it must not have a run still in progress) and must have at least one task in state FAILED or CANCELED.
The specified graph run group must belong to the task identified by name.
The task graph must not have been modified since the targeted run.
The targeted graph run group’s first attempt must have been executed in the last 14 days.

To find a graph run’s GRAPH_RUN_GROUP_ID, query the TASK_HISTORY or COMPLETE_TASK_GRAPHS table function, or use the Tasks page on Snowsight.

Note

Like RETRY LAST, this command creates a new graph run that begins execution at the failed task(s) of the targeted graph run. Specifically, all FAILED or CANCELED task runs in the targeted graph run are immediately re-executed, and associated child tasks are scheduled if all of their predecessors execute successfully.

The new task graph run produced by the retry will have an ATTEMPT_NUMBER that is one greater than the targeted graph run, and shares the same GRAPH_RUN_GROUP_ID as the targeted graph run.

Usage notes¶

General task behavior¶

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.
By default, Snowflake runs tasks by using the system user with the privileges of the task owner role. To run a task as a specific user, configure the task with EXECUTE AS USER. For more information, see Run tasks with user privileges.
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 a task fails with an unexpected error, you can receive a notification about the error. For more information, see Set up alerts and notifications for tasks.
To view the task information you can either:
- In Snowsight, in the navigation menu, select Transformation » Tasks.
- Call the COMPLETE_TASK_GRAPHS table function, and examine the results.

Asynchronous execution¶

By default, EXECUTE TASK schedules a run and returns a status message without waiting for the run to complete. The following notes describe scheduling and configuration for asynchronous execution:

For the USING CONFIG option:
- If the task graph is currently executing and you run this command, Snowflake waits for the current execution to complete before starting a new execution with the dynamic configuration.
- If you run this command multiple times while a task is executing, Snowflake uses the configuration from the most recent command for the next run. Previous configurations are replaced and won’t be executed.
- The dynamic configuration only applies to the single execution triggered by this command. Subsequent scheduled runs use the default CONFIG parameter from the task definition.
If no instance of the task is running, a new run starts immediately.
If another instance is scheduled (that is, if the task shows a SCHEDULED state in the TASK_HISTORY output), the requested run replaces the scheduled run. The requested run starts immediately, using the current timestamp as the scheduled time.
If the task or task graph is currently queueing or executing (that is, if the task shows an EXECUTING state in the TASK_HISTORY output), then the current run continues using the task version that was current when the command was executed. A new run is then scheduled to start, at a time depending on the task type:
- For standalone tasks, a new run is scheduled to start after the current run completes.
- For task graphs, the behavior depends on the OVERLAP_POLICY setting. For more information, see OVERLAP_POLICY in the CREATE TASK documentation.
If the EXECUTE TASK command is executed again before the next scheduled run starts, the requested run replaces the scheduled run.

Synchronous execution with AWAIT¶

Use EXECUTE TASK ... AWAIT to run a task or task graph synchronously. The command waits for the run to complete before returning, so subsequent SQL statements in a script or stored procedure can use the run’s results.

Run behavior¶

For a standalone task, the command waits for that task to complete. For a task graph, the command waits for the entire graph, including any finalizer task.
The command waits through all automatic retries configured with TASK_AUTO_RETRY_ATTEMPTS and returns the outcome of the final attempt.
The requested run must be able to start immediately. When another run is in progress and the task’s OVERLAP_POLICY prevents a new run from starting, the command returns an error without queueing a new run. For more information, see Overlapping task graph runs.
Like asynchronous execution, EXECUTE TASK ... AWAIT replaces a future scheduled run with the requested run.
Manual retries with RETRY LAST or RETRY GRAPH RUN GROUP don’t support AWAIT.

Timeouts and cancellation¶

STATEMENT_TIMEOUT_IN_SECONDS limits how long the command waits. When the statement times out or you cancel the statement, waiting stops, but the task or task graph continues running. The task run is still subject to its own timeout settings, including USER_TASK_TIMEOUT_MS.

Output¶

By default, EXECUTE TASK returns a status message after scheduling the run.

With AWAIT, a successful or skipped run returns one row with the following columns:

Column	Description
`MESSAGE`	A message indicating that the task or task graph completed or was skipped.
`GRAPH_RUN_GROUP_ID`	The identifier for the graph run group started by the command. You can use it to query the TASK_HISTORY, CURRENT_TASK_GRAPHS, or COMPLETE_TASK_GRAPHS table function.
`STATUS`	`SUCCEEDED` or `SKIPPED`.

If the run fails or is canceled, the command returns an error instead of a result row. The error includes the graph run group ID and, when available, error details. You can use the graph run group ID to query task history for details.

Examples¶

The following examples show how to manually trigger a task run, wait for a run to complete, retry a specific previous graph run, and use a dynamic configuration.

Manually trigger a task run¶

Manually trigger a run of a task named mytask:

EXECUTE TASK mytask;

Wait for a task run to complete¶

Run mytask and wait for it to complete:

EXECUTE TASK mytask AWAIT;

A successful run returns output similar to the following:

+----------------------------------------------+--------------------------------------+-----------+
| MESSAGE                                      | GRAPH_RUN_GROUP_ID                   | STATUS    |
|----------------------------------------------+--------------------------------------+-----------|
| Task graph 'MYDB.MYSCHEMA.MYTASK' completed. | 00000000-0000-0000-0000-000000000000 | SUCCEEDED |
+----------------------------------------------+--------------------------------------+-----------+

To retrieve task history for this run, including any automatic retry attempts, use the returned graph run group ID:

SELECT NAME, STATE, ATTEMPT_NUMBER, ERROR_CODE, ERROR_MESSAGE
  FROM TABLE(INFORMATION_SCHEMA.TASK_HISTORY(
    GRAPH_RUN_GROUP_ID => '00000000-0000-0000-0000-000000000000'))
  ORDER BY ATTEMPT_NUMBER, SCHEDULED_TIME;

Retry a specific graph run¶

Retry the failed tasks of a specific previous graph run of mytask, identified by its GRAPH_RUN_GROUP_ID:

EXECUTE TASK mytask RETRY GRAPH RUN GROUP '33af30ab-f960-4ba0-a5c8-d132e5623468';

To find the GRAPH_RUN_GROUP_ID for a previous run, query the TASK_HISTORY or COMPLETE_TASK_GRAPHS table function.

Use a dynamic CONFIG¶

Create a root task named my_root_task with a default configuration:

CREATE OR REPLACE TASK my_root_task
  WAREHOUSE = regress
  SCHEDULE = '10 m'
  CONFIG = $${
    "environment": "production",
    "output_paths": {
      "logs": "/prod/logs",
      "results": "/prod/results"
    }
  }$$
  AS ...;

Now, execute the task and specify a dynamic configuration:

EXECUTE TASK my_root_task
  USING CONFIG=$${
    "output_paths": {
      "results": "/temp/testing"
    }
  }$$;

The following example shows the resulting configuration for this execution:

{
  "environment": "production",
  "output_paths": {
    "logs": "/prod/logs",
    "results": "/temp/testing"
  }
}

The environment field and the output_paths.logs field remain unchanged from the default configuration; only output_paths.results is updated with the dynamic value.