TASK_HISTORY

TASK_HISTORY (태스크 이력)

이 테이블 함수를 사용해 지정된 날짜 범위 내의 태스크 사용 이력을 조회할 수 있어요. 함수는 전체 Snowflake 계정, 지정된 태스크, 또는 태스크 그래프의 태스크 사용 이력을 반환해요.

이 함수는 지난 7일 동안 실행된 모든 실행 또는 향후 8일 이내의 다음 예약 실행을 반환할 수 있어요.

출처: Snowflake SQL Reference - TASK_HISTORY

본문

구문

TASK_HISTORY(
      [ SCHEDULED_TIME_RANGE_START => <constant_expr> ]
      [, SCHEDULED_TIME_RANGE_END => <constant_expr> ]
      [, RESULT_LIMIT => <integer> ]
      [, TASK_NAME => '<string>' ]
      [, DATABASE_NAME => '<string>' ]
      [, SCHEMA_NAME => '<string>' ]
      [, ERROR_ONLY => { TRUE | FALSE } ]
      [, ROOT_TASK_ID => '<string>' ]
)

인자

모든 인자는 선택적이에요.

SCHEDULED_TIME_RANGE_START => <constant_expr>, SCHEDULED_TIME_RANGE_END => <constant_expr>

지난 7일 이내의, 태스크 실행이 예약된 시간 범위(TIMESTAMP_LTZ 형식)예요. 시간 범위가 지난 7일 이내에 속하지 않으면 오류가 반환돼요.

• SCHEDULED_TIME_RANGE_END를 지정하지 않으면 함수는 이미 완료되었거나 현재 실행 중이거나 향후 예약된 태스크를 반환해요.
• SCHEDULED_TIME_RANGE_END가 CURRENT_TIMESTAMP이면 함수는 이미 완료되었거나 현재 실행 중인 태스크를 반환해요. 현재 시간 직전에 실행된 태스크는 여전히 예약된 것으로 식별될 수 있다는 점에 유의해요.
• 이미 완료되었거나 현재 실행 중인 태스크만 조회하려면 필터로 WHERE query_id IS NOT NULL을 포함해요. TASK_HISTORY 출력의 QUERY_ID 열은 태스크가 실행을 시작했을 때만 채워져요.

참고: 시작 또는 종료 시간을 지정하지 않으면 지정된 RESULT_LIMIT 값까지 가장 최근 태스크가 반환돼요.

RESULT_LIMIT =>

함수가 반환하는 최대 행 수를 지정하는 숫자예요.

일치하는 행 수가 이 한도를 초과하면 가장 최근 타임스탬프의 태스크 실행이 지정된 한도까지 반환돼요.

범위: 1 ~ 10000

기본값: 100.

TASK_NAME =>

태스크를 지정하는 대소문자 구분 없는 문자열이에요. 한정되지 않은 태스크 이름만 지원돼요. 지정된 태스크의 실행만 반환돼요. 여러 태스크가 같은 이름을 가지면 함수는 이러한 각 태스크의 이력을 반환한다는 점에 유의해요.

DATABASE_NAME =>

태스크를 필터링할 데이터베이스를 지정하는 문자열이에요. 역할이 데이터베이스에 대한 USAGE 권한이 있어야 한다는 점에 유의해요. 대소문자를 구분해 일치시키려면 문자열 안에 큰따옴표를 사용해요.

SCHEMA_NAME =>

태스크를 필터링할 스키마를 지정하는 문자열이에요. 이 인자를 제공하면 DATABASE_NAME도 지정해야 해요. 역할이 스키마와 데이터베이스에 대한 USAGE 권한이 있어야 한다는 점에 유의해요. 대소문자를 구분해 일치시키려면 문자열 안에 큰따옴표를 사용해요.

ERROR_ONLY => { TRUE | FALSE }

TRUE로 설정되면 함수는 실패했거나 취소된 태스크 실행만 반환해요.

기본값: FALSE.

ROOT_TASK_ID =>

태스크 그래프에서 루트 태스크의 고유 식별자예요. 이 ID는 같은 태스크에 대한 SHOW TASKS 출력의 ID 열 값과 일치해요. ROOT_TASK_ID를 지정해 루트 태스크와 태스크 그래프의 일부인 모든 하위 태스크의 이력을 보여줘요.

사용상 주의사항

