PUT

로컬 파일 시스템의 데이터 파일을 다음 Snowflake 스테이지 중 하나로 업로드합니다.

  • 명명된 내부 스테이지.

  • 지정된 테이블의 내부 스테이지.

  • 현재 사용자의 내부 스테이지.

COPY INTO <테이블> 명령을 사용하여 스테이징된 파일을 테이블에 로드할 수 있습니다.

참고

  • PUT은 외부 스테이지로의 파일 업로드를 지원하지 않습니다. 외부 스테이지로 파일을 업로드하려면 클라우드 서비스에서 제공하는 유틸리티를 사용하십시오.

  • ODBC 드라이버 는 다음 플랫폼에 호스트된 Snowflake 계정으로 PUT을 지원합니다.

    • Amazon Web Services

    • Google Cloud Platform

    • Microsoft Azure

참고 항목:

GET , LIST , REMOVE , COPY FILES

구문

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

여기서:

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>[/<path>]
  | @~[/<path>]
Copy

필수 매개 변수

file://path_to_file/filename

클라이언트 컴퓨터에 있는 데이터 파일의 URI를 지정합니다. 여기서 다음 사항이 적용됩니다.

  • path_to_file 은 업로드할 파일의 로컬 디렉터리 경로입니다.

  • filename 은 업로드할 파일의 이름입니다. 와일드카드 문자(*, ?)를 사용하여 여러 파일을 업로드할 수 있습니다. 디렉터리 경로나 파일 이름에 특수 문자나 공백이 포함된 경우 전체 파일 URI를 작은따옴표로 묶습니다.

URI 형식은 클라이언트 운영 체제에 따라 다릅니다.

Linux/macOS:

경로 첫 부분에 슬래시를 포함해야 합니다. 예를 들어, load 라는 파일의 경우 file:///tmp/load 를 사용합니다.

Windows:

경로에 드라이브와 백슬래시를 포함하고 백슬래시 문자를 슬래시로 바꿔야 합니다. 예를 들어, load data 라는 파일의 경우 file://C:/temp/load data 를 사용합니다.

internalStage

Snowflake에서 파일을 업로드할 대상 위치를 지정합니다.

@[namespace.]int_stage_name[/path]

파일은 지정된 명명된 내부 스테이지로 업로드됩니다.

@[namespace.]%table_name[/path]

파일은 지정된 테이블의 스테이지로 업로드됩니다.

@~[/path]

파일은 현재 사용자의 스테이지로 업로드됩니다.

여기서:

  • namespace 는 명명된 내부 스테이지 또는 테이블을 포함하는 데이터베이스 또는 스키마입니다. 데이터베이스와 스키마가 세션 내에서 사용 중인 경우 이는 선택 사항 입니다.

  • path 는 파일 세트에 대한 액세스를 제한하는 클라우드 저장소 위치에 있는 파일의 선택적 경로로, 대/소문자를 구분합니다. 다른 클라우드 저장소 서비스에서는 경로를 접두사 또는 폴더 라고도 합니다.

참고

스테이지 이름 또는 경로가 공백이나 특수 문자를 포함한 경우 이를 작은따옴표로 묶습니다. 예를 들어 "my stage" 라는 스테이지에는 '@"my stage"' 를 사용합니다.

선택적 매개 변수

PARALLEL = integer

파일 업로드에 사용할 스레드 수를 지정합니다. 업로드 프로세스는 데이터 파일의 배치를 크기별로 분리합니다.

  • 작은 파일(64MB 미만의 압축 또는 비압축 파일)은 개별 파일로 동시에 스테이징됩니다.

  • 더 큰 파일은 자동으로 청크로 분할되고 동시에 스테이징되고 대상 스테이지에서 다시 어셈블됩니다. 단일 스레드는 여러 청크를 업로드할 수 있습니다.

스레드 수를 늘리면 큰 파일을 업로드할 때 성능을 높일 수 있습니다.

지원되는 값: 1 (병렬 처리 없음)에서 99 (파일 업로드에 99개의 스레드 사용)까지의 모든 정수 값.

기본값: 4

참고

다음을 포함하여 이전 버전의 Snowflake 드라이버에 16MB 제한이 적용됩니다.

  • 3.12.1 이전의 JDBC 드라이버 버전.

  • 2.20.5 이전의 ODBC 드라이버 버전.

  • 2.2.0 이전의 Python Connector 버전.

