QUERY_HISTORY , QUERY_HISTORY_BY_*

QUERY_HISTORY , QUERY_HISTORY_BY_*

QUERY_HISTORY 계열의 표(table) 함수를 사용하면 다양한 차원을 따라 Snowflake 쿼리 히스토리를 조회할 수 있어요. 지정된 시간 범위, 세션, 사용자, 웨어하우스 단위로 실행된 쿼리를 가져올 수 있어요.

출처: Snowflake SQL Reference

본문

카테고리: Information Schema , Table 함수

QUERY_HISTORY 계열 표 함수로 다양한 차원을 따라 Snowflake 쿼리 히스토리를 조회할 수 있어요:

• QUERY_HISTORY는 지정된 시간 범위 안의 쿼리를 반환해요.
• QUERY_HISTORY_BY_SESSION은 지정된 세션과 시간 범위 안의 쿼리를 반환해요.
• QUERY_HISTORY_BY_USER는 지정된 사용자가 지정된 시간 범위 안에 제출한 쿼리를 반환해요.
• QUERY_HISTORY_BY_WAREHOUSE는 지정된 웨어하우스가 지정된 시간 범위 안에 실행한 쿼리를 반환해요.

각 함수는 지정된 차원을 따라 조회하도록 최적화되어 있어요. 결과는 SQL 조건자로 추가 필터링할 수 있어요.

구문 (Syntax)

QUERY_HISTORY(
      [ END_TIME_RANGE_START => <constant_expr> ]
      [, END_TIME_RANGE_END => <constant_expr> ]
      [, RESULT_LIMIT => <num> ]
      [, INCLUDE_CLIENT_GENERATED_STATEMENT => <boolean_expr> ] )

QUERY_HISTORY_BY_SESSION(
      [ SESSION_ID => <constant_expr> ]
      [, END_TIME_RANGE_START => <constant_expr> ]
      [, END_TIME_RANGE_END => <constant_expr> ]
      [, RESULT_LIMIT => <num> ]
      [, INCLUDE_CLIENT_GENERATED_STATEMENT => <boolean_expr> ] )

QUERY_HISTORY_BY_USER(
      [ USER_NAME => '<string>' ]
      [, END_TIME_RANGE_START => <constant_expr> ]
      [, END_TIME_RANGE_END => <constant_expr> ]
      [, RESULT_LIMIT => <num> ]
      [, INCLUDE_CLIENT_GENERATED_STATEMENT => <boolean_expr> ] )

QUERY_HISTORY_BY_WAREHOUSE(
      [ WAREHOUSE_NAME => '<string>' ]
      [, END_TIME_RANGE_START => <constant_expr> ]
      [, END_TIME_RANGE_END => <constant_expr> ]
      [, RESULT_LIMIT => <num> ]
      [, INCLUDE_CLIENT_GENERATED_STATEMENT => <boolean_expr> ] )

인자 (Arguments)

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

END_TIME_RANGE_START => <constant_expr>, END_TIME_RANGE_END => <constant_expr> — 쿼리 실행이 완료된, 최근 7일 안의 시간 범위(TIMESTAMP_LTZ 형식)예요:

• END_TIME_RANGE_END를 지정하지 않으면 실행 중인 쿼리를 포함한 모든 쿼리를 반환해요.
• END_TIME_RANGE_END가 CURRENT_TIMESTAMP면 완료된 쿼리만 반환해요.

시간 범위가 최근 7일 안에 있지 않으면 오류가 반환돼요.

참고: 시작 또는 종료 시간을 지정하지 않으면 지정된 한도까지 가장 최근 쿼리가 반환돼요.

SESSION_ID => <constant_expr> — QUERY_HISTORY_BY_SESSION에만 적용돼요. 세션에 대한 숫자 식별자 또는 CURRENT_SESSION이에요. 지정된 세션의 쿼리만 반환돼요. 기본값: CURRENT_SESSION