• 가능할 때마다 DATABASE_NAME, SCHEMA_NAME, TASK_NAME 같은 함수 인자를 사용해 결과를 필터링해요. 이러한 필터는 RESULT_LIMIT(기본값: 100행)보다 먼저 적용되므로, 사용하는 것이 WHERE 절로 잠재적으로 잘린 결과 집합을 필터링하는 것보다 가장 관련성 높은 결과를 얻는 데 보장돼요.
• SCHEMA_NAME을 제공하면 이를 한정하기 위해 DATABASE_NAME도 제공해야 해요.
• 이 함수 내에서 태스크 그래프를 보려면 호출 역할은 다음 권한 중 적어도 하나가 필요해요: 태스크에 대한 OWNERSHIP 권한(즉, 태스크 소유자), 태스크에 대한 MONITOR 또는 OPERATE 권한, 전역 MONITOR EXECUTION 권한, ACCOUNTADMIN 역할. 또한 역할은 태스크를 저장하는 데이터베이스와 스키마에 대한 USAGE 권한이 있어야 하며, 그렇지 않으면 출력의 DATABASE_NAME과 SCHEMA_NAME 값은 NULL이에요.
• 이 함수는 RESULT_LIMIT 인자 값에 설정된 최대 10,000행을 반환해요. 기본값은 100이에요. 이 제한을 피하려면 TASK_HISTORY 뷰(Account Usage)를 사용해요.
• TASK_HISTORY 함수를 조회하면 해당 태스크 이름, 시간 범위, 결과 한도 인자가 먼저 적용된 다음 각각 WHERE 및 LIMIT 절이 적용된다는 점에 유의해요. 또한 TASK_HISTORY 함수는 SCHEDULED_TIME 내림차순으로 레코드를 반환해요. SUCCEEDED, FAILED, CANCELLED 상태의 태스크는 일반적으로 더 일찍 예약되므로 일반적으로 검색 결과에서 더 늦게 반환돼요.
• 실제로 계정에서 실행 중인 태스크가 많으면 함수가 반환하는 결과에 완료된 태스크가 예상보다 적을 수 있거나 예약된 태스크만 포함될 수 있어요. 이미 실행된 태스크의 이력을 조회하려면 SCHEDULED_TIME_RANGE_START => constant_expr과 SCHEDULED_TIME_RANGE_END => constant_expr 인자를 조합해 사용해요.
• 정보 스키마 테이블 함수를 호출할 때 세션은 INFORMATION_SCHEMA 스키마를 사용 중이거나 함수 이름이 완전히 한정되어야 해요. 자세한 내용은 Snowflake Information Schema를 참고해요.
• 클라우드 서비스 장애 중에 실행된 태스크는 이 함수의 결과에 중복 항목으로 나타날 수 있어요. 클라우드 서비스 장애 중에 Snowflake는 태스크를 다시 실행할 수 있으며, 이로 인해 태스크에 서로 다른 SCHEDULED_TIME을 가진 두 개의 UUID가 생길 수 있어요. TASK_HISTORY 뷰는 다시 실행된 태스크의 최종 UUID만 표시해요.
• 태스크 그래프 실행의 모든 태스크는 같은 태스크 이력 출력을 보여줘요.

출력

이 함수는 다음 열을 반환해요:

