tasks

Creates, updates, deletes, gets or lists a tasks resource.

Overview

Name	tasks
Type	Resource
Id	snowflake.pipelines.tasks

Fields

The following fields are returned by SELECT queries:

get

successful

Name	Datatype	Description
id	string	An ID for the current task.
name	string	String that specifies the identifier (i.e. name) for the task. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
database_name	string	The name of the parent database for the task.
schema_name	string	The name of the parent schema for the task.
allow_overlapping_execution	boolean	Specifies whether to allow multiple instances of the DAG to run concurrently.
comment	string	Specifies a comment for the task.
condition	string	Specifies a Boolean SQL expression condition; multiple conditions joined with AND/OR are supported
config	object	Task Config
created_on	string (date-time)	The time the task was created on.
definition	string	The SQL definition for the task. Any one of single SQL statement, call to stored procedure, or procedural logic using Snowflake scripting.
error_integration	string	Specifies the name of the notification integration used to communicate with Amazon SNS, MS Azure Event Grid, or Google Pub/Sub.
finalize	string	Specifies the name of the root task that the finalizer task is associated with.
last_committed_on	string (date-time)	The time the task was last committed on.
last_suspended_on	string (date-time)	The time the task was last suspended on.
owner	string	The role that owns the task.
owner_role_type	string	The role type of the task owner.
predecessors	array	Specifies one or more predecessor tasks for the current task
schedule	object	Specifies the schedule for periodically running the task.
serverless_task_max_statement_size	string	Specifies the maximum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE. This parameter only applies to serverless tasks.
serverless_task_min_statement_size	string	Specifies the minimum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE. This parameter only applies to serverless tasks.
session_parameters	object	Session Parameters for the task at runtime.
state	string	The state of the task. Must be one of started or suspended. (started, suspended)
suspend_task_after_num_failures	integer	Specifies the number of consecutive failed task runs after which the current task is suspended automatically.
target_completion_interval	object	Specifies the desired task completion time. This parameter only applies to serverless tasks.
task_auto_retry_attempts	integer	Root task settable only. Specifies the number of automatic task graph retry attempts. Valid range is 0 to 30. When not specified, no retry would happen.
task_relations	string	Displays the relationship between the root task and its corresponding finalizer tasks.
user_task_managed_initial_warehouse_size	string	Specifies the size of the compute resources to provision for the first run of the task. This parameter only applies to serverless tasks.
user_task_timeout_ms	integer	Specifies the time limit on a single run of the task before it times out (in milliseconds).
warehouse	string	Specifies the virtual warehouse that provides compute resources for task runs. Omit this parameter to use serverless compute resources for runs of this task. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)

list

A Snowflake task, used to execute SQL code.