USER_NAME => '<string>' — QUERY_HISTORY_BY_USER에만 적용돼요. 사용자 로그인 이름 또는 CURRENT_USER를 지정하는 문자열이에요. 지정된 사용자가 실행한 쿼리만 반환돼요. 로그인 이름은 작은따옴표로 감싸야 해요. 로그인 이름에 공백·혼합 대소문자·특수 문자가 있으면 이름을 작은따옴표 안에서 큰따옴표로 감싸야 해요(예: '"User 1"' vs 'user1'). SYSTEM(USER_NAME =>'SYSTEM')은 사용자가 아닌 백그라운드 서비스이므로 지정할 수 없어요. 하지만 QUERY_HISTORY 표 함수에 대해 쿼리를 실행할 때 user_name='SYSTEM'으로 필터링할 수는 있어요. 기본값: CURRENT_USER

WAREHOUSE_NAME => '<string>' — QUERY_HISTORY_BY_WAREHOUSE에만 적용돼요. 웨어하우스 이름 또는 CURRENT_WAREHOUSE를 지정하는 문자열이에요. 해당 웨어하우스가 실행한 쿼리만 반환돼요. 웨어하우스 이름은 작은따옴표로 감싸야 해요. 이름에 공백·혼합 대소문자·특수 문자가 있으면 이름을 작은따옴표 안에서 큰따옴표로 감싸야 해요(예: '"My Warehouse"' vs 'mywarehouse'). 기본값: CURRENT_WAREHOUSE

RESULT_LIMIT => <num> — 함수가 반환하는 최대 행 수를 지정하는 숫자예요. 일치하는 행 수가 이 한도를 넘으면 가장 최근 종료 시각의 쿼리(또는 실행 중인 쿼리)가 지정된 한도까지 반환돼요. 범위: 1~10000. 기본값: 100.

참고: QUERY_HISTORY 표 함수에서 선택할 때 시간 범위와 RESULT_LIMIT 인자가 먼저 적용된 뒤 WHERE 절이 적용돼요. 더 넓은 범위의 쿼리에 필터를 적용하려면 RESULT_LIMIT 값을 늘려요.

INCLUDE_CLIENT_GENERATED_STATEMENT => <boolean_expr> — 클라이언트 생성 문장이 표 함수 쿼리에 포함되는지 여부를 지정해요(is_client_generated_statement 열의 값을 기준으로). 기본값: FALSE.

ACCOUNT_USAGE QUERY_HISTORY 뷰에도 is_client_generated_statement 열이 있지만, 이 뷰의 쿼리는 클라이언트 생성 여부와 관계없이 모든 문장을 반환해요. 필요한 경우 쿼리 결과를 필터링할 수 있어요.

사용 시 유의사항 (Usage notes)

• 현재 사용자가 실행한 쿼리를 반환해요. 실행 역할 또는 계층에서 더 높은 역할이 다음 권한 중 하나를 가질 때는 임의 사용자가 실행한 쿼리도 반환해요:

  • 쿼리가 실행된 사용자 관리 웨어하우스에 대한 MONITOR 또는 OPERATE 권한.
  • 작업에 대한 MONITOR 또는 OPERATE 권한. 예외: 작업이 owner's right 저장 프로시저나 UDF를 실행하면, 역할은 해당 작업이 실행된 웨어하우스에 대한 MONITOR 권한 이상을 가져야 저장 프로시저 쿼리와 UDF 쿼리를 볼 수 있어요.
  • 작업이 있는 계정에 대한 MONITOR EXECUTION 권한.
  • 예외: 저장 프로시저와 사용자 정의 함수(UDF) 모두 이 쿼리를 실행할 수 없어요.

  자세한 내용은 가상 웨어하우스 권한을 참고해요.

• Information Schema 표 함수를 호출할 때 세션은 INFORMATION_SCHEMA를 사용하거나 함수 이름을 정규화해야 해요. 자세한 내용은 Snowflake Information Schema를 참고해요.

• external_function_total_invocations, external_function_total_sent_rows, external_function_total_received_rows, external_function_total_sent_bytes, external_function_total_received_bytes 열의 값은 다음을 포함한 여러 요인의 영향을 받아요: SQL 문장의 외부 함수 수, 각 원격 서비스로 보내진 배치당 행 수, 일시적 오류(예: 예상 시간 내 응답을 받지 못함)로 인한 재시도 횟수.

• 취소된 쿼리는 execution_status 값이 아니라 error_message 텍스트(SQL execution canceled)로 식별돼요.