QUERY_ID	TEXT	태스크가 실행한 SQL 문의 ID. 문 또는 저장 프로시저의 실행에 대한 추가 세부 정보를 위해 QUERY_HISTORY 뷰와 조인할 수 있음.
NAME	TEXT	태스크의 이름.
DATABASE_NAME	TEXT	태스크를 포함하는 데이터베이스의 이름.
SCHEMA_NAME	TEXT	태스크를 포함하는 스키마의 이름.
QUERY_TEXT	TEXT	SQL 문의 텍스트.
CONDITION_TEXT	TEXT	실행 여부를 결정할 때 태스크가 평가하는 WHEN 조건의 텍스트.
STATE	TEXT	태스크의 상태: SCHEDULED(실행 예약됨), EXECUTING(현재 실행 중), SUCCEEDED(실행 성공), FAILED(실행 실패 — 시간 초과된 태스크는 항상 태스크 이력에서 FAILED 상태를 가짐), FAILED_AND_AUTO_SUSPENDED(태스크 실패 및 자동 일시 중단됨), CANCELLED(실행 취소됨), SKIPPED(태스크 실행이 시작되었지만 태스크 정의의 선택적 WHEN 파라미터가 FALSE 값을 반환하여 실행이 웨어하우스를 재개하지 않거나(태스크가 고객 관리 컴퓨팅 리소스를 사용하는 경우) 태스크 정의의 SQL 코드를 실행하지 않음을 나타냄).
ERROR_CODE	NUMBER	문이 오류를 반환한 경우 오류 코드.
ERROR_MESSAGE	TEXT	문이 오류를 반환한 경우 오류 메시지.
SCHEDULED_TIME	TIMESTAMP_LTZ	태스크가 실행을 시작하도록 예약된 시간. 태스크는 실행을 시작하기 전에 짧은 대기 기간으로 시작함. 자세한 내용은 Task duration 참고.
QUERY_START_TIME	TIMESTAMP_LTZ	태스크 정의의 쿼리가 실행을 시작한 시간, 또는 SCHEDULED_TIME이 미래이거나 현재 예약된 실행이 아직 시작되지 않았으면 NULL. 이 타임스탬프는 QUERY_HISTORY가 반환한 쿼리의 시작 시간과 일치함.
NEXT_SCHEDULED_TIME	TIMESTAMP_LTZ	독립형 또는 루트 태스크가(태스크 그래프에서) 다음 실행을 시작하도록 예약된 시간. 단, 독립형 태스크 또는 태스크 그래프의 현재 실행이 SCHEDULED_TIME 시간에 시작되어 제시간에 완료된다고 가정함.
COMPLETED_TIME	TIMESTAMP_LTZ	태스크가 완료된 시간, 또는 SCHEDULED_TIME이 미래이거나 태스크가 여전히 실행 중이면 NULL.
ROOT_TASK_ID	TEXT	태스크 그래프에서 루트 태스크의 고유 식별자. 이 ID는 같은 태스크에 대한 SHOW TASKS 출력의 ID 열 값과 일치함.
GRAPH_VERSION	NUMBER	실행되었거나 실행되도록 예약된 태스크 그래프의 버전을 식별하는 정수. 값이 증가할 때마다 태스크 그래프의 태스크에 대한 하나 이상의 수정을 나타냄. 루트 태스크가 재생성되면(CREATE OR REPLACE TASK 사용) 버전 번호는 1부터 다시 시작됨.
RUN_ID	NUMBER	태스크 그래프의 독립형 또는 루트 태스크가 원래 실행을 시작하도록 예약된 시간. 형식은 epoch 시간(밀리초)임. 원래 예약 시간은 시스템이 같은 태스크를 다시 실행하거나 부하를 재분배하기 위해 다른 시간에 실행하도록 재예약할 수 있는 드문 경우를 말함. 그런 경우 RUN_ID는 원래 예약된 실행 시간을, SCHEDULED_TIME은 재예약된 실행 시간을 표시함. RUN_ID는 재시도 전의 현재 태스크/그래프 실행에 대한 고유 식별자가 아닐 수 있음. GRAPH_RUN_GROUP_ID 열을 RUN_ID 대신 사용할 수 있음.
RETURN_VALUE	TEXT	태스크 그래프에서 선행 태스크에 대해 설정된 값. 반환 값은 선행 태스크가 System_Set_Return_Value 함수를 호출해 명시적으로 설정함.
SCHEDULED_FROM	TEXT	다음 중 하나: SCHEDULE(CREATE TASK의 SCHEDULE 또는 AFTER 절에 설명된 대로 태스크가 정상적으로 실행되도록 예약됨), EXECUTE_TASK(태스크가 EXECUTE TASK로 실행되도록 예약됨), MANUAL RETRY(태스크가 EXECUTE TASK … RETRY LAST로 실행되도록 예약됨), AUTOMATIC RETRY(태스크가 실패 시 재시도하도록 구성되었고 이전 실행이 실패함), TRIGGER(태스크의 WHEN 절의 스트림에 새 데이터가 있어 태스크가 실행됨). 태스크 그래프의 하위 태스크 실행의 경우 이 열은 루트 태스크 실행과 같은 값을 반환함.
ATTEMPT_NUMBER	NUMBER	이 태스크 실행 시도 횟수를 나타내는 정수. 처음에는 1.
CONFIG	TEXT	태스크 실행이 사용한 구성. EXECUTE TASK … USING CONFIG로 지정된 동적 구성을 포함함. 구성이 설정되지 않으면 열은 NULL을 표시함.
QUERY_HASH	TEXT	정규화된 SQL 텍스트를 기반으로 계산된 해시 값.
QUERY_HASH_VERSION	NUMBER	QUERY_HASH를 계산하는 데 사용된 로직의 버전.
QUERY_PARAMETERIZED_HASH	TEXT	파라미터화된 쿼리를 기반으로 계산된 해시 값.
QUERY_PARAMETERIZED_HASH_VERSION	NUMBER	QUERY_PARAMETERIZED_HASH를 계산하는 데 사용된 로직의 버전.
GRAPH_RUN_GROUP_ID	TEXT	그래프 실행의 식별자. 그래프 실행에 여러 태스크 실행이 있으면 각 태스크 실행은 같은 GRAPH_RUN_GROUP_ID를 표시함. GRAPH_RUN_GROUP_ID와 ATTEMPT_NUMBER의 조합을 사용해 그래프 실행을 고유하게 식별할 수 있음.
BACKFILL_INFO	OBJECT	향후 사용을 위해 예약됨. 모든 행의 반환 값은 NULL.
SPCS_JOB_ID	NUMBER	이 태스크 실행과 연결된 Snowpark Container Services(SPCS) 작업의 ID. 태스크가 컨테이너 작업으로 실행되지 않았으면 NULL.

