Introduction to tasks¶

Limitations¶

• The maximum compute size for a serverless task is equivalent to an XXLARGE virtual warehouse.

Create a task using the serverless compute model¶

Use CREATE TASK to define the task. Don’t include the WAREHOUSE parameter.

The role that runs the task must have the global EXECUTE MANAGED TASK privilege. For more information, see Task security.

The following example creates a task that runs every hour.

CREATE TASK SCHEDULED_T1
  SCHEDULE='60 MINUTES'
  AS SELECT 1;

from datetime import timedelta
from snowflake.core.task import Cron, Task

tasks = root.databases["TEST_DB"].schemas["TEST_SCHEMA"].tasks

task = tasks.create(
    Task(
        name="SCHEDULED_T1",
        definition="SELECT 1",
        schedule=timedelta(minutes=60),
        ),
    )

Cost and performance: Warehouse sizes¶

To make sure serverless tasks run efficiently, you can set the minimum and maximum warehouse sizes by setting the following parameters:

• SERVERLESS_TASK_MIN_STATEMENT_SIZE: the minimum warehouse size for predictable performance (default: XSMALL).

• SERVERLESS_TASK_MAX_STATEMENT_SIZE: the maximum warehouse size to prevent unexpected costs (default: XXLARGE).

After a task completes, Snowflake reviews the performance and adjusts compute resources for future runs within these limits.

The following example shows a task that runs every 30 seconds, with a minimum warehouse size of SMALL and a maximum warehouse size of LARGE.

CREATE TASK SCHEDULED_T2
  SCHEDULE='30 SECONDS'
  SERVERLESS_TASK_MIN_STATEMENT_SIZE='SMALL'
  SERVERLESS_TASK_MAX_STATEMENT_SIZE='LARGE'
  AS SELECT 1;

from datetime import timedelta
from snowflake.core.task import Cron, Task

tasks = root.databases["TEST_DB"].schemas["TEST_SCHEMA"].tasks

task = tasks.create(
    Task(
        name="SCHEDULED_T2",
        definition="SELECT 1",
        schedule=timedelta(seconds=30),
        serverless_task_min_statement_size="SMALL",
        serverless_task_max_statement_size="LARGE",
        ),
    )

Target completion interval¶

You can set an earlier target for a serverless task to complete. A target completion interval is required for serverless triggered tasks.

When set, Snowflake estimates and scales resources to complete within the target completion interval. When a task is already at its maximum warehouse size and is running too long, the target completion interval is ignored.

In the following example, a task runs every day at midnight, with a target of completing by 2 a.m. The start time and time zone are defined by USING CRON. If the task gets to the largest warehouse size, it may run as long as three hours before finally triggering a timeout.

CREATE TASK SCHEDULED_T3
  SCHEDULE='USING CRON 0 * * * * America/Los_Angeles'
  TARGET_COMPLETION_INTERVAL='120 MINUTE'
  SERVERLESS_TASK_MAX_STATEMENT_SIZE='LARGE'
  USER_TASK_TIMEOUT_MS = 10800000         -- (3 hours)
  SUSPEND_TASK_AFTER_NUM_FAILURES = 3
  AS SELECT 1;

from datetime import timedelta
from snowflake.core.task import Cron, Task

tasks = root.databases["TEST_DB"].schemas["TEST_SCHEMA"].tasks

task = tasks.create(
    Task(
        name="SCHEDULED_T3",
        definition="SELECT 1",
        schedule=Cron("0 * * * *", "America/Los_Angeles"),
        target_completion_interval=timedelta(minutes=120),
        serverless_task_max_statement_size="LARGE",
        user_task_timeout_ms=10800000,  # (3 hours)
        suspend_task_after_num_failures=3,
    ),
)

Choose a warehouse¶

When choosing a warehouse, consider the following:

• Review the best practices in Warehouse considerations.

• Analyze average task run times using different warehouses based on warehouse size and clustering. For more information, see Task duration.

• If the warehouse is shared by multiple processes, consider the impact of the task on other workloads.

Create a task using the user-managed compute model¶

Use CREATE TASK, and include the WAREHOUSE parameter.

The role that runs the task must have the global EXECUTE MANAGED TASK privilege. For more information, see Task security.

The following example creates a task that runs every hour.