• QUERY_HISTORY 표 함수에서 선택할 때 함수 인자(시간 범위, RESULT_LIMIT)가 먼저 적용되어 행을 가져온 뒤, 쿼리의 WHERE와 LIMIT 절이 적용돼요. 예를 들어 RESULT_LIMIT이 100(기본값)으로 설정되면 WHERE 절은 가장 최근 100개 쿼리에만 적용돼요. 필터링 전에 더 넓은 범위의 쿼리를 검색하려면 RESULT_LIMIT 값을 늘려요.

쿼리 재시도 열 (Query retry columns)

쿼리는 성공적으로 완료되기 위해 한 번 이상 재시도되어야 할 수 있어요. 쿼리 재시도를 초래하는 원인은 여러 가지일 수 있어요. 그 중 일부는 조치 가능(actionable)한 것으로, 사용자가 특정 쿼리의 재시도를 줄이거나 없애기 위해 변경할 수 있어요. 예를 들어 쿼리가 메모리 부족 오류로 재시도된다면 웨어하우스 설정을 수정하면 해결될 수 있어요.

일부 쿼리 재시도는 조치 불가능한 결함으로 인해 발생해요. 즉 사용자가 재시도를 막기 위해 변경할 수 있는 것이 없어요. 예를 들어 네트워크 중단으로 쿼리 재시도가 발생할 수 있어요. 이 경우 쿼리나 실행 웨어하우스에 재시도를 막을 수 있는 변경이 없어요.

QUERY_RETRY_TIME, QUERY_RETRY_CAUSE, FAULT_HANDLING_TIME 열은 재시도되는 쿼리를 최적화하고 쿼리 성능 변동을 더 잘 이해하는 데 도움을 줘요.

출력 (Output)

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

query_type 열의 가능한 값은 다음을 포함해요:

• CREATE_USER
• CREATE_ROLE
• CREATE_NETWORK_POLICY
• ALTER_ROLE
• ALTER_NETWORK_POLICY
• ALTER_ACCOUNT
• DROP_SEQUENCE
• DROP_USER
• DROP_ROLE
• DROP_NETWORK_POLICY
• RENAME_NETWORK_POLICY
• REVOKE

예시 (Examples)

현재 세션에서 실행된 최근 최대 100개 쿼리를 가져와요:

SELECT *
  FROM TABLE(INFORMATION_SCHEMA.QUERY_HISTORY_BY_SESSION())
  ORDER BY start_time;

현재 사용자가 실행한(또는 현재 사용자가 MONITOR 권한을 가진 웨어하우스에서 임의 사용자가 실행한) 최근 최대 100개 쿼리를 가져와요:

SELECT *
  FROM TABLE(INFORMATION_SCHEMA.QUERY_HISTORY())
  ORDER BY start_time;

현재 사용자가 지난 1시간 안에 실행한(또는 현재 사용자가 MONITOR 권한을 가진 웨어하우스에서 임의 사용자가 실행한) 최근 최대 100개 쿼리를 가져와요:

SELECT *
  FROM TABLE(INFORMATION_SCHEMA.QUERY_HISTORY(DATEADD('hours',-1,CURRENT_TIMESTAMP()),CURRENT_TIMESTAMP()))
  ORDER BY start_time;

현재 사용자가 실행한(또는 현재 사용자가 MONITOR 권한을 가진 웨어하우스에서 임의 사용자가 실행한) 지난 7일 안의 지정된 30분 블록 안의 모든 쿼리를 가져와요:

SELECT *
  FROM TABLE(INFORMATION_SCHEMA.QUERY_HISTORY(
    END_TIME_RANGE_START=>TO_TIMESTAMP_LTZ('2017-12-4 12:00:00.000 -0700'),
    END_TIME_RANGE_END=>TO_TIMESTAMP_LTZ('2017-12-4 12:30:00.000 -0700')));

my_xsmall_wh라는 웨어하우스에 대해 실행된 클라이언트 생성 문장 수를 가져와요:

SELECT COUNT(*)
  FROM TABLE(INFORMATION_SCHEMA.QUERY_HISTORY_BY_WAREHOUSE(
    WAREHOUSE_NAME => 'my_xsmall_wh',
    INCLUDE_CLIENT_GENERATED_STATEMENT => TRUE));

더 알아보기

• QUERY_HISTORY 뷰 (Account Usage)
• Query History로 쿼리 활동 모니터링 (Snowsight 대시보드)