예시

계정의 가장 최근 100개 태스크 실행(완료, 아직 실행 중, or 향후 예약)을 검색해요. 함수가 반환하는 최대 행 수는 기본적으로 100으로 제한된다는 점에 유의해요:

SELECT *
  FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.TASK_HISTORY())
  ORDER BY SCHEDULED_TIME;

특정 7일 기간 내의 지정된 30분 시간 블록에 계정의 태스크에 대한 실행 이력을 검색해요:

SELECT *
  FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.TASK_HISTORY(
    SCHEDULED_TIME_RANGE_START=>TO_TIMESTAMP_LTZ('2024-11-9 12:00:00.000 -0700'),
    SCHEDULED_TIME_RANGE_END=>TO_TIMESTAMP_LTZ('2024-11-9 12:30:00.000 -0700')));

지난 1시간 이내에 예약된 지정된 태스크의 가장 최근 10개 실행(완료, 아직 실행 중, or 향후 예약)을 검색해요:

SELECT *
  FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.TASK_HISTORY(
    SCHEDULED_TIME_RANGE_START=>DATEADD('hour',-1,current_timestamp()),
    RESULT_LIMIT => 10,
    TASK_NAME=>'mytask'));

참고: 완료되었거나 아직 실행 중인 태스크만 검색하려면 WHERE query_id IS NOT NULL을 사용해 쿼리를 필터링해요. 이 필터는 RESULT_LIMIT가 이미 반환된 결과를 줄인 후에 적용되므로, 태스크 1개가 예약되었지만 아직 시작되지 않았다면 쿼리가 9개 태스크를 반환할 수 있다는 점에 유의해요.

지정된 루트 태스크의 태스크 그래프에 있는 모든 태스크의 실행 이력을 검색해요.

SELECT *
  FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.TASK_HISTORY(
    ROOT_TASK_ID=>'d4b89013-c942-465c-bcb8-e7037a932b04'));

가장 최근에 조회된 루트 태스크의 태스크 그래프에 있는 모든 태스크의 실행 이력을 검색해요:

DESC TASK my_task
SET task_id=(SELECT "id" FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())));

SELECT *
  FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.TASK_HISTORY(
    ROOT_TASK_ID=>$task_id));

지정된 데이터베이스(대소문자 구분 없음)의 태스크에 대한 실행 이력을 검색해요:

SELECT *
  FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.TASK_HISTORY(
    DATABASE_NAME => 'MY_DATABASE'));

해당 데이터베이스 내의 지정된 스키마(둘 다 대소문자 구분 없음)의 태스크에 대한 실행 이력을 검색해요:

SELECT *
  FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.TASK_HISTORY(
    DATABASE_NAME => 'MY_DATABASE',
    SCHEMA_NAME => 'MY_SCHEMA'));

큰따옴표를 사용해 데이터베이스와 스키마 이름을 대소문자 구분해 일치시켜요:

SELECT *
  FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.TASK_HISTORY(
    DATABASE_NAME => '"my_db"',
    SCHEMA_NAME => '"my_schema"'));

더 알아보기

• Information Schema — 정보 스키마
• TASK_HISTORY 뷰 (Account Usage) — 계정 사용량 이력 뷰