CREATE TASK SCHEDULED_T1
  WAREHOUSE='COMPUTE_WH'
  SCHEDULE='60 MINUTES'
  AS SELECT 1;

Creating tasks¶

Creating tasks requires a role with a minimum of the following privileges:

Running tasks¶

After a task is created, the task owner must have the following privileges for the task to run:

In addition, the role must have the permissions required to run the SQL statement run by the task.

Viewing task history¶

To view tasks, you must have one or more of the following privileges:

• The ACCOUNTADMIN role

• The OWNERSHIP privilege on the task

• The global MONITOR EXECUTION privilege

Resuming or suspending tasks¶

In addition to the task owner, a role that has the OPERATE privilege on the task can suspend or resume the task. This role must have the USAGE privilege on the database and schema that contain the task. No other privileges are required.

When a task is resumed, Snowflake verifies that the task owner role has the privileges listed in Running tasks.

Create a custom role to create tasks¶

Snowflake requires different permissions to create serverless and user-managed tasks.

For example, to create user-managed tasks, create a custom role named warehouse_task_creation and grant that role the CREATE TASK and USAGE privileges on the warehouse that the role can create tasks in.

USE SYSADMIN;

CREATE ROLE warehouse_task_creation
  COMMENT = 'This role can create user-managed tasks.';

from snowflake.core.role import Role

root.session.use_role("SYSADMIN")

my_role = Role(
    name="warehouse_task_creation",
    comment="This role can create user-managed tasks."
)
root.roles.create(my_role)

USE ACCOUNTADMIN;

GRANT CREATE TASK
  ON SCHEMA schema1
  TO ROLE warehouse_task_creation;

from snowflake.core.role import Securable

root.session.use_role("ACCOUNTADMIN")

root.roles['warehouse_task_creation'].grant_privileges(
    privileges=["CREATE TASK"], securable_type="schema", securable=Securable(name='schema1')
)

GRANT USAGE
  ON WAREHOUSE warehouse1
  TO ROLE warehouse_task_creation;

from snowflake.core.role import Securable

root.roles['warehouse_task_creation'].grant_privileges(
    privileges=["USAGE"], securable_type="warehouse", securable=Securable(name='warehouse1')
)

As an example of a role that can create serverless tasks; create a custom role named serverless_task_creation and grant the role the CREATE TASK privilege and the account level EXECUTE MANAGED TASK privilege.

USE SYSADMIN;

CREATE ROLE serverless_task_creation
  COMMENT = 'This role can create serverless tasks.';

from snowflake.core.role import Role

root.session.use_role("SYSADMIN")

my_role = Role(
    name="serverless_task_creation",
    comment="This role can create serverless tasks."
)
root.roles.create(my_role)

USE ACCOUNTADMIN;

GRANT CREATE TASK
  ON SCHEMA schema1
  TO ROLE serverless_task_creation;

from snowflake.core.role import Securable

root.session.use_role("ACCOUNTADMIN")

root.roles['serverless_task_creation'].grant_privileges(
    privileges=["CREATE TASK"], securable_type="schema", securable=Securable(name='schema1')
)

GRANT EXECUTE MANAGED TASK ON ACCOUNT
  TO ROLE serverless_task_creation;

root.roles['serverless_task_creation'].grant_privileges(
    privileges=["EXECUTE MANAGED TASK"], securable_type="account"
)

Create a custom role to administer tasks¶

Create a custom role, grant it the EXECUTE TASK privilege, and then grant this custom role to any task owner role to allow altering their own tasks. To remove the ability for the task owner role to run the task, revoke this custom role from the task owner role.

For example, create a custom role name taskadmin and grant that role the EXECUTE TASK privilege. Assign the taskadmin role to a task owner role named myrole:

USE ROLE securityadmin;

CREATE ROLE taskadmin;

from snowflake.core.role import Role

root.session.use_role("securityadmin")

root.roles.create(Role(name="taskadmin"))

Set the active role to ACCOUNTADMIN before granting the account-level privileges to the new role

USE ROLE accountadmin;

GRANT EXECUTE TASK, EXECUTE MANAGED TASK ON ACCOUNT TO ROLE taskadmin;

root.session.use_role("accountadmin")

