PUT

PUT

로컬 파일 시스템에서 내부 스테이지로 하나 이상의 데이터 파일을 업로드하는 명령이에요. 내부 스테이지에 파일을 업로드한 후 COPY INTO <table> 명령으로 파일의 데이터를 테이블에 로드할 수 있어요.

출처: 문서

본문

참고:

  • PUT은 외부 스테이지로 파일을 업로드하는 것을 지원하지 않아요. 외부 스테이지에 파일을 업로드하려면 클라우드 서비스에서 제공하는 유틸리티를 사용해요.
  • Snowpark 저장 프로시저의 snowflake.snowpark.FileOperation.put은 외부 스테이지를 지원하며 정상 데이터 전송 요율로 청구돼요.
  • ODBC 드라이버는 다음 플랫폼에서 호스팅되는 Snowflake 계정으로 PUT을 지원해요: Amazon Web Services, Google Cloud, Microsoft Azure.

구문 (Syntax)

PUT file://<local_file_path> <internalStage>
    [ PARALLEL = <integer> ]
    [ AUTO_COMPRESS = TRUE | FALSE ]
    [ SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE ]
    [ OVERWRITE = TRUE | FALSE ]

여기서:

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>
  | @~[/<path>]
internalStage 설명
@[namespace.]int_stage_name[/path] 파일이 지정된 명명된 내부 스테이지에 업로드됨.
@[namespace.]%table_name[/path] 파일이 지정된 테이블의 스테이지에 업로드됨.
@~[/path] 파일이 현재 사용자의 스테이지에 업로드됨.

여기서:

  • <namespace>는 명명된 내부 스테이지나 테이블을 포함하는 데이터베이스 또는 스키마예요. 세션 내에서 데이터베이스와 스키마가 사용 중이면 선택 사항이에요.
  • <path>는 파일 집합에 대한 접근을 제한하는 클라우드 스토리지 위치의 파일에 대한 선택적 대소문자 구분 경로예요. 경로는 다른 클라우드 스토리지 서비스에서 prefix 또는 folder라고도 불러요.

스테이지 이름이나 경로에 공백이나 특수 문자가 포함되면 작은따옴표로 묶어요. 예를 들어 "my stage"라는 스테이지에는 '@"my stage"'를 사용해요.