Name	Datatype	Description
id	string	An ID for the current task.
name	string	String that specifies the identifier (i.e. name) for the task. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
database_name	string	The name of the parent database for the task.
schema_name	string	The name of the parent schema for the task.
allow_overlapping_execution	boolean	Specifies whether to allow multiple instances of the DAG to run concurrently.
comment	string	Specifies a comment for the task.
condition	string	Specifies a Boolean SQL expression condition; multiple conditions joined with AND/OR are supported
config	object	Task Config
created_on	string (date-time)	The time the task was created on.
definition	string	The SQL definition for the task. Any one of single SQL statement, call to stored procedure, or procedural logic using Snowflake scripting.
error_integration	string	Specifies the name of the notification integration used to communicate with Amazon SNS, MS Azure Event Grid, or Google Pub/Sub.
finalize	string	Specifies the name of the root task that the finalizer task is associated with.
last_committed_on	string (date-time)	The time the task was last committed on.
last_suspended_on	string (date-time)	The time the task was last suspended on.
owner	string	The role that owns the task.
owner_role_type	string	The role type of the task owner.
predecessors	array	Specifies one or more predecessor tasks for the current task
schedule	object	Specifies the schedule for periodically running the task.
serverless_task_max_statement_size	string	Specifies the maximum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE. This parameter only applies to serverless tasks.
serverless_task_min_statement_size	string	Specifies the minimum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE. This parameter only applies to serverless tasks.
session_parameters	object	Session Parameters for the task at runtime.
state	string	The state of the task. Must be one of started or suspended. (started, suspended)
suspend_task_after_num_failures	integer	Specifies the number of consecutive failed task runs after which the current task is suspended automatically.
target_completion_interval	object	Specifies the desired task completion time. This parameter only applies to serverless tasks.
task_auto_retry_attempts	integer	Root task settable only. Specifies the number of automatic task graph retry attempts. Valid range is 0 to 30. When not specified, no retry would happen.
task_relations	string	Displays the relationship between the root task and its corresponding finalizer tasks.
user_task_managed_initial_warehouse_size	string	Specifies the size of the compute resources to provision for the first run of the task. This parameter only applies to serverless tasks.
user_task_timeout_ms	integer	Specifies the time limit on a single run of the task before it times out (in milliseconds).
warehouse	string	Specifies the virtual warehouse that provides compute resources for task runs. Omit this parameter to use serverless compute resources for runs of this task. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	database_name, schema_name, name, endpoint		Fetch a task using the describe command output.
list	select	database_name, schema_name, endpoint	rootOnly, like, startsWith, showLimit, fromName	Lists tasks under the database and schema, with show options as query parameters.
create	insert	database_name, schema_name, endpoint, name, definition	createMode	Create a task, with standard create modifiers as query parameters. See the Task component definition for what is required to be provided in the request body.
create_or_alter	replace	database_name, schema_name, task_name, endpoint, name, definition		Create a (or alter an existing) task. Even if the operation is just an alter, the full property set must be provided.
delete	delete	database_name, schema_name, name, endpoint	ifExists	Delete a task with the task name. If ifExists is used, the operation will succeed even if the object does not exist. Otherwise, there will be a failure if the drop is unsuccessful.
execute	exec	database_name, schema_name, name, endpoint	asyncExec, retryLast	Execute a task -- this is equivalent to EXECUTE IMMEDIATE.
resume	exec	database_name, schema_name, name, endpoint		Resumes a suspended task object. This is equivalento an ALTER TASK ... RESUME.
suspend	exec	database_name, schema_name, name, endpoint		Suspends a running task. This is equivalent to an ALTER TASK ... SUSPEND.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
database_name	string	Identifier (i.e. name) for the database to which the resource belongs. You can use the /api/v2/databases GET request to get a list of available databases.
endpoint	string	Organization and account identifier (orgname-accountname) (default: orgname-accountname)
name	string	Identifier (i.e. name) for the resource.
schema_name	string	Identifier (i.e. name) for the schema to which the resource belongs. You can use the /api/v2/databases/{database}/schemas GET request to get a list of available schemas for the specified database.
task_name	string	Identifier (i.e. name) for the resource.
asyncExec	boolean	Asynchronous execution enable/disable. Default is disable.
createMode	string	Parameter allowing support for different modes of resource creation. Possible values include: - errorIfExists: Throws an error if you try to create a resource that already exists. - orReplace: Automatically replaces the existing resource with the current one. - ifNotExists: Creates a new resource when an alter is requested for a non-existent resource.
fromName	string	Parameter to enable fetching rows only following the first row whose object name matches the specified string. Case-sensitive and does not have to be the full name.
ifExists	boolean	Parameter that specifies how to handle the request for a resource that does not exist: - true: The endpoint does not throw an error if the resource does not exist. It returns a 200 success response, but does not take any action on the resource. - false: The endpoint throws an error if the resource doesn't exist.
like	string	Parameter to filter the command output by resource name. Uses case-insensitive pattern matching, with support for SQL wildcard characters.
retryLast	boolean	Retry the last failed run of the DAG.
rootOnly	boolean	Parameter to filter the command output to return only root resources (resources with no predecessors).
showLimit	integer	Parameter to limit the maximum number of rows returned by a command.
startsWith	string	Parameter to filter the command output based on the string of characters that appear at the beginning of the object name. Uses case-sensitive pattern matching.

SELECT examples

get

Fetch a task using the describe command output.

SELECT
id,
name,
database_name,
schema_name,
allow_overlapping_execution,
comment,
condition,
config,
created_on,
definition,
error_integration,
finalize,
last_committed_on,
last_suspended_on,
owner,
owner_role_type,
predecessors,
schedule,
serverless_task_max_statement_size,
serverless_task_min_statement_size,
session_parameters,
state,
suspend_task_after_num_failures,
target_completion_interval,
task_auto_retry_attempts,
task_relations,
user_task_managed_initial_warehouse_size,
user_task_timeout_ms,
warehouse
FROM snowflake.pipelines.tasks
WHERE database_name = '{{ database_name }}' -- required
AND schema_name = '{{ schema_name }}' -- required
AND name = '{{ name }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

list

Lists tasks under the database and schema, with show options as query parameters.