AUTO_COMPRESS = TRUE | FALSE

Snowflake가 업로드 중에 gzip을 사용해 파일을 압축할지 여부를 지정합니다.

  • TRUE: Snowflake는 파일을 압축합니다(아직 압축되지 않은 경우).

  • FALSE: Snowflake는 파일을 압축하지 않습니다.

이 옵션은 다른 압축 유형을 지원하지 않습니다. 다른 압축 유형을 사용하려면 파일을 개별적으로 압축한 후 PUT 명령을 실행하십시오. 그런 다음, SOURCE_COMPRESSION 옵션을 사용해 압축 유형을 식별합니다.

Snowflake가 데이터 파일을 압축한 후 스테이징하기에 충분한 공간이 로컬 폴더에 있는지 확인하십시오. 필요한 경우 추가 여유 공간이 있는 로컬 폴더를 가리키도록 운영 체제의 TEMP, TMPDIR 또는 TMP 환경 변수를 설정합니다.

기본값: TRUE

SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

스테이징 중인 이미 압축된 파일에 사용되는 압축 방법을 지정합니다.

지원되는 값

참고

AUTO_DETECT

현재 자동으로 감지할 수 없는 Brotli 압축 파일을 제외하고 압축 알고리즘이 자동으로 감지됩니다. Brotli 압축 파일을 로딩하는 경우 AUTO_DETECT 대신 BROTLI 를 명시적으로 사용합니다.

GZIP

BZ2

BROTLI

Brotli 압축 파일을 로딩하는 경우 사용해야 합니다.

ZSTD

Zstandard v0.8 이상이 지원됩니다.

DEFLATE

Deflate 압축 파일(zlib 헤더 RFC1950 포함).

RAW_DEFLATE

원시 Deflate 압축 파일(헤더 RFC1951 제외).

NONE

로딩할 데이터 파일이 압축되지 않았습니다.

기본값: AUTO_DETECT

참고

Snowflake는 이 옵션을 사용해 데이터 파일의 압축을 풀고 로딩할 데이터를 추출할 수 있도록 데이터 파일 압축 방식을 감지하는데, 이 옵션을 사용해 파일을 압축하지는 않습니다.

다른 유틸리티로 압축된 파일 업로드는 현재 지원되지 않습니다.

OVERWRITE = TRUE | FALSE

업로드 중에 Snowflake가 이름이 같은 기존 파일을 덮어쓸지 여부를 지정합니다.

  • TRUE: 이름이 같은 기존 파일을 덮어씁니다.

  • FALSE: 이름이 같은 기존 파일을 덮어쓰지 않습니다.

    스테이지에 대한 LIST 작업은 백그라운드에서 수행되므로 PUT 작업의 성능에 영향을 줄 수 있습니다.

    대상 스테이지에 이름이 같은 파일이 있어 파일을 PUT하는 시도에 실패할 경우 다음 옵션을 사용할 수 있습니다.

    • 기존 파일의 데이터를 하나 이상의 테이블로 로딩하고 스테이지에서 파일을 제거합니다. 그런 다음, 새 데이터나 업데이트된 데이터가 있는 파일을 스테이지로 PUT합니다.

    • 로컬 파일의 이름을 바꾼 다음 PUT 작업을 다시 시도합니다.

    • PUT 문에서 OVERWRITE = TRUE 를 설정합니다. Snowflake에 아직 로딩되지 않았을 수 있는 데이터가 있는 파일을 덮어써도 실제로 안전한 경우에만 그렇게 하십시오.

Snowflake 계정이 Google Cloud Platform에 호스트되는 경우 PUT 문은 OVERWRITE 매개 변수가 TRUE로 설정될 때 이를 인식하지 못합니다. PUT 작업은 업로드하는 로컬 파일이 있는 대상 스테이지에서 기존 파일을 항상 덮어씁니다.

다음 클라이언트는 Amazon Web Services 또는 Microsoft Azure에서 호스트되는 Snowflake 계정에 대한 OVERWRITE 옵션을 지원합니다.

  • SnowSQL

  • Snowflake ODBC 드라이버

  • Snowflake JDBC 드라이버

  • Python용 Snowflake 커넥터