선택 파라미터 (Optional parameters)

  • PARALLEL = integer — 파일 업로드에 사용할 스레드 수를 지정해요. Snowflake는 데이터 파일 배치를 크기별로 구분하여 업로드해요:

    • 64MB보다 작은 파일(압축 또는 비압축)은 개별 파일로 병렬 스테이징돼요.
    • 더 큰 파일은 자동으로 청크로 분할되어 동시에 스테이징되고 대상 스테이지에서 재조립돼요. 단일 스레드가 여러 청크를 업로드할 수 있어요. 스레드 수를 늘리면 큰 파일 업로드 성능이 향상될 수 있어요. 지원 값: 1(병렬 없음)부터 99(파일 업로드에 99 스레드 사용)까지의 모든 정수. 기본값: 4

    참고: 16MB 제한이 이전 버전의 Snowflake 드라이버에 적용돼요: JDBC Driver 3.12.1 이전, ODBC Driver 2.20.5 이전, Python Connector 2.2.0 이전.

  • AUTO_COMPRESS = TRUE | FALSE — Snowflake가 업로드 중에 gzip으로 파일을 압축할지 여부를 지정해요:

    • TRUE: Snowflake가 파일(이미 압축되지 않은 경우)을 압축해요.
    • FALSE: Snowflake가 파일을 압축하지 않아요. 이 옵션은 다른 압축 유형을 지원하지 않아요. 다른 압축 유형을 사용하려면 PUT 명령 실행 전에 파일을 별도로 압축해요. 그런 다음 SOURCE_COMPRESSION 옵션으로 압축 유형을 식별해요. 스테이징 전에 데이터 파일을 압축할 수 있도록 로컬 폴더에 충분한 공간이 있는지 확인해요. 필요한 경우 운영 체제의 TEMP, TMPDIR 또는 TMP 환경 변수를 추가 여유 공간이 있는 로컬 폴더를 가리키도록 설정해요. 기본값: TRUE

  • SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE — 스테이징되는 이미 압축된 파일에 사용된 압축 방법을 지정해요:

    Supported Values Notes
    AUTO_DETECT 압축 알고리즘이 자동으로 감지되지만, Brotli 압축 파일은 현재 자동 감지할 수 없어요. Brotli 압축 파일을 업로드 중이면 AUTO_DETECT 대신 BROTLI를 명시적으로 사용해요.
    GZIP *.tar.gz 파일 형식을 지원하지 않아요.
    BZ2 *.tar.bz2 파일 형식을 지원하지 않아요.
    BROTLI Brotli 압축 파일을 업로드하면 반드시 사용해야 해요.
    ZSTD Zstandard v0.8(및 그 이상) 지원.
    DEFLATE Deflate 압축 파일(zlib 헤더 포함, RFC1950).
    RAW_DEFLATE Raw Deflate 압축 파일(헤더 없음, RFC1951).
    NONE 데이터 파일이 압축되지 않았음.

    기본값: AUTO_DETECT. Snowflake는 이 옵션을 사용하여 데이터 파일이 어떻게 압축되었는지 감지해 파일을 압축 해제하고 업로드를 위해 데이터를 추출해요. 이 옵션으로 파일을 압축하지는 않아요. 다른 유틸리티로 압축된 파일 로딩은 현재 지원되지 않아요.

  • OVERWRITE = TRUE | FALSE — 업로드 중 Snowflake가 같은 이름의 기존 파일을 덮어쓸지 여부를 지정해요:

    • TRUE: 같은 이름의 기존 파일이 덮어써져요.
    • FALSE: 같은 이름의 기존 파일이 덮어써지지 않아요. Snowflake는 백그라운드에서 스테이지에 LIST 작업을 수행하며, 이는 PUT 작업의 성능에 영향을 줄 수 있어요. 대상 스테이지에 같은 이름의 파일이 존재하여 파일을 PUT하려는 시도가 실패하면 다음 작업을 수행할 수 있어요:
    • 기존 파일의 데이터를 하나 이상의 테이블에 로드하고 파일을 스테이지에서 제거한 다음, 새 데이터나 업데이트된 데이터의 파일을 스테이지에 PUT해요.
    • 로컬 파일 이름을 바꾼 다음 PUT 작업을 다시 시도해요.
    • PUT 문장에서 OVERWRITE = TRUE를 설정해요. 같은 이름의 기존(스테이징된) 파일을 덮어써도 안전할 때만 이렇게 해요. Snowflake 계정이 Google Cloud에서 호스팅되면 PUT 문장은 OVERWRITE 파라미터가 TRUE로 설정된 것을 인식하지 못해요. PUT 작업은 항상 업로드 중인 로컬 파일로 대상 스테이지의 기존 파일을 덮어써요. 다음 클라이언트는 Amazon Web Services 또는 Microsoft Azure에서 호스팅되는 Snowflake 계정에 대해 OVERWRITE 옵션을 지원해요: SnowSQL, Snowflake ODBC Driver, Snowflake JDBC Driver, Snowflake Connector for Python. 지원 값: TRUE, FALSE. 기본값: FALSE.

사용 메모 (Usage notes)

  • 이 명령은 두 Snowflake 웹 인터페이스의 Worksheets 페이지에서 실행할 수 없어요. 대신 SnowSQL 클라이언트나 드라이버로 데이터 파일을 업로드하거나 특정 Snowflake 클라이언트 문서에서 이 명령 지원 여부를 확인해요. 또는 Snowsight UI로 명명된 내부 스테이지에 파일을 업로드할 수 있어요.
  • 파일 글로빙(globbing) 패턴(와일드카드)은 일치하는 파일들이 분기하는 디렉토리 경로를 가지지 않을 때 지원돼요. 이 명령은 분기하는 디렉토리 경로를 가진 여러 파일 업로드를 지원하지 않아요. Snowflake가 스테이지에 파일을 업로드할 때 파일 시스템 디렉토리 구조를 보존하지 않기 때문이에요. 예를 들어 다음 PUT 문장은 중첩 하위 디렉토리의 여러 파일을 지정할 수 없으므로 오류를 반환해요:
PUT file:///tmp/data/** @my_int_stage AUTO_COMPRESS=FALSE;
  • 이 명령은 파일을 만들거나 이름을 변경하지 않아요.
  • 데이터 로딩 및 언로딩 작업을 위해 내부 스테이지에 저장된 모든 파일은 서버 쪽에서 AES-256 강력 암호화로 자동 암호화돼요. 기본적으로 Snowflake는 128비트 키(256비트 키 구성 옵션 포함)로 추가 클라이언트 쪽 암호화를 제공해요.
  • 이 명령은 같은 스테이지에 업로드하려는 중복 파일을 무시해요. 중복 파일은 이미 스테이징된 파일과 같은 이름의 수정되지 않은 파일이에요. 이미 스테이징된 파일을 덮어쓰려면 업로드 중인 파일을 수정하여 내용이 스테이징된 파일과 달라야 하며, 그 결과 새로 스테이징된 파일에 새 체크섬이 생겨요.
  • PUT 및 GET 명령의 경우 QUERY_HISTORY의 EXECUTION_STATUS가 success여도 데이터 파일이 성공적으로 업로드 또는 다운로드되었음을 의미하지 않아요. 이 상태는 Snowflake가 파일 전송을 진행할 권한을 받았음을 나타내는 것뿐이에요.

팁: 보안상의 이유로 이 명령은 설정된 기간 후에 시간 초과돼요. 이는 크고 압축되지 않은 데이터 파일을 업로드할 때 발생할 수 있어요. 시간 초과 문제를 피하려면 지원되는 압축 유형 중 하나로 큰 데이터 파일을 업로드하기 전에 압축할 것을 권장해요. 그런 다음 SOURCE_COMPRESSION 옵션으로 파일의 압축 유형을 지정해요. 큰 데이터 파일 업로드 시 성능에 도움이 되는 PARALLEL 옵션의 값을 늘리는 것도 고려할 수 있어요. 또한 테이블로 데이터를 로드할 때(COPY INTO <table> 명령 사용) 병렬 작업을 활용하려면 크기가 약 100~250MB로 압축된 데이터 파일을 권장해요. 데이터 파일이 더 크면 서드파티 도구로 더 작은 파일로 분할한 후 압축하고 업로드하는 것을 고려해요.

예시 (Examples)

Linux 및 macOS

파일을 내부 스테이지에 로드하기:

/tmp/data 디렉토리의 mydata.csv라는 파일을 my_int_stage라는 내부 스테이지에 로드해요:

PUT file:///tmp/data/mydata.csv @my_int_stage;

테이블 스테이지에 파일을 로드하기:

/tmp/data 디렉토리의 orders_001.csv라는 파일을 orderstiny_ext 테이블의 스테이지에 자동 데이터 압축을 비활성화하여 로드해요:

PUT file:///tmp/data/orders_001.csv @%orderstiny_ext
  AUTO_COMPRESS = FALSE;

내부 스테이지에 여러 파일 로드하기:

파일 이름에 와일드카드 문자를 사용하여 여러 파일을 업로드해요:

PUT file:///tmp/data/orders_*01.csv @my_int_stage
  AUTO_COMPRESS = FALSE;

특수 문자가 있는 파일 경로 지정하기:

특수 문자나 공백이 있는 파일 경로를 작은따옴표로 묶어요:

PUT 'file:///tmp/data/orders 001.csv' @my_int_stage
  AUTO_COMPRESS = FALSE;

Windows

현재 사용자의 스테이지에 파일을 로드하기:

C:\temp\data 디렉토리의 mydata.csv라는 파일을 현재 사용자의 스테이지에 자동 데이터 압축을 활성화하여 로드해요:

PUT file://C:\temp\data\mydata.csv @~
  AUTO_COMPRESS = TRUE;

특수 문자가 있는 파일 경로 지정하기:

특수 문자가 있는 Windows 파일 경로를 지정하려면 경로를 작은따옴표로 묶고 백슬래시를 슬래시로 바꿔야 해요. 이 예시에서 파일 이름에 공백이 있어요(my data.csv):

PUT 'file://C:/temp/data/my data.csv' @my_int_stage
  AUTO_COMPRESS = TRUE;

더 알아보기 (Learn more)