ALTER TASK

기존 태스크(task)의 속성을 수정하는 명령이에요.

출처: 문서

본문

태스크에 대한 자세한 내용은 Introduction to tasks를 참고하세요.

관련 명령: CREATE TASK, DROP TASK, SHOW TASKS, DESCRIBE TASK

구문 (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> }
    | { 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> ]
  [ SUSPEND_TASK_AFTER_NUM_FAILURES = <num> ]
  [ ERROR_INTEGRATION = <integration_name> ]
  [ SUCCESS_INTEGRATION = <integration_name> ]
  [ LOG_LEVEL = '<log_level>' ]
  [ COMMENT = <string> ]
  [ <session_parameter> = <value>
    [ , <session_parameter> = <value> ... ] ]
  [ 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' ]
  [ CONTACT <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ]
  [ EXECUTE AS USER <user_name> ]

ALTER TASK [ IF EXISTS ] <name> UNSET
  [ WAREHOUSE ]
  [ SCHEDULE ]
  [ CONFIG ]
  [ OVERLAP_POLICY ]
  [ USER_TASK_TIMEOUT_MS ]
  [ SUSPEND_TASK_AFTER_NUM_FAILURES ]
  [ LOG_LEVEL ]
  [ COMMENT ]
  [ <session_parameter> [ , <session_parameter> ... ] ]
  [ TARGET_COMPLETION_INTERVAL ]
  [ SERVERLESS_TASK_MIN_STATEMENT_SIZE ]
  [ SERVERLESS_TASK_MAX_STATEMENT_SIZE ]
  [ CONTACT <purpose> [ , ... ]]
  [ EXECUTE AS USER ]
  [ DCM PROJECT ]

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>

ALTER TASK [ IF EXISTS ] <name> REMOVE WHEN

파라미터 (Parameters)

*name*

수정할 태스크의 식별자예요. 식별자에 공백이나 특수 문자가 포함되면 전체 문자열을 큰따옴표로 감싸야 해요. 큰따옴표로 감싼 식별자는 대소문자를 구분해요.

RESUME | SUSPEND

태스크에 수행할 작업을 지정해요:

RESUME는 중단된 태스크를 'Started' 상태로 전환해요. 계정은 현재 최대 30000개의 시작된 태스크로 제한된다는 점에 유의하세요.

Task Graph의 루트 태스크를 다시 시작하기 전에 모든 하위 태스크를 다시 시작해요. 루트 태스크의 하위 태스크를 재귀적으로 다시 시작하려면 SYSTEM$TASK_DEPENDENTS_ENABLE을 사용해요.
SUSPEND는 태스크를 'Suspended' 상태로 전환해요.

태스크 스케줄이 (*number* { HOURS | MINUTES | SECONDS }) 간격으로 설정된 경우, 스케줄의 *기준 간격 시간(base interval time)*은 태스크가 다시 시작될 때 현재 시간으로 재설정돼요.

기준 간격 시간은 현재 시계 시간부터 간격 카운터를 시작해요. 예를 들어 10 MINUTES의 INTERVAL 값이 설정되고 태스크가 오전 9:03에 다시 시작되면 태스크는 오전 9:13, 9:23 등에 실행돼요. 태스크가 설정된 간격 이전에 실행되지 않는다는 것만 보장한다는 점에 유의하세요. 이 예에서 태스크는 오전 9:14에 처음 실행될 수 있지만 오전 9:12에는 실행되지 않아요.

REMOVE AFTER *string* [ , *string* , ... ]

태스크 그래프(task graph)에서 이 하위 태스크의 현재 선행(이전) 태스크 이름 하나 이상을 지정해요.

하위 태스크의 모든 선행 태스크가 제거되면, 이전 하위 태스크는 다른 태스크가 이 하위 태스크를 선행으로 식별하는지 여부에 따라 독립형 태스크 또는 루트 태스크가 돼요. 이전 하위 태스크가 루트 태스크가 되면 이 태스크는 기본적으로 중단되고 수동으로 다시 시작해야 해요.

ADD AFTER *string* [ , *string* , ... ]

태스크 그래프에서 이 하위 태스크의 선행으로 추가할 기존 태스크 이름 하나 이상을 지정해요. 태스크 그래프의 각 하위 태스크는 모든 선행 태스크가 성공적으로 실행을 마칠 때 실행돼요. 자세한 내용은 CREATE TASK의 AFTER 파라미터 설명을 참고하세요.

각 하위 태스크는 최대 100개의 선행 태스크로 제한돼요.

SET ...

다음 중 하나 또는 둘 다를 지정해요:

공백, 쉼표 또는 새 줄로 구분된 태스크에 대해 설정할 속성 하나 이상. 설정할 수 있는 속성에 대한 자세한 내용은 CREATE TASK를 참고하세요.

태스크에 구성을 설정할 때 태스크의 기본 구성 문자열을 지정해요. 단일 실행에 대한 기본 구성을 재정의하려면 EXECUTE TASK 명령을 사용해요.
태스크가 실행될 때 세션에 대해 설정할 세션 파라미터의 쉼표로 구분된 목록. 태스크는 모든 세션 파라미터를 지원해요. 전체 목록은 Parameters를 참고하세요.
TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

태그(tag) 이름과 태그 문자열 값을 지정해요.

태그 값은 항상 문자열이고 태그 값의 최대 문자 수는 256이에요.

문에서 태그를 지정하는 방법에 대한 정보는 Tag quotas를 참고하세요.
CONTACT purpose = contact [ , purpose = contact ... ]

기존 객체를 하나 이상의 연락처(contacts)와 연결해요. 유효한 목적 목록은 Associate a contact with an object를 참고하세요.

같은 문에서 CONTACT 속성을 다른 속성과 함께 설정할 수 없어요.

UNSET ...

태스크에 대해 설정 해제할 속성 및/또는 세션 파라미터 하나(이상)를 지정하며, 기본값으로 재설정돼요.

단일 ALTER 문으로 여러 속성/파라미터를 재설정할 수 있어요. 다만 각 속성/파라미터는 쉼표로 구분해야 해요. 속성/파라미터를 재설정할 때는 이름만 지정해요. 속성/파라미터에 값을 지정하면 오류가 반환돼요.

태스크에서 연락처를 분리하려면 UNSET CONTACT *purpose*를 지정해요. 같은 문에서 CONTACT 속성을 다른 속성과 함께 해제할 수 없어요.

UNSET DCM PROJECT

태스크를 현재 관리하는 DCM 프로젝트에서 분리해요. 이 명령은 태스크를 삭제하지 않고 태스크와 DCM 프로젝트 사이의 연관을 제거해요. 자세한 내용은 Detach objects from a DCM project를 참고하세요.

*sql*

태스크가 실행될 때 실행할 SQL 코드를 지정해요:

단일 SQL 문
저장 프로시저 호출
Snowflake Scripting을 사용한 절차적 로직

현재 Snowsight는 태스크가 Snowflake Scripting을 사용하도록 만들거나 수정하는 것을 지원하지 않는다는 점에 유의하세요. 대신 SnowSQL 또는 다른 명령줄 클라이언트를 사용해요.

참고

태스크를 만들기 전에 태스크에서 참조하는 SQL 코드가 예상대로 실행되는지 확인해요. 태스크는 이미 철저히 테스트된 SQL 코드를 자동화하기 위한 것이에요.

WHEN *boolean_expr*

Boolean SQL 표현식을 지정해요. 태스크가 트리거되면 실행 여부를 결정하기 위해 표현식의 조건을 검증해요. 표현식의 조건이 충족되지 않으면 태스크는 현재 실행을 건너뛰어요. 이 태스크를 선행으로 식별하는 태스크도 실행되지 않아요.

WHEN 표현식의 조건을 검증하는 데는 가상 웨어하우스가 필요하지 않아요. 검증은 대신 클라우드 서비스 계층에서 처리돼요. 태스크가 WHEN 조건을 평가하고 실행되지 않을 때마다 소액 요금이 발생해요. 태스크가 실행될 때까지 트리거될 때마다 요금이 누적돼요. 그 시점에 요금은 Snowflake 크레딧으로 전환되어 태스크 실행의 컴퓨트 리소스 사용에 추가돼요.

일반적으로 조건 검증에 걸리는 컴퓨트 시간은 태스크 실행 시간에 비해 미미해요. 모범 사례로 예약 태스크 실행과 실제 태스크 실행을 최대한 일치시키세요. 실제 태스크 실행과 크게 어긋난 태스크 스케줄은 피하세요. 예를 들어 데이터가 약 24시간마다 스트림으로 테이블에 삽입된다면 매분 스트림 데이터를 확인하는 태스크를 예약하지 마세요. 각 실행의 WHEN 표현식 검증 요금은 일반적으로 미미하지만 요금은 누적돼요.

일일 클라우드 서비스 사용이 컴퓨트 리소스 일일 사용량의 10% 할당량 미만이면 클라우드 서비스 요금이 누적되지 않는다는 점에 유의하세요.

현재 SQL 표현식에서 평가하기 위해 다음 함수가 지원돼요:

SYSTEM$STREAM_HAS_DATA

지정된 스트림이 변경 추적 데이터를 포함하는지 여부를 나타내요. 태스크에 대한 스케줄이 정의되지 않은 경우 트리거된 태스크를 실행하는 데 사용돼요. 스트림에 변경 데이터가 없으면 현재 태스크 실행을 건너뛰는 데도 사용할 수 있어요.

결과가 FALSE이면 태스크가 실행되지 않아요.

SYSTEM$GET_PREDECESSOR_RETURN_VALUE

태스크 그래프에서 선행 태스크의 반환 값을 가져와요. 반환된 결과에 따라 태스크가 실행되어야 하는지 결정하는 데 사용돼요.

REMOVE WHEN

지정한 WHEN 조건을 제거해요.

EXECUTE AS USER *user_name*

지정된 사용자 계정을 대신하여 태스크를 실행해요. 명령을 실행하는 사용자는 GRANT IMPERSONATE ON USER TO ROLE 명령으로 부여된 권한이 있어야 해요.

자세한 내용은 Run tasks with user privileges를 참고하세요.

태스크 이름 바꾸기 (Rename a task)

태스크 이름 바꾸기는 지원되지 않아요. 대신 태스크를 복제한 다음 기존 태스크를 삭제할 수 있어요. 예:

태스크를 중단해요(ALTER TASK task_old_name SUSPEND).
태스크에 새 이름을 부여해 복제해요(CREATE TASK new_task_name CLONE old_task_name).
태스크 그래프에 대해 이전 태스크 이름을 참조하는 의존 태스크를 찾아 새 이름을 사용하도록 업데이트해요:
TASK_DEPENDENTS … RECURSIVE 함수를 사용해 즉시 의존 태스크(즉 하위 태스크와 finalizer 태스크, 단 손자-하위 태스크는 아님)를 찾아요. 예:

SELECT * FROM TABLE(INFORMATION_SCHEMA.TASK_DEPENDENTS('old_task_name', RECURSIVE => false));

각 의존 태스크를 새 태스크 이름을 사용하도록 업데이트해요(ALTER TASK child_task_1 ADD AFTER new_task_name).
이전 버전의 태스크를 삭제해요(DROP TASK old_task_name).
새 버전의 태스크를 다시 시작해요(ALTER TASK new_task_name RESUME).

사용 참고사항 (Usage notes)

태스크를 다시 시작하거나 중단하려면(각각 ALTER TASK … RESUME 또는 ALTER TASK … SUSPEND) 태스크에 OWNERSHIP 또는 OPERATE 권한이 필요해요.

태스크가 다시 시작될 때 Snowflake는 태스크에 OWNERSHIP 권한이 있는 역할이 태스크에 할당된 웨어하우스에 대한 USAGE 권한과 전역 EXECUTE TASK 권한도 가지고 있는지 확인해요. 그렇지 않으면 오류가 발생해요.

계정 관리자(ACCOUNTADMIN 역할을 가진 사용자)만 역할에 EXECUTE TASK 권한을 부여할 수 있어요. 사용 편의를 위해 사용자 지정 역할(예: TASKADMIN)을 만들고 이 역할에 EXECUTE TASK 권한을 할당하는 것을 권장해요. 그러면 권한을 부여할 수 있는 모든 역할(예: SECURITYADMIN 또는 MANAGE GRANTS 권한이 있는 역할)이 이 사용자 지정 역할을 태스크 소유자 역할에 부여해 자체 태스크를 수정할 수 있게 해요. 사용자 지정 역할과 역할 계층 만들기 지침은 Configuring access control을 참고하세요.
태스크 소유자(즉 태스크에 OWNERSHIP 권한이 있는 역할)만 태스크의 속성을 설정하거나 해제할 수 있어요.
기본 CONFIG를 수정하려면 전체 대체 JSON 문자열을 제공해야 해요. 개별 키-값 쌍을 업데이트할 수 없어요. 단일 실행에 대한 기본 구성을 재정의하려면 EXECUTE TASK를 사용해요.
독립형 태스크는 수정되기 전에 중단되어야 해요.
태스크 그래프의 루트 태스크는 그래프의 어떤 태스크가 수정되거나, 하위 태스크가 중단·재개되거나, 하위 태스크가 추가(ALTER TASK … AFTER 사용)되기 전에 중단되어야 해요.
태스크 그래프는 재개 또는 중단 상태에서 총 (루트 태스크 포함) 최대 1000개 태스크로 제한돼요.
태스크 그래프에서 루트 태스크와 연결된 모든 의존 태스크를 재귀적으로 다시 시작하려면 각 태스크를 개별적으로 활성화(ALTER TASK … RESUME)하는 대신 SYSTEM$TASK_DEPENDENTS_ENABLE 함수를 쿼리해요.
기본적으로 트랜잭션을 명시적으로 시작하지 않고 실행된 DML 문은 문이 끝날 때 성공 시 자동 커밋되거나 실패 시 롤백돼요. 이 동작을 autocommit이라고 하며 AUTOCOMMIT 파라미터로 제어돼요. 이 파라미터는 TRUE로 설정되어야 해요. AUTOCOMMIT 파라미터가 계정 수준에서 FALSE로 설정되어 있으면 개별 태스크에 대해 파라미터를 TRUE로 설정해요(ALTER TASK … SET AUTOCOMMIT = TRUE).
태스크가 중단되면 태스크의 현재 실행(즉 TASK_HISTORY 출력에서 EXECUTING 상태의 실행)이 완료돼요. 지정된 태스크의 실행을 중단하려면 SYSTEM$USER_TASK_CANCEL_ONGOING_EXECUTIONS 함수를 실행해요.
태스크 개별 실행의 컴퓨트 리소스는 Snowflake가 관리(서버리스 컴퓨트 모델)하거나 사용자가 지정한 가상 웨어하우스가 관리해요. 웨어하우스에 의존하는 태스크를 서버리스 컴퓨트 모델로 변환하려면 WAREHOUSE를 설정 해제해요.
태스크가 예기치 않은 오류로 실패하면 오류에 대한 알림을 받을 수 있어요. 태스크 오류 알림 구성에 대한 자세한 내용은 Set up error notifications for tasks를 참고하세요.
OVERLAP_POLICY 파라미터는 더 이상 사용되지 않는 ALLOW_OVERLAPPING_EXECUTION 파라미터를 대체해요. 하위 호환성을 위해 ALLOW_OVERLAPPING_EXECUTION = TRUE는 OVERLAP_POLICY = ALLOW_CHILD_OVERLAP로, ALLOW_OVERLAPPING_EXECUTION = FALSE는 OVERLAP_POLICY = NO_OVERLAP로 매핑돼요.
메타데이터에 관해: 고객은 Snowflake 서비스를 사용할 때 메타데이터로 개인 데이터(User 객체 외), 민감 데이터, 수출 통제 데이터 또는 기타 규제 데이터를 입력하지 않도록 해야 해요. 자세한 내용은 Metadata fields in Snowflake를 참고하세요.
finalizer 태스크에 관해:
- SET FINALIZE = <root task name>을 실행하면 일반 태스크가 주어진 루트 태스크와 연결된 finalizer 태스크로 구성돼요.
- UNSET FINALIZE를 실행하면 finalizer 태스크가 스케줄이나 선행 태스크가 없는 일반 독립형 태스크로 바뀌어요.
- SET FINALIZE는 SET SCHEDULE 및 ADD AFTER와 충돌해요. 기존 스케줄이나 선행 태스크가 있는 태스크도 SET FINALIZE 쿼리를 실패시켜요.
- 루트 태스크의 정의된 finalizer 태스크를 수정하려면 먼저 UNSET FINALIZE를 사용해 finalizer 태스크를 해제한 다음 SET FINALIZE = <root task name>을 사용해 루트 태스크의 finalizer 태스크를 업데이트해요.
- finalizer 태스크가 수정·설정·해제되기 전에 루트 태스크는 중단되어야 해요.
자세한 내용은 Finalizer task를 참고하세요.

예제 (Examples)

다음 예제는 태스크의 운영을 시작해요:

ALTER TASK mytask RESUME;

다음 예제는 태스크를 서버리스 컴퓨트 모델로 변환하고 태스크의 첫 서버리스 실행에 대해 프로비저닝할 컴퓨트 리소스 양으로 xsmall을 설정해요:

ALTER TASK mytask UNSET WAREHOUSE;

ALTER TASK mytask SET USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL';

다음 예제는 태스크가 실행되는 세션의 TIMEZONE과 CLIENT_TIMESTAMP_TYPE_MAPPING 세션 파라미터를 설정해요:

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

다음 예제는 태스크에 다른 스케줄을 설정해요:

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

다음 예제는 mytask 하위 태스크의 현재 선행 태스크(pred_task1, pred_task2)를 제거하고 다른 선행 태스크(pred_task3)로 교체해요:

ALTER TASK mytask REMOVE AFTER pred_task1, pred_task2;

ALTER TASK mytask ADD AFTER pred_task3;

다음 예제는 태스크와 연결된 SQL 문을 변경해요. 이제 태스크는 실행될 때 CURRENT_VERSION 함수를 쿼리해요:

ALTER TASK mytask MODIFY AS SELECT CURRENT_VERSION();

다음 예제는 태스크와 연결된 WHEN 조건을 수정해요. 트리거되면(스케줄 또는 선행 태스크가 성공적으로 실행된 후) 태스크는 이제 mystream 스트림에 데이터가 있을 때만 실행돼요:

ALTER TASK mytask MODIFY WHEN SYSTEM$STREAM_HAS_DATA('MYSTREAM');

새 또는 대체 기본 구성으로 기존 태스크를 업데이트하는 예제예요:

ALTER TASK task_with_config SET
      CONFIG=$${"output_directory": "/temp/prod_directory/", "environment": "prod"}$$;

기존 태스크에서 기본 구성을 제거하는 예제예요:

ALTER TASK task_with_config UNSET CONFIG;

더 알아보기 (Learn more)

CREATE TASK, DROP TASK, SHOW TASKS, DESCRIBE TASK