Categories:

Table, View, & Sequence DDL

ALTER TASK

Modifies the properties, columns, or constraints for an existing task.

See also:

CREATE TASK , DROP TASK , SHOW TASKS

In this Topic:

Syntax

ALTER TASK [ IF EXISTS ] <name> RESUME | SUSPEND

ALTER TASK [ IF EXISTS ] <name> REMOVE AFTER | ADD AFTER

ALTER TASK [ IF EXISTS ] <name> SET { [ WAREHOUSE = <string> ] [ SCHEDULE = '{ <number> MINUTE | USING CRON <expr> <time_zone> }' ] }

ALTER TASK [ IF EXISTS ] <name> SET { [ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ] }

ALTER TASK [ IF EXISTS ] <name> UNSET { <property_name> | <session_parameter> } [ , ... ]

Parameters

name

Identifier for the task to alter. 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.

RESUME | SUSPEND

Specifies the action to perform on the task:

  • RESUME brings a suspended task to a usable ‘Started’ state. Note that accounts are currently limited to a maximum of 10000 resumed (i.e. in a ‘Started’ state) tasks.

  • SUSPEND puts the task into a ‘Suspended’ state.

If the task schedule is set to an interval (i.e. number MINUTE), then to avoid ambiguity, the base interval time for the schedule is reset to the current time when the task is resumed.

The base interval time starts the interval counter from the current clock time. For example, if an INTERVAL value of 10 is set and the task is resumed at 9:03 AM, then the task runs at 9:13 AM, 9:23 AM, and so on. Note that we make a best effort to ensure absolute precision, but only guarantee that tasks do not execute before their set interval occurs (e.g., in the current example, the task could first run at 9:14 AM, but will definitely not run at 9:12 AM).

REMOVE AFTER string

Specifies the name of the current predecessor task for this child task. Use this parameter to remove the current predecessor task from the specified task before adding a new predecessor task using ALTER TASK … ADD AFTER. The child task is suspended automatically.

In a simple tree of tasks, a child task is triggered when the predecessor task runs and finishes successfully. For more information, see the description of the AFTER parameter in CREATE TASK.

ADD AFTER string

Specifies the name of a new predecessor task for this child task. Use this parameter to add a predecessor task to the specified task after removing the current predecessor task using ALTER TASK … REMOVE AFTER.

SET ...

Specifies either or both of the following:

  • One (or more) properties to set for the task (separated by blank spaces, commas, or new lines). For more details about the properties you can set, see CREATE TASK.

  • A comma-separated list of session parameters to set for the session when the task runs. A task supports all session parameters. For the complete list, see Parameters.

UNSET ...

Specifies one (or more) properties and/or session parameters to unset for the task, which resets them to the defaults.

You can reset multiple properties/parameters with a single ALTER statement; however, each property/parameter must be separated by a comma. When resetting a property/parameter, specify only the name; specifying a value for the property/parameter will return an error.

Usage Notes

  • Resuming or suspending a task (using ALTER TASK … RESUME or ALTER TASK … SUSPEND, respectively) requires either the OWNERSHIP or OPERATE privilege on the task.

    When a task is resumed, 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.

    Only account administrators (users with the ACCOUNTADMIN role) can grant the EXECUTE TASK privilege to a role. For ease of use, we recommend creating a custom role (e.g. TASKADMIN) and assigning the EXECUTE TASK privilege to this role. Any role that can grant privileges (e.g. SECURITYADMIN or any role with the MANAGE GRANTS privilege) can then grant this custom role to any task owner role to allow altering their own tasks. For instructions for creating custom roles and role hierarchies, see Configuring Access Control.

  • Only the task owner (i.e. the role with the OWNERSHIP privilege on the task) can set or unset properties on a task.

  • A simple tree of tasks is limited to a maximum of 1000 tasks total (including the root task) in either a resumed or suspended state.

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

  • By default, a DML statement executed without explicitly starting a transaction is automatically committed on success or rolled back on failure at the end of the statement. This behavior is called autocommit and is controlled with the AUTOCOMMIT parameter. This parameter must be set to TRUE. If the AUTOCOMMIT parameter is set to FALSE at the account level, then set the parameter to TRUE for the individual task (using ALTER TASK … SET AUTOCOMMIT = TRUE).

  • When a task is suspended, or when the schedule or warehouse is modified, any current run of the task (i.e. a run with an EXECUTING state in the TASK_HISTORY output) is completed. To abort the run of the specified task, execute the SYSTEM$USER_TASK_CANCEL_ONGOING_EXECUTIONS function.

Examples

The following example initiates operation of a task:

ALTER TASK mytask RESUME;

The following example sets the TIMEZONE and CLIENT_TIMESTAMP_TYPE_MAPPING session parameters for the session in which the task runs:

ALTER TASK mytask SET TIMEZONE = 'America/Los_Angeles', CLIENT_TIMESTAMP_TYPE_MAPPING = TIMESTAMP_LTZ;

The following example sets a different schedule for a task:

ALTER TASK mytask SET SCHEDULE = 'USING CRON */3 * * * * UTC';

The following example removes the current predecessor task for the mytask child task (pred_task1) and replace it with a different predecessor task (pred_task2):

ALTER TASK mytask REMOVE AFTER pred_task1;

ALTER TASK mytask ADD AFTER pred_task2;