지원되는 값: TRUE, FALSE.

기본값: FALSE.

사용법 노트

  • 어느 Snowflake 웹 인터페이스에서든 Worksheets 워크시트 탭 페이지에서는 이 명령을 실행할 수 없습니다. 대신 SnowSQL 클라이언트 또는 드라이버 를 사용하여 데이터 파일을 업로드하거나 특정 Snowflake 클라이언트에 대한 설명서를 참조해 이 명령에 대한 지원을 확인하십시오.

  • 이 명령은 스테이지에 파일을 업로드할 때 파일 시스템 디렉터리 구조를 유지하지 않으므로 디렉터리 경로가 서로 다른 여러 파일의 업로드는 지원하지 않습니다.

    예를 들어, 다음 PUT 문은 중첩된 하위 디렉터리에 여러 파일을 지정할 수 없으므로 오류를 반환합니다.

    PUT file:///tmp/data/** @my_int_stage AUTO_COMPRESS=FALSE;
    
    Copy
  • 패턴과 일치하는 파일의 디렉터리 경로가 서로 다르지 않다면 와일드카드와 같은 파일 글로빙 패턴이 지원됩니다.

  • 이 명령은 파일을 만들거나 파일 이름을 바꾸지 않습니다.

  • 데이터 로딩 및 언로딩 작업을 위해 내부 스테이지에 저장되는 모든 파일은 서버 측에서 강력한 AES-256 암호화를 사용하여 자동으로 암호화됩니다. 기본적으로, Snowflake는 (256비트 키를 구성하는 옵션과 함께) 128비트 키를 사용하여 추가적인 클라이언트 측 암호화를 제공합니다. 자세한 내용은 내부 스테이지의 암호화 유형 을 참조하십시오.

  • 이 명령은 같은 스테이지에 업로드하려는 모든 중복 파일을 무시합니다. 중복 파일은 이미 스테이징된 파일과 같은 이름을 가진 수정되지 않은 파일입니다.

    이미 스테이징된 상태의 파일을 덮어쓰려면 업로드 중인 파일의 내용이 스테이징된 파일과 달라 새로 스테이징된 파일의 새로운 체크섬이 생성되도록 업로드하려는 파일을 수정해야 합니다.

보안상의 이유로, 이 명령은 설정된 시간이 지나면 시간 초과됩니다. 이는 압축되지 않은 큰 데이터 파일을 로딩할 때 발생할 수 있습니다. 시간 초과 문제를 방지하려면 파일을 업로드하기 전에 지원되는 압축 유형 중 하나를 사용해 큰 데이터 파일을 압축하는 것이 좋습니다. 그런 다음, SOURCE_COMPRESSION 옵션을 사용해 파일의 압축 유형을 지정합니다.

큰 데이터 파일을 업로드할 때 PARALLEL 옵션의 값을 높여 성능에 도움이 되도록 할 수도 있습니다.

또한, (COPY INTO <테이블> 명령을 사용해) 데이터를 테이블에 로딩할 때 병렬 작업을 활용하려면 크기가 대략 100~250MB로 압축된 데이터 파일을 사용하는 것이 좋습니다. 데이터 파일이 더 큰 경우에는 서드 파티 도구를 사용해 파일을 더 작은 파일로 분할한 후 압축하고 업로드해 보십시오.

(Linux 또는 macOS 환경에서) /tmp/data 디렉터리에 있는 mydata.csv 파일을 my_int_stage 로 명명된 내부 스테이지로 업로드합니다.

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

(Linux 또는 macOS 환경에서) 자동 데이터 압축을 비활성화한 상태에서 /tmp/data 디렉터리에 있는 orders_001.csv 파일을 orderstiny_ext 테이블에 대한 스테이지로 업로드합니다.

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

위와 같은 예이지만, 파일 이름에 와일드카드 문자를 사용해 여러 파일을 업로드합니다.

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

(Windows 환경에서) 자동 데이터 압축을 활성화한 상태에서 C:\temp\data 디렉터리에 있는 mydata.csv 파일을 현재 사용자에 대한 스테이지로 업로드합니다.

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

이전의 예와 비슷하지만, (Windows 환경에서는) C:\temp\load data 디렉터리에서 파일을 업로드합니다.

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