SYSTEM$AUTO_REFRESH_STATUS

SYSTEM$AUTO_REFRESH_STATUS는 외부 관리 Iceberg 테이블의 자동 새로고침(refresh) 상태를 반환하는 시스템 함수예요. 접근 권한이 있는 모든 외부 관리 Apache Iceberg™ 테이블의 새로고침 상태를 한 번에 확인하려면 SHOW ICEBERG TABLES 명령을 실행하고 출력의 auto_refresh_status 열을 보면 돼요.

출처: Snowflake SQL Reference

본문

구문 (Syntax)

SYSTEM$AUTO_REFRESH_STATUS('<table_name>')

인자 (Arguments)

'<table_name>' — 현재 자동 새로고침 상태를 가져올 Iceberg 테이블의 이름이에요.

정규화된 이름(fully qualified name)을 사용한다면 데이터베이스와 스키마를 포함해 전체 이름을 작은따옴표로 감싸요. 테이블 이름이 대소문자를 구분하거나 특수 문자·공백을 포함한다면 큰따옴표를 사용해야 해요. 큰따옴표는 작은따옴표 안에 둘러싸 주세요. 예: '\"Table_Name\"'

반환값 (Returns)

이 함수는 다음 이름/값 쌍을 담은 JSON 객체를 반환해요:

{
  "executionState":"<value>",
  "invalidExecutionStateReason":"<value>",
  "pendingSnapshotCount":"<value>",
  "oldestSnapshotTime":"<value>",
  "currentSnapshotId":"<value>",
  "currentSnapshotSummary":"<value>",
  "lastSnapshotTime":"<value>",
  "lastUpdatedTime":"<value>",
  "currentMetadataFile":"<value>",
  "currentSchemaId":"<value>"
}

여기서:

executionState — Snowflake가 테이블의 메타데이터 새로고침을 자동화하는 데 사용하는 파이프의 현재 실행 상태예요. 값은 다음과 같아요:

RUNNING: 자동 새로고침이 정상적으로 실행 중이에요. 이 상태가 Snowflake가 파이프의 이벤트 메시지를 실제로 처리 중인지 여부를 뜻하지는 않아요.
STALLED: 자동 새로고침이 오류를 만나 복구를 시도 중이에요.
STOPPED: 자동 새로고침이 복구 불가능한 오류를 만나, 추가 조치를 취하지 않으면 중지된 상태예요. 자세한 내용은 오류 복구를 참고해요.
ICEBERG_TABLE_NOT_INITIALIZED: Snowflake가 테이블을 만들 때 오류가 발생해 자동 새로고침이 초기화되지 않았어요. 자동 새로고침을 실행하려면 오류를 해결한 뒤 테이블에 자동 새로고침을 활성화해야 해요. 이 실행 상태는 카탈로그 연결 데이터베이스에 있는 테이블에서만 발생해요.

invalidExecutionStateReason — STALLED 또는 STOPPED 실행 상태와 연결된 오류 메시지예요.

pendingSnapshotCount — 자동 새로고침을 위해 대기열에 올라간 스냅샷 수예요.

oldestSnapshotTime — 대기열에 있는 스냅샷 중 가장 이른 타임스탬프예요. Snowflake는 스냅샷이 대기열에 추가될 때 그 스냅샷의 타임스탬프를 설정해요.

currentSnapshotId — Snowflake가 추적 중인 현재 스냅샷의 ID예요. 현재 테이블 데이터가 대응하는 스냅샷을 나타내요.

currentSnapshotSummary — metadata.json 파일의 Iceberg 스냅샷 요약이에요. 메타데이터 파일에 없다면 NULL이에요.

lastSnapshotTime — Iceberg 메타데이터 기준 현재 스냅샷의 생성 타임스탬프예요. 외부 카탈로그에서 현재 스냅샷이 생성된 시점을 나타내요.

lastUpdatedTime — Snowflake가 현재 스냅샷을 성공적으로 처리한 시점을 나타내는 타임스탬프예요. 이 값과 lastSnapshotTime의 차이는 외부 카탈로그에서 스냅샷이 생성된 시점과 Snowflake가 테이블 메타데이터를 성공적으로 새로고침한 시점 사이의 지연(latency)을 나타내요.

지연을 줄이려면 테이블과 연결된 카탈로그 통합의 REFRESH_INTERVAL_SECONDS 파라미터를 조정해요.

currentMetadataFile — 현재 메타데이터 파일의 전체 경로예요.

currentSchemaId — 현재 스키마의 ID예요.

사용 시 유의사항 (Usage notes)

이 함수를 호출하려면 Iceberg 테이블에 대한 OWNERSHIP 권한을 가진 역할이 필요해요.
Delta 기반 테이블의 경우 다음을 유의해요:
- 이 함수와 Snowflake의 자동 새로고침 맥락에서 "스냅샷(snapshot)"은 Delta 커밋을 가리켜요.
- 이 함수는 lastSnapshotTime에 대한 값을 반환하지 않아요.

예시 (Examples)

스키마 db1.schema1에 있는 테이블 my_iceberg_table의 자동 새로고침 상태를 가져와요:

SELECT SYSTEM$AUTO_REFRESH_STATUS('db1.schema1.my_iceberg_table');

SYSTEM$AUTO_REFRESH_STATUS