SELECT
id,
name,
database_name,
schema_name,
allow_overlapping_execution,
comment,
condition,
config,
created_on,
definition,
error_integration,
finalize,
last_committed_on,
last_suspended_on,
owner,
owner_role_type,
predecessors,
schedule,
serverless_task_max_statement_size,
serverless_task_min_statement_size,
session_parameters,
state,
suspend_task_after_num_failures,
target_completion_interval,
task_auto_retry_attempts,
task_relations,
user_task_managed_initial_warehouse_size,
user_task_timeout_ms,
warehouse
FROM snowflake.pipelines.tasks
WHERE database_name = '{{ database_name }}' -- required
AND schema_name = '{{ schema_name }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND rootOnly = '{{ rootOnly }}'
AND "like" = '{{ like }}'
AND startsWith = '{{ startsWith }}'
AND showLimit = '{{ showLimit }}'
AND fromName = '{{ fromName }}'
;

INSERT examples

create

Create a task, with standard create modifiers as query parameters. See the Task component definition for what is required to be provided in the request body.

INSERT INTO snowflake.pipelines.tasks (
name,
warehouse,
schedule,
comment,
finalize,
task_auto_retry_attempts,
config,
session_parameters,
definition,
predecessors,
user_task_managed_initial_warehouse_size,
target_completion_interval,
serverless_task_min_statement_size,
serverless_task_max_statement_size,
user_task_timeout_ms,
suspend_task_after_num_failures,
condition,
allow_overlapping_execution,
error_integration,
database_name,
schema_name,
endpoint,
createMode
)
SELECT 
'{{ name }}' /* required */,
'{{ warehouse }}',
'{{ schedule }}',
'{{ comment }}',
'{{ finalize }}',
{{ task_auto_retry_attempts }},
'{{ config }}',
'{{ session_parameters }}',
'{{ definition }}' /* required */,
'{{ predecessors }}',
'{{ user_task_managed_initial_warehouse_size }}',
'{{ target_completion_interval }}',
'{{ serverless_task_min_statement_size }}',
'{{ serverless_task_max_statement_size }}',
{{ user_task_timeout_ms }},
{{ suspend_task_after_num_failures }},
'{{ condition }}',
{{ allow_overlapping_execution }},
'{{ error_integration }}',
'{{ database_name }}',
'{{ schema_name }}',
'{{ endpoint }}',
'{{ createMode }}'
RETURNING
status
;

Manifest

# Description fields are for documentation purposes
- name: tasks
props:
  - name: database_name
    value: "{{ database_name }}"
    description: Required parameter for the tasks resource.
  - name: schema_name
    value: "{{ schema_name }}"
    description: Required parameter for the tasks resource.
  - name: endpoint
    value: "{{ endpoint }}"
    description: Required parameter for the tasks resource.
  - name: name
    value: "{{ name }}"
    description: |
      String that specifies the identifier (i.e. name) for the task.
  - name: warehouse
    value: "{{ warehouse }}"
    description: |
      Specifies the virtual warehouse that provides compute resources for task runs. Omit this parameter to use serverless compute resources for runs of this task.
  - name: schedule
    description: |
      Specifies the schedule for periodically running the task.
    value:
      schedule_type: "{{ schedule_type }}"
  - name: comment
    value: "{{ comment }}"
    description: |
      Specifies a comment for the task.
  - name: finalize
    value: "{{ finalize }}"
    description: |
      Specifies the name of the root task that the finalizer task is associated with.
  - name: task_auto_retry_attempts
    value: {{ task_auto_retry_attempts }}
    description: |
      Root task settable only. Specifies the number of automatic task graph retry attempts. Valid range is 0 to 30. When not specified, no retry would happen.
  - name: config
    value: "{{ config }}"
    description: |
      Task Config
  - name: session_parameters
    value: "{{ session_parameters }}"
    description: |
      Session Parameters for the task at runtime.
  - name: definition
    value: "{{ definition }}"
    description: |
      The SQL definition for the task. Any one of single SQL statement, call to stored procedure, or procedural logic using Snowflake scripting.
  - name: predecessors
    value:
      - "{{ predecessors }}"
    description: |
      Specifies one or more predecessor tasks for the current task
  - name: user_task_managed_initial_warehouse_size
    value: "{{ user_task_managed_initial_warehouse_size }}"
    description: |
      Specifies the size of the compute resources to provision for the first run of the task. This parameter only applies to serverless tasks.
  - name: target_completion_interval
    description: |
      Specifies the desired task completion time. This parameter only applies to serverless tasks.
    value:
      minutes: {{ minutes }}
      schedule_type: "{{ schedule_type }}"
  - name: serverless_task_min_statement_size
    value: "{{ serverless_task_min_statement_size }}"
    description: |
      Specifies the minimum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE. This parameter only applies to serverless tasks.
  - name: serverless_task_max_statement_size
    value: "{{ serverless_task_max_statement_size }}"
    description: |
      Specifies the maximum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE. This parameter only applies to serverless tasks.
  - name: user_task_timeout_ms
    value: {{ user_task_timeout_ms }}
    description: |
      Specifies the time limit on a single run of the task before it times out (in milliseconds).
  - name: suspend_task_after_num_failures
    value: {{ suspend_task_after_num_failures }}
    description: |
      Specifies the number of consecutive failed task runs after which the current task is suspended automatically.
  - name: condition
    value: "{{ condition }}"
    description: |
      Specifies a Boolean SQL expression condition; multiple conditions joined with AND/OR are supported
  - name: allow_overlapping_execution
    value: {{ allow_overlapping_execution }}
    description: |
      Specifies whether to allow multiple instances of the DAG to run concurrently.
  - name: error_integration
    value: "{{ error_integration }}"
    description: |
      Specifies the name of the notification integration used to communicate with Amazon SNS, MS Azure Event Grid, or Google Pub/Sub.
  - name: createMode
    value: "{{ createMode }}"
    description: Parameter allowing support for different modes of resource creation. Possible values include: - `errorIfExists`: Throws an error if you try to create a resource that already exists. - `orReplace`: Automatically replaces the existing resource with the current one. - `ifNotExists`: Creates a new resource when an alter is requested for a non-existent resource.
    description: Parameter allowing support for different modes of resource creation. Possible values include: - `errorIfExists`: Throws an error if you try to create a resource that already exists. - `orReplace`: Automatically replaces the existing resource with the current one. - `ifNotExists`: Creates a new resource when an alter is requested for a non-existent resource.

