CREATE TASK

CREATE TASK

CREATE TASK 명령은 현재/지정된 스키마에 새 태스크(task)를 만들거나 기존 태스크를 교체하는 명령이에요. 태스크는 스케줄이나 작업 그래프에 따라 SQL 코드를 실행하는 객체입니다.

출처: CREATE TASK

본문

현재/지정된 스키마에 새 태스크를 만들거나 기존 태스크를 교체하는 명령입니다. 이 명령은 다음 변형을 지원해요: ALTER TASK, DROP TASK, SHOW TASKS, DESCRIBE TASK

중요 새로 만들거나 복제한 태스크는 일시 중지된(changed suspended) 상태로 생성됩니다. 일시 중지된 태스크 실행에 대한 내용은 ALTER TASK … RESUME 또는 EXECUTE TASK를 참고하세요.

Syntax

CREATE [ OR REPLACE ] TASK [ IF NOT EXISTS ] <name>
    [ WITH TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
    [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]
    [ { WAREHOUSE = <string> }
      | { USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = <string> } ]
    [ SCHEDULE = { '<num> { HOURS | MINUTES | SECONDS }'
      | 'USING CRON <expr> <time_zone>' } ]
    [ CONFIG = <configuration_string> ]
    [ OVERLAP_POLICY = { NO_OVERLAP | ALLOW_CHILD_OVERLAP | ALLOW_ALL_OVERLAP } ]
    [ <session_parameter> = <value>
      [ , <session_parameter> = <value> ... ] ]
    [ USER_TASK_TIMEOUT_MS = <num> ]
    [ SUSPEND_TASK_AFTER_NUM_FAILURES = <num> ]
    [ ERROR_INTEGRATION = <integration_name> ]
    [ SUCCESS_INTEGRATION = <integration_name> ]
    [ LOG_LEVEL = '<log_level>' ]
    [ COMMENT = '<string_literal>' ]
    [ FINALIZE = <string> ]
    [ TASK_AUTO_RETRY_ATTEMPTS = <num> ]
    [ USER_TASK_MINIMUM_TRIGGER_INTERVAL_IN_SECONDS = <num> ]
    [ TARGET_COMPLETION_INTERVAL = '<num> { HOURS | MINUTES | SECONDS }' ]
    [ SERVERLESS_TASK_MIN_STATEMENT_SIZE = '{ XSMALL | SMALL
      | MEDIUM | LARGE | XLARGE | XXLARGE }' ]
    [ SERVERLESS_TASK_MAX_STATEMENT_SIZE = '{ XSMALL | SMALL
      | MEDIUM | LARGE | XLARGE | XXLARGE }' ]
  [ AFTER <string> [ , <string> , ... ] ]
  [ EXECUTE AS USER <user_name> ]
  [ WHEN <boolean_expr> ]
  AS
    <sql>

Variant syntax

CREATE OR ALTER TASK

이미 존재하지 않으면 새 태스크를 만들고, 존재하면 기존 태스크를 문에 정의된 태스크로 변환해요. CREATE OR ALTER TASK 문은 CREATE TASK 문의 구문 규칙을 따르며 ALTER TASK 문과 동일한 제한 사항을 가집니다.

CREATE OR ALTER TASK <name>
    [ { WAREHOUSE = <string> }
      | { USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = <string> } ]
    [ SCHEDULE = { '<num> { HOURS | MINUTES | SECONDS }'
      | 'USING CRON <expr> <time_zone>' } ]
    [ CONFIG = <configuration_string> ]
    [ OVERLAP_POLICY = { NO_OVERLAP | ALLOW_CHILD_OVERLAP | ALLOW_ALL_OVERLAP } ]
    [ USER_TASK_TIMEOUT_MS = <num> ]
    [ <session_parameter> = <value>
      [ , <session_parameter> = <value> ... ] ]
    [ SUSPEND_TASK_AFTER_NUM_FAILURES = <num> ]
    [ ERROR_INTEGRATION = <integration_name> ]
    [ SUCCESS_INTEGRATION = <integration_name> ]
    [ COMMENT = '<string_literal>' ]
    [ FINALIZE = <string> ]
    [ TASK_AUTO_RETRY_ATTEMPTS = <num> ]
  [ AFTER <string> [ , <string> , ... ] ]
  [ EXECUTE AS USER <user_name> ]
  [ WHEN <boolean_expr> ]
  AS
    <sql>

CREATE TASK … CLONE

같은 파라미터 값을 가진 새 태스크를 만들어요.

CREATE [ OR REPLACE ] TASK <name> CLONE <source_task>
  [ ... ]

자세한 내용은 CREATE … CLONE 문서를 참고하세요.

참고 CREATE TASK <name> CLONE으로 태스크를 복제하거나 태스크가 포함된 스키마를 복제하면, 명시적으로 재정의되지 않는 한 모든 기본 태스크 속성이 복사됩니다.

Required parameters (필수 파라미터)

  • name — 태스크의 식별자를 지정하는 문자열이에요. 태스크가 생성되는 스키마 내에서 고유해야 합니다. 또한 식별자는 알파벳 문자로 시작해야 하고, 전체 식별자 문자열을 큰따옴표로 감싸지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 감싼 식별자는 대소문자를 구분합니다. 자세한 내용은 Identifier requirements 문서를 참고하세요.
  • <sql> — 태스크가 실행될 때 실행되는 SQL 코드예요. 태스크에서 사용하기 전에 SQL이 예상대로 실행되는지 확인하세요.

Clone tasks in a task graph

작업 그래프의 경우 의존 태스크(각 자식 태스크 또는 파이널라이저 태스크)의 클론을 만들어야 할 수도 있어요.

Optional parameters (선택 파라미터)

  • WAREHOUSE = <string> — 태스크 실행에 컴퓨트 리소스를 제공하는 가상 웨어하우스를 지정해요. 이 파라미터를 생략하면 태스크 실행에 서버리스 컴퓨트 리소스를 사용합니다. Snowflake는 각 워크로드에 필요한 대로 서버리스 컴퓨트 리소스를 자동으로 크기 조정·확장해요. 태스크에 스케줄이 지정되면 Snowflake는 지정된 시간 내에 태스크의 향후 실행을 완료하도록 리소스 크기를 조정합니다. 태스크의 초기 웨어하우스 크기를 지정하려면 USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = string 파라미터를 설정하세요.
  • USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = <string> — 태스크 기록이 있어 Snowflake가 이상적인 크기를 결정하기 전에, 태스크의 첫 실행에 프로비저닝할 컴퓨트 리소스의 크기를 지정해요. 태스크가 몇 번 성공적으로 실행된 이후에는 이 파라미터 설정을 무시합니다. 태스크 기록을 사용할 수 없으면 컴퓨트 리소스는 이 초기 크기로 되돌아갑니다. WAREHOUSE = string 파라미터 값을 지정하면 이 파라미터를 설정하면 사용자 오류가 발생해요. 크기는 CREATE WAREHOUSE로 웨어하우스를 만들 때 사용 가능한 컴퓨트 리소스(SMALL, MEDIUM, LARGE 등)와 동등하며, 이 파라미터가 지원하는 최대 크기는 XXLARGE입니다. 생략하면 태스크의 첫 실행은 MEDIUM 크기 웨어하우스로 실행됩니다. 자세한 내용은 USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE 문서를 참고하세요.
  • SCHEDULE — 태스크를 주기적으로 실행하는 스케줄을 지정해요.
  • OVERLAP_POLICY — 작업 그래프 실행의 중첩 정책을 지정해요. 작업 그래프의 여러 인스턴스가 동시에 실행될 수 있는지와 허용되는 병렬 수준을 제어합니다. 기본값: NO_OVERLAP
  • <session_parameter> = <value> — 태스크가 실행될 때 세션에 설정할 세션 파라미터의 쉼표로 구분된 목록을 지정해요. 태스크는 모든 세션 파라미터를 지원합니다. 태스크에서 지원되지 않는 특정 세션 파라미터 구성이 있습니다.
  • USER_TASK_TIMEOUT_MS = <num> — 태스크의 단일 실행이 시간 초과되기 전까지의 시간 제한(밀리초)을 지정해요. 값: 0 ~ 604800000(7일). 값 0은 최대 시간 초과 값이 적용됨을 지정합니다. 기본값: 3600000 (1시간)
  • SUSPEND_TASK_AFTER_NUM_FAILURES = <num> — 현재 태스크가 자동으로 일시 중지되기 전까지의 연속 실패한 태스크 실행 횟수를 지정해요. 실패한 태스크 실행은 태스크 본문의 SQL 코드가 사용자 오류를 만들거나 시간 초과된 실행을 포함합니다. 건너뛰거나 취소되었거나 시스템 오류로 실패한 실행은 불확정으로 간주되어 실패 횟수에 포함되지 않아요. 값 0은 실패한 태스크가 자동으로 일시 중지되지 않음을 의미합니다. 설정은 서버리스 또는 가상 웨어하우스 컴퓨트 리소스에 의존하는 태스크에 적용됩니다. 기본값: 10
  • ERROR_INTEGRATION = <integration_name> — Amazon SNS, MS Azure Event Grid, Google Pub/Sub와 통신하는 데 사용되는 알림 통합의 이름을 지정해요. 태스크 오류 알림 설정에 대한 자세한 내용은 Set up error notifications for tasks 문서를 참고하세요.
  • SUCCESS_INTEGRATION = <integration_name> — Amazon SNS, MS Azure Event Grid, Google Pub/Sub와 통신하는 데 사용되는 알림 통합의 이름을 지정해요.
  • LOG_LEVEL = '<log_level>' — 활성 이벤트 테이블에서 수집·사용 가능하게 해야 하는 이 태스크의 이벤트 심각도 수준을 지정해요. 지정된 수준(및 더 심각한 수준)의 이벤트가 수집됩니다.
  • COMMENT = '<string_literal>' — 태스크에 대한 주석을 지정해요. 기본값: 값 없음
  • AFTER <string> [ , ... ] — 현재 태스크의 선행(predecessor) 태스크를 하나 이상 지정해요. 이 옵션을 사용해 작업 그래프를 만들거나 이 태스크를 기존 작업 그래프에 추가합니다. 작업 그래프는 스케줄된 루트 태스크로 시작해 의존성으로 연결된 일련의 태스크예요. 태스크는 모든 선행 태스크가 자신의 실행을 성공적으로 마친 후에 실행됩니다.
  • WHEN <boolean_expr> — 부울 SQL 표현식을 지정해요. AND/OR로 결합된 여러 조건이 지원됩니다. 태스크가 실행되면 표현식의 조건을 검증해 실행 여부를 결정합니다. 표현식 조건이 충족되지 않으면 태스크는 현재 실행을 건너뜁니다. 이 태스크를 선행 태스크로 식별하는 태스크들도 실행되지 않아요. WHEN 표현식 조건의 검증은 컴퓨트 리소스가 필요하지 않으며 클라우드 서비스 계층에서 처리됩니다. 태스크가 WHEN 조건을 평가하고 실행하지 않을 때마다 명목 요금이 누적됩니다. 태스크가 실행될 때까지 태스크가 트리거될 때마다 요금이 누적되며, 그때 요금은 Snowflake 크레딧으로 변환되어 태스크 실행의 컴퓨트 리소스 사용량에 추가됩니다. 일반적으로 조건 검증의 컴퓨트 시간은 태스크 실행 시간에 비해 미미합니다. 일일 클라우드 서비스 소비가 컴퓨트 리소스 일일 사용량의 10% 할당량 미만이면 클라우드 서비스 요금이 발생하지 않습니다.
  • TAG ( ... ) — 태그 이름과 태그 문자열 값을 지정해요. 태그 값은 항상 문자열이며 최대 문자 수는 256이에요. CREATE OR ALTER 변형 구문에서는 지원되지 않습니다.
  • WITH CONTACT ( ... ) — 새 객체를 하나 이상의 연락처와 연결하고, 연락처를 참조하는 purpose를 지정해요.
  • FINALIZE = <string> — 파이널라이저 태스크가 연결되는 루트 태스크의 이름을 지정해요. 파이널라이저 태스크는 작업 그래프의 다른 모든 태스크가 완료된 후 실행됩니다. 파이널라이저 태스크의 SQL은 작업 그래프가 사용하는 알림, 리소스 해제 및 정리를 처리하도록 정의할 수 있어요. 자세한 내용은 Finalizer task 문서를 참고. 기본값: 값 없음
  • TASK_AUTO_RETRY_ATTEMPTS = <num> — 자동 작업 그래프 재시도 횟수를 지정해요. 작업 그래프가 FAILED 상태로 완료되면 Snowflake는 그래프에서 실패한 마지막 태스크부터 작업 그래프를 자동으로 재시도할 수 있어요. 자동 재시도는 기본적으로 비활성화되어 있으며, 작업 그래프의 루트 태스크에 TASK_AUTO_RETRY_ATTEMPTS를 0보다 큰 값으로 설정해 활성화합니다. 루트 태스크에 설정해야 하며, 자식 태스크에 설정하면 오류가 반환됩니다. 값: 0 ~ 30. 기본값: 0
  • USER_TASK_MINIMUM_TRIGGER_INTERVAL_IN_SECONDS = <num> — 태스크가 실행될 수 있는 빈도(초)를 정의해요. 지정된 최소값보다 자주 데이터 변경이 발생하면 변경이 함께 그룹화되어 처리됩니다. 값: 최소 10, 최대 604800. 기본값: 30
  • TARGET_COMPLETION_INTERVAL = '<num> { HOURS | MINUTES | SECONDS }' — 원하는 태스크 완료 시간을 지정해요. 이 파라미터는 서버리스 태스크에만 적용되고 태스크에만 설정됩니다. 서버리스 Triggered 태스크를 만들 때 필수입니다. 값: 1086400 SECONDS, 11440 MINUTES, 또는 1~24 HOURS(즉 10초에서 1일에 해당). 양의 정수만 허용하며, HOUR, MINUTE, SECOND, H, M, S 표기법도 지원됩니다. 기본값: Snowflake가 다음 예정 실행 시간 전에 완료하도록 서버리스 컴퓨트 리소스를 크기 조정합니다.
  • SERVERLESS_TASK_MIN_STATEMENT_SIZE — 서버리스 태스크의 최소 허용 웨어하우스 크기를 지정해요. 값: 최소 XSMALL, 최대 XXLARGE. WAREHOUSE_SIZE 값과 일치하며 X2LARGE 표기법도 지원됩니다. 기본값: XSMALL
  • SERVERLESS_TASK_MAX_STATEMENT_SIZE — 서버리스 태스크의 최대 허용 웨어하우스 크기를 지정해요. 값: 최소 XSMALL, 최대 XXLARGE. 기본값: XXLARGE
  • EXECUTE AS USER <user_name> — 지정된 사용자 계정을 대신해 태스크를 실행해요. 명령을 실행하는 사용자는 GRANT IMPERSONATE ON USER TO ROLE 명령으로 부여된 권한을 보유해야 합니다. 자세한 내용은 Run tasks with user privileges 문서를 참고하세요.

Access control requirements (접근 제어 요구 사항)

이 작업을 실행하는 데 사용되는 역할은 최소한 다음 권한을 보유해야 해요. 기존 태스크에 대해 CREATE OR ALTER TASK 문을 실행할 때만 필요합니다. OWNERSHIP은 객체를 생성한 역할에 자동으로 부여되는 특별한 권한이지만, 소유 역할(또는 MANAGE GRANTS 권한이 있는 역할)이 GRANT OWNERSHIP 명령으로 다른 역할에 이전할 수 있습니다.

스키마의 객체를 조작하려면 상위 데이터베이스에 대한 권한과 상위 스키마에 대한 권한이 각각 최소 하나씩 필요합니다. 지정된 권한 집합으로 사용자 정의 역할을 만드는 방법은 Creating custom roles 문서를, 보안 객체에 대한 SQL 작업의 역할·권한 부여에 대한 일반적인 정보는 Overview of Access Control 문서를 참고하세요.

Usage notes (사용 참고 사항)

Examples (예제)

Single SQL statement

일요일 오전 9:18에 시작해 오후 5:18에 끝나는 매시간 현재 타임스탬프를 쿼리하는 서버리스 태스크(America/Los_Angeles 시간대)를 만들어 봅시다. 초기 웨어하우스 크기는 XSMALL입니다.

CREATE TASK t1
  SCHEDULE = 'USING CRON 18 9-17 * * SUN America/Los_Angeles'  -- Use a random minute such as 18
  USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL'
  AS
    SELECT CURRENT_TIMESTAMP;

이전 예제와 같지만 태스크가 실행을 위한 컴퓨트 리소스를 사용자 관리 웨어하우스에 의존하는 예제예요.

CREATE TASK mytask_hour
  WAREHOUSE = mywh
  SCHEDULE = 'USING CRON 34 9-17 * * SUN America/Los_Angeles'  -- Use a random minute such as 34
  AS
    SELECT CURRENT_TIMESTAMP;

태스크가 실행되는 세션의 TIMESTAMP_INPUT_FORMAT 파라미터를 설정하면서, 매시간 현재 타임스탬프를 테이블에 삽입하는 서버리스 태스크를 만들어 봅시다. 이 세션 파라미터는 삽입된 타임스탬프의 형식을 지정해요.

CREATE TASK t1
  SCHEDULE = '60 MINUTES'
  TIMESTAMP_INPUT_FORMAT = 'YYYY-MM-DD HH24'
  USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL'
  AS
    INSERT INTO mytable(ts) VALUES(CURRENT_TIMESTAMP);

매 5분마다 현재 타임스탬프를 테이블에 삽입하는 태스크를 만들어 봅시다.

CREATE TASK mytask_minute
  WAREHOUSE = mywh
  SCHEDULE = '5 MINUTES'
  AS
    INSERT INTO mytable(ts) VALUES(CURRENT_TIMESTAMP);

더 알아보기 (Learn more)