ALTER PIPE

ALTER PIPE

기존 파이프(pipe) 객체의 제한된 속성 집합을 수정하는 명령이에요. 또한 다음 작업도 지원해요:

  • 파이프 일시 중지(pause).
  • 파이프 새로고침(refresh) — 지정된 스테이징 데이터 파일을 대상 테이블로 로드하기 위해 Snowpipe 수집 큐에 복사.
  • 파이프 주석 추가/덮어쓰기/제거.
  • 파이프 태그 설정/해제.

출처: 문서

본문

관련 명령: CREATE PIPE, DROP PIPE, SHOW PIPES, DESCRIBE PIPE

구문 (Syntax)

ALTER PIPE [ IF EXISTS ] <name> SET { [ objectProperties ]
                                      [ COMMENT = '<string_literal>' ] }

ALTER PIPE <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER PIPE <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

ALTER PIPE [ IF EXISTS ] <name> UNSET { <property_name> | COMMENT } [ , ... ]

ALTER PIPE [ IF EXISTS ] <name> REFRESH { [ PREFIX = '<path>' ] [ MODIFIED_AFTER = <start_time> ] }

여기서:

objectProperties ::=
  PIPE_EXECUTION_PAUSED = TRUE | FALSE

매개변수 (Parameters)

name — 수정할 파이프의 식별자를 지정해요. 식별자에 공백이나 특수 문자가 포함되어 있으면 전체 문자열을 큰따옴표로 묶어야 해요. 큰따옴표로 묶은 식별자는 대소문자를 구분해요.

SET ... — 공백, 콤마 또는 줄바꿈으로 구분해 파이프에 설정할 하나 이상의 속성을 지정해요.

ERROR_INTEGRATION = 'integration_name' — Snowpipe가 클라우드 메시징 서비스에 오류 알림을 보내도록 구성할 때만 필요해요. 메시징 서비스와 통신하는 데 사용하는 알림 통합(notification integration)의 이름을 지정해요. 자세한 내용은 Snowpipe 오류 알림을 참고하세요.

PIPE_EXECUTION_PAUSED = TRUE | FALSE — 실행 중인 파이프를 일시 중지할지(보통 파이프 소유권 이전 준비를 위해) 지정해요:

  • TRUE는 파이프를 일시 중지해요. SYSTEM$PIPE_STATUS가 보고하는 executionState는 PAUSED예요. 파이프 소유자는 일시 중지된 파이프에도 계속 파일을 제출할 수 있지만, 파이프가 재개되기 전까지는 처리되지 않아요.
  • FALSE는 파이프를 재개해요. SYSTEM$PIPE_STATUS가 보고하는 executionState는 RUNNING이에요.

참고: 다음 두 시나리오 중 하나는 SYSTEM$PIPE_FORCE_RESUME 함수를 호출해 파이프를 강제로 재개해야 해요:

  • 파이프 소유권을 다른 역할로 이전. 이 요구사항은 새 소유자가 SYSTEM$PIPE_STATUS 함수를 호출해 파이프 상태와 로드 대기 중인 파일 수를 평가할 수 있게 해줘요.
  • 클라우드 스토리지 계정에 대량의 스테이징 파일이 있는 경우. (전문가 검토에 따라)

REFRESH — 파이프 정의에 지정된 스테이지에서 준비된 데이터 파일을 Snowpipe 수집 큐로 복사해 대상 테이블에 로드해요.

참고

  • 이 SQL 명령은 지난 7일 이내에 스테이징된 데이터 파일만 로드할 수 있어요.
  • 이 명령은 파이프와 대상 테이블 모두의 로드 이력을 확인해요. 결과적으로 다음 두 방법 중 하나로 아직 로드되지 않은 파일만 큐에 넣어요:
    • 파일이 로드된 후 파이프 소유자가 파이프를 다시 만들지 않은 경우 같은 파이프 사용.
    • COPY INTO <table> 문 사용.