REPLACE examples

create_or_alter

Create a (or alter an existing) task. Even if the operation is just an alter, the full property set must be provided.

REPLACE snowflake.pipelines.tasks
SET 
name = '{{ name }}',
warehouse = '{{ warehouse }}',
schedule = '{{ schedule }}',
comment = '{{ comment }}',
finalize = '{{ finalize }}',
task_auto_retry_attempts = {{ task_auto_retry_attempts }},
config = '{{ config }}',
session_parameters = '{{ session_parameters }}',
definition = '{{ definition }}',
predecessors = '{{ predecessors }}',
user_task_managed_initial_warehouse_size = '{{ user_task_managed_initial_warehouse_size }}',
target_completion_interval = '{{ target_completion_interval }}',
serverless_task_min_statement_size = '{{ serverless_task_min_statement_size }}',
serverless_task_max_statement_size = '{{ serverless_task_max_statement_size }}',
user_task_timeout_ms = {{ user_task_timeout_ms }},
suspend_task_after_num_failures = {{ suspend_task_after_num_failures }},
condition = '{{ condition }}',
allow_overlapping_execution = {{ allow_overlapping_execution }},
error_integration = '{{ error_integration }}'
WHERE 
database_name = '{{ database_name }}' --required
AND schema_name = '{{ schema_name }}' --required
AND task_name = '{{ task_name }}' --required
AND endpoint = '{{ endpoint }}' --required
AND name = '{{ name }}' --required
AND definition = '{{ definition }}' --required
RETURNING
status;

DELETE examples

delete

Delete a task with the task name. If ifExists is used, the operation will succeed even if the object does not exist. Otherwise, there will be a failure if the drop is unsuccessful.

DELETE FROM snowflake.pipelines.tasks
WHERE database_name = '{{ database_name }}' --required
AND schema_name = '{{ schema_name }}' --required
AND name = '{{ name }}' --required
AND endpoint = '{{ endpoint }}' --required
AND ifExists = '{{ ifExists }}'
;

Lifecycle Methods

execute

Execute a task -- this is equivalent to EXECUTE IMMEDIATE.

EXEC snowflake.pipelines.tasks.execute 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@asyncExec={{ asyncExec }}, 
@retryLast={{ retryLast }}
;

resume

Resumes a suspended task object. This is equivalento an ALTER TASK ... RESUME.

EXEC snowflake.pipelines.tasks.resume 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required
;

suspend

Suspends a running task. This is equivalent to an ALTER TASK ... SUSPEND.

EXEC snowflake.pipelines.tasks.suspend 
@database_name='{{ database_name }}' --required, 
@schema_name='{{ schema_name }}' --required, 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required
;