root.roles['taskadmin'].grant_privileges(
    privileges=["EXECUTE TASK", "EXECUTE MANAGED TASK"], securable_type="account"
)

Set the active role to SECURITYADMIN to show that this role can grant a role to another role

USE ROLE securityadmin;

GRANT ROLE taskadmin TO ROLE myrole;

from snowflake.core.role import Securable

root.session.use_role("securityadmin")

root.roles['myrole'].grant_role(role_type="ROLE", role=Securable(name='taskadmin'))

For more information about how to create custom roles and role hierarchies, see Configuring access control.

Drop a task owner role¶

When you delete the owner role of a task, the task transfers ownership to the role that dropped the owner role. When a task transfers ownership, it is automatically paused and new task runs aren’t scheduled until the new owner resumes the task.

If you drop the role while the task is running, the task run completes processing under the dropped role.

Share tasks by using a service user and role¶

For production environments, we recommend that you create a separate service user to represent your team or business process. In contrast to running as an existing service or person user, this best practice helps make the workflow more secure:

• When a task runs as a dedicated service user, it gains access only to the intended privileges. If instead, a user impersonates a different user, they gain access to all privileges associated with the other user, which might include unintended privileges, including user privileges granted after creating and resuming the task.

• A task running as a user might be interrupted if the person leaves the department or organization.

Examples: Set up the service user and team role¶

1. Using the admin role, set up a service user to be used for the task.

   The following example creates a service user named task_user:

   USE ROLE ACCOUNTADMIN;
   CREATE USER task_user;
   

   Copy

2. Create a task role, and then grant it to the service user:

   CREATE ROLE task_role;
   GRANT ROLE task_role to USER task_user;
   

   Copy

3. Allow the task role to run queries on behalf of the team user role:

   GRANT IMPERSONATE ON USER task_user TO ROLE task_role;
   

   Copy

4. Grant appropriate privileges to the task role.

   USE ROLE ACCOUNTADMIN;
   
   -- Grant the team role the privileges to create tasks in a specific schema
   GRANT CREATE TASK
     ON SCHEMA schema1
     TO ROLE task_role;
   
   -- Grant the team role the privileges to use a specific warehouse
   GRANT USAGE
     ON WAREHOUSE warehouse1
     TO ROLE task_role;
   
   -- Grant the team role the privileges to run tasks on a serverless compute model
   GRANT EXECUTE MANAGED TASK ON ACCOUNT TO ROLE task_role;
   

   Copy

Run a task on behalf of a service user¶

After the team role has ownership of the task, team members can modify the task, and run it on behalf of the service user.

Example:

USE ROLE task_owner;

CREATE TASK team_task
  SCHEDULE='12 HOURS'
  EXECUTE AS USER task_user
  AS SELECT 1;

In the previous example, the resulting logs would show that task_user modified the task.

(For testing only) Allow a user to impersonate another user directly¶

When you test or prototype changes, you, as an administrator, can allow users to directly impersonate another user. This scenario, while supported, isn’t recommended in a production environment.

1. Set up a role for impersonation:

   USE ROLE ACCOUNTADMIN;
   CREATE ROLE janes_role;
   GRANT ROLE janes_role to USER jane;
   GRANT IMPERSONATE ON USER jane TO ROLE janes_role;
   

   Copy

2. Create a task by using the new role:

   USE ROLE janes_role;
   
   CREATE TASK janes_task
     SCHEDULE='60 M' AS SELECT 1;
   

   Copy

3. Grant the role to another user.

   In the following example, the user Jane grants access to the user Billy:

   --Logged in as Jane or account admin
   GRANT ROLE janes_role to USER billy;
   

   Copy

4. The other user modifies the task.

   In the following example, the user Billy modifies the task:

   -- Logged in as billy
   USE ROLE janes_role;
   
   ALTER TASK janes_task
     SET EXECUTE AS USER jane;
   

   Copy

5. Review the logs.

   The SHOW GRANTS TO ROLE command would show that Jane granted the role to Billy. The QUERY_HISTORY view would then show that Billy modified the task. Future task runs would still appear as run by Jane.

   USE ROLE ACCOUNTADMIN;
   
   SHOW GRANTS TO ROLE janes_role;
   
   QUERY_HISTORY()
     WHERE QUERY_TEXT ILIKE '%janes_task%';
   

   Copy