중요: REFRESH 기능은 Snowpipe가 파일 하위 집합을 로드하지 못할 때 특정 문제를 해결하기 위한 단기 사용용으로, 정기적인 사용용이 아니에요.

PREFIX = 'path' — 파이프 정의의 스테이지 참조에 추가되는 경로(또는 접두사). 이 경로는 로드할 파일 집합을 제한해요. 지정된 경로로 시작하는 파일만 데이터 로드에 포함돼요.

예를 들어 파이프 정의가 @mystage/path1/를 참조한다고 가정해요. path 값이 d1/이면 ALTER PIPE 문은 /path1/d1/ 경로의 @mystage 스테이지의 파일만 로드하도록 제한해요.

경로는 단일 따옴표로 묶어야 해요.

MODIFIED_AFTER = 'start_time' — LAST_MODIFIED 날짜(즉 파일이 스테이징된 날짜)를 기준으로 Snowpipe 수집 큐로 복사할 가장 오래된 데이터 파일의 타임스탬프(ISO-8601 형식)예요.

기본값이자 최대 허용값은 7일이에요.

사용 메모 (Usage notes)

  • 파이프 소유자(즉 파이프에 OWNERSHIP 권한이 있는 역할)만 파이프 속성을 설정하거나 해제할 수 있어요.

다음 최소 권한을 가진 비소유자 역할이 파이프를 새로고침할 수 있어요 (ALTER PIPE … REFRESH … 사용):

권한 객체 설명
OPERATE Pipe
USAGE 파이프 정의의 스테이지 외부 스테이지만
READ 파이프 정의의 스테이지 내부 스테이지만
SELECT, INSERT 파이프 정의의 테이블
파이프에 OPERATE 권한이 있는 비소유자 역할 ALTER PIPE … SET PIPE_EXECUTION_PAUSED = TRUE/FALSE로 파이프를 일시 중지/재개할 수 있어요.
스키마 객체에 대한 SQL 작업 객체를 포함한 데이터베이스와 스키마에 대한 USAGE 또는 기타 권한도 필요해요.

  • 현재 ALTER PIPE 문으로 다음 파이프 속성은 수정할 수 없어요:

    대신 CREATE OR REPLACE PIPE 문으로 파이프를 다시 만들어요.

  • 메타데이터 관련: Snowflake 서비스를 사용할 때 메타데이터로 개인 데이터(User 객체 외), 민감한 데이터, 수출 통제 데이터 또는 기타 규제 대상 데이터를 입력하지 않도록 주의해야 해요. 자세한 내용은 Snowflake의 메타데이터 필드를 참고하세요.

예시 (Examples)

mypipe 파이프를 일시 중지해요.

alter pipe mypipe SET PIPE_EXECUTION_PAUSED = true;

파이프 mypipe의 주석을 추가하거나 수정해요.

alter pipe mypipe SET COMMENT = "Pipe for North American sales data";

파이프 새로고침

예시를 위한 설정:

CREATE PIPE mypipe AS COPY INTO mytable FROM @mystage/path1/;

mypipe 파이프 정의에 정의된 대로 @mystage/path1/ 스테이지와 경로의 데이터 파일을 mytable 테이블로 로드해요.

ALTER PIPE mypipe REFRESH;

이전 예시와 같지만, 로드할 파일 목록을 더 제한하기 위해 경로에 d1을 추가해요. 이 예시에서는 @mystage/path1/d1/ 스테이지와 경로에서 파일을 로드해요.

ALTER PIPE mypipe REFRESH PREFIX='d1/';

이전 예시와 같지만, 지정된 타임스탬프 이후에 스테이징된 파일만 로드해요.

ALTER PIPE mypipe REFRESH PREFIX='d1/' MODIFIED_AFTER='2018-07-30T13:56:46-07:00';

더 알아보기 (Learn more)