ALTER TASK¶
Modifies the properties for an existing task.
- See also:
Syntax¶
ALTER TASK [ IF EXISTS ] <name> RESUME | SUSPEND
ALTER TASK [ IF EXISTS ] <name> REMOVE AFTER <string> [ , <string> , ... ] | ADD AFTER <string> [ , <string> , ... ]
ALTER TASK [ IF EXISTS ] <name> SET
[ WAREHOUSE = <string> ]
[ SCHEDULE = '{ <number> MINUTE | USING CRON <expr> <time_zone> }' ]
[ CONFIG = <configuration_string> ]
[ ALLOW_OVERLAPPING_EXECUTION = TRUE | FALSE ]
[ USER_TASK_TIMEOUT_MS = <num> ]
[ SUSPEND_TASK_AFTER_NUM_FAILURES = <num> ]
[ COMMENT = <string> ]
[ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ]
ALTER TASK [ IF EXISTS ] <name> UNSET
[ WAREHOUSE ]
[ SCHEDULE ]
[ CONFIG ]
[ ALLOW_OVERLAPPING_EXECUTION ]
[ USER_TASK_TIMEOUT_MS ]
[ SUSPEND_TASK_AFTER_NUM_FAILURES ]
[ COMMENT ]
[ <session_parameter> [ , <session_parameter> ... ] ]
[ , ... ]
ALTER TASK [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
ALTER TASK [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ]
ALTER TASK [ IF EXISTS ] <name> SET FINALIZE = <string>
ALTER TASK [ IF EXISTS ] <name> UNSET FINALIZE
ALTER TASK [ IF EXISTS ] <name> MODIFY AS <sql>
ALTER TASK [ IF EXISTS ] <name> MODIFY WHEN <boolean_expr>
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 [ , string , ... ]
Specifies the names of one or more current predecessor tasks for this child task in a DAG of tasks.
When all predecessors for a child task are removed, then the former child task becomes either a standalone task or a root task, depending on whether other tasks identify this former child task as their predecessor. If the former child task becomes a root task, this task is suspended by default and must be resumed manually.
ADD AFTER string [ , string , ... ]
Specifies the names of one or more existing tasks to add as predecessors for this child task in a DAG of tasks. Each child task in a DAG runs when all predecessor tasks finish their runs successfully. For more information, see the description of the
AFTER
parameter in CREATE TASK.Each child task is limited to 100 predecessor tasks.
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.
TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]
Specifies the tag name and the tag string value.
The tag value is always a string, and the maximum number of characters for the tag value is 256.
For details about specifying tags in a statement, refer to Tag quotas for objects and columns.
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.
sql
Specifies the SQL code to execute when the task runs:
Single SQL statement
Call to a stored procedure
Procedural logic using Snowflake Scripting
Note that currently, Snowsight and the Classic Console do not support creating or modifying tasks to use Snowflake Scripting. Instead, use SnowSQL or another command-line client.
Note
Verify the SQL code that you reference in a task executes as expected before you create the task. Tasks are intended to automate SQL code that have already been tested thoroughly.
WHEN boolean_expr
Specifies a Boolean SQL expression. When a task is triggered (based on its
SCHEDULE
orAFTER
setting), it validates the conditions of the expression to determine whether to execute. If the conditions of the expression are not met, then the task skips the current run. Any tasks that identify this task as a predecessor also do not run.Validating the conditions of the WHEN expression does not require a virtual warehouse. The validation is instead processed in the cloud services layer. A nominal charge accrues each time a task evaluates its WHEN condition and does not run. The charges accumulate each time the task is triggered until it runs. At that time, the charge is converted to Snowflake credits and added to the compute resource usage for the task run.
Generally the compute time to validate the condition is insignificant compared to task execution time. As a best practice, align scheduled and actual task runs as closely as possible. Avoid task schedules that are wildly out of synch with actual task runs. For example, if data is inserted into a table with a stream roughly every 24 hours, do not schedule a task that checks for stream data every minute. The charge to validate the WHEN expression with each run is generally insignificant, but the charges are cumulative.
Note that daily consumption of cloud services that falls below the 10% quota of the daily usage of the compute resources accumulates no cloud services charges.
Currently, the following functions are supported for evaluation in the SQL expression:
- SYSTEM$STREAM_HAS_DATA
Indicates whether a specified stream contains change tracking data. Used to skip the current task run if the stream contains no change data.
If the result is
FALSE
, then the task does not run.- SYSTEM$GET_PREDECESSOR_RETURN_VALUE
Retrieves the return value for the predecessor task in a DAG of tasks. Used to make decisions as to whether the task should run based on the returned result.
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.
When altering configuration you cannot update individual key-value pairs. Rather you must supply the entire replacement json string representing the complete configuration.
A standalone task must be suspended before it can be modified.
The root task in a DAG of tasks must be suspended before any task in the DAG is modified, a child task is suspended or resumed, or a child task is added (using ALTER TASK … AFTER).
A DAG 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 DAG, 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, 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.
The compute resources for individual runs of a task are either managed by Snowflake (i.e. the serverless compute model) or a user-specified virtual warehouse. To convert a task that relies on a warehouse to the serverless compute model, unset the
WAREHOUSE
.Note
The serverless compute model is supported as a preview feature.
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.
Regarding metadata:
Attention
Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata Fields in Snowflake.
Regarding the finalizer task:
When you
SET FINALIZE = <root task name>
, a normal task is configured to be a finalizer task associated with the given root task.When you
UNSET FINALIZE
, a finalizer task is changed back to a normal standalone task with no schedule nor predecessor.A finalizer task must never have a schedule or predecessor. As a result,
SET FINALIZE
to a task conflicts withSET SCHEDULE
andADD AFTER
. A task with an existing schedule or predecessor will also fail theSET FINALIZE
query. If the target root task already has a finalizer task, the ALTER will overwrite the old one so the target root task will have a new finalizer task.The root task must be suspended before the finalizer task is modified, set, or unset.
Examples¶
The following example initiates operation of a task:
ALTER TASK mytask RESUME;
The following example converts a task to the serverless compute model and sets xsmall
as the amount of compute resources to provision
for the first serverless runs of the task:
ALTER TASK mytask UNSET WAREHOUSE;
ALTER TASK mytask SET USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL';
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 tasks for the mytask
child task (pred_task1
, pred_task2
) and replace them
with a different predecessor task (pred_task3
):
ALTER TASK mytask REMOVE AFTER pred_task1, pred_task2;
ALTER TASK mytask ADD AFTER pred_task3;
The following example changes the SQL statement associated with a task. The task now queries the CURRENT_VERSION function when it runs:
ALTER TASK mytask MODIFY AS SELECT CURRENT_VERSION();
The following example modifies the WHEN condition associated with a task. When triggered (on a schedule or after the predecessor task runs
successfully), the task now runs only when the mystream
stream contains data:
ALTER TASK mytask MODIFY WHEN SYSTEM$STREAM_HAS_DATA('MYSTREAM');
Update an existing task with new or replacement configuration.
ALTER TASK task_with_config SET
CONFIG=$${"output_directory": "/temp/prod_directory/", "environment": "prod"}$$;
Remove configuration from an existing task.
ALTER TASK task_with_config UNSET CONFIG;