TO_FILE

TO_FILE

파일 위치 또는 메타데이터에서 FILE 타입의 값을 구성해요.

출처: Snowflake SQL Reference - TO_FILE

본문

구문

다음 중 하나를 사용해요:

TO_FILE( stage_name, relative_path )

TO_FILE( file_url )

TO_FILE( metadata )

인자

다음을 제공하여 파일을 지정해요:

• stage_name과 relative_path 둘 다
• file_url
• metadata

이 방법 중 한 번에 하나만 사용할 수 있어요.

stage_name 파일이 있는 스테이지의 이름을 문자열로, @stage_name 형태로 지정해요.

relative_path stage_name으로 지정한 스테이지 위의 파일 경로를 문자열로 지정해요.

file_url 유효한 스테이지 또는 스코프 파일 URL을 문자열로 지정해요.

metadata 필요한 FILE 속성을 포함하는 OBJECT예요. FILE은 CONTENT_TYPE, SIZE, ETAG, LAST_MODIFIED 필드가 있어야 해요. 또한 다음 방법 중 하나로 파일의 위치를 지정해야 해요:

• STAGE와 RELATIVE_PATH 둘 다
• STAGE_FILE_URL
• SCOPED_FILE_URL

반환 값

스테이지에 있는 파일을 나타내는 FILE을 반환해요.

사용 시 유의사항

다음 경우에 오류를 발생시켜요:

• 제공된 URL이 유효하지 않을 때.
• 파일이 사용자가 접근 권한이 없는 스테이지에 있을 때.
• 제공된 메타데이터에 필요한 FILE 필드가 포함되어 있지 않을 때.

예시

TO_FILE을 사용하여 FILE 객체 만들기

스테이지 이름과 상대 경로를 사용한 TO_FILE 함수의 간단한 사용:

SELECT TO_FILE(@mystage, image.png);

결과:

+-----------------------------------------------------+
| TO_FILE(@MYSTAGE, IMAGE.PNG)                        |
|-----------------------------------------------------|
| {                                                   |
|   CONTENT_TYPE: image/png,                          |
|   ETAG: 2859efde6e26491810f619668280a2ce,           |
|   LAST_MODIFIED: Thu, 18 Sep 2025 09:02:00 GMT,     |
|   RELATIVE_PATH: image.png,                         |
|   SIZE: 23698,                                      |
|   STAGE: @MYDB.MYSCHEMA.MYSTAGE                     |
| }                                                   |
+-----------------------------------------------------+

스테이지에 있는 파일 URL을 사용한 TO_FILE 함수의 간단한 사용:

SELECT TO_FILE(BUILD_STAGE_FILE_URL(@mystage, image.png));

결과:

+--------------------------------------------------------------------------------------------------------------------+
| TO_FILE(BUILD_STAGE_FILE_URL(@MYSTAGE, IMAGE.PNG))                                                                 |
|--------------------------------------------------------------------------------------------------------------------|
| {                                                                                                                  |
|   CONTENT_TYPE: image/png,                                                                                         |
|   ETAG: ...                                                                                                        |
|   LAST_MODIFIED: Wed, 11 Dec 2024 20:24:00 GMT,                                                                    |
|   RELATIVE_PATH: image.png,                                                                                        |
|   SIZE: 105859,                                                                                                    |
|   STAGE: @MYDB.MYSCHEMA.MYSTAGE,                                                                                   |
|   STAGE_FILE_URL: https://snowflake.account.snowflakecomputing.com/api/files/MYDB/MYSCHEMA/MYSTAGE/image.png       |
| }                                                                                                                  |
+--------------------------------------------------------------------------------------------------------------------+

또는 스테이지 디렉터리에 있는 파일의 FILE_URL을 사용해요:

SELECT TO_FILE(FILE_URL) FROM DIRECTORY(@mystage) LIMIT 1;

+--------------------------------------------------------------------------------------------------------------------+
| TO_FILE(FILE_URL)                                                                                                  |
|--------------------------------------------------------------------------------------------------------------------|
| {                                                                                                                  |
|   CONTENT_TYPE: image/png,                                                                                         |
|   ETAG: ...                                                                                                        |
|   LAST_MODIFIED: Wed, 11 Dec 2024 20:24:00 GMT,                                                                    |
|   RELATIVE_PATH: image.png,                                                                                        |
|   SIZE: 105859,                                                                                                    |
|   STAGE: @MYDB.MYSCHEMA.MYSTAGE,                                                                                   |
|   STAGE_FILE_URL: https://snowflake.account.snowflakecomputing.com/api/files/MYDB/MYSCHEMA/MYSTAGE/image.png       |
| }                                                                                                                  |
+--------------------------------------------------------------------------------------------------------------------+

이 예시는 스코프 파일 URL과 함께 TO_FILE 함수를 직접 사용해요:

SELECT TO_FILE(`https://snowflake.account.snowflakecomputing.com/api/files/01ba4df2-0100-0001-0000-00040002e2b6/299017/Y6JShH6KjV`);
+------------------------------------------------------------------------------------------------------------------------------------------------+
| TO_FILE(https://snowflake.account.snowflakecomputing.com/api/files/01ba4df2-0100-0001-0000-00040002e2b6/299017/Y6JShH6KjV                      |
|------------------------------------------------------------------------------------------------------------------------------------------------|
| {                                                                                                                                              |
|   CONTENT_TYPE: image/png,                                                                                                                     |
|   ETAG: ...                                                                                                                                    |
|   LAST_MODIFIED: Wed, 11 Dec 2024 20:24:00 GMT,                                                                                                |
|   SCOPED_FILE_URL: https://snowflake.account.snowflakecomputing.com/api/files/01ba4df2-0100-0001-0000-00040002e2b6/299017/Y6JShH6KjV,          |
|   SIZE: 105859                                                                                                                                 |
| }                                                                                                                                              |
+------------------------------------------------------------------------------------------------------------------------------------------------+

이것은 필요한 메타데이터를 포함한 객체에서 FILE을 구성하는 예시를 보여줘요:

SELECT TO_FILE(OBJECT_CONSTRUCT(STAGE, MYSTAGE, RELATIVE_PATH, image.png, ETAG, ETAG value,
  LAST_MODIFIED, Wed, 11 Dec 2024 20:24:00 GMT, SIZE, 105859, CONTENT_TYPE, image/png));
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| TO_FILE(OBJECT_CONSTRUCT(STAGE, MYSTAGE, RELATIVE_PATH, IMAGE.PNG, ETAG, ETAG value, LAST_MODIFIED, WED, 11 DEC 2024 20:24:00 GMT, SIZE, 105859, CONTENT_TYPE, IMAGE/PNG))                        |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| {                                                                                                                                                                                                  |
|   CONTENT_TYPE: image/png,                                                                                                                                                                         |
|   ETAG: ETAG value                                                                                                                                                                                 |
|   LAST_MODIFIED: Wed, 11 Dec 2024 20:24:00 GMT,                                                                                                                                                    |
|   RELATIVE_PATH: image.png,                                                                                                                                                                        |
|   SIZE: 105859,                                                                                                                                                                                     |
|   STAGE: @MYDB.MYSCHEMA.MYSTAGE                                                                                                                                                                    |
| }                                                                                                                                                                                                  |
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

테이블에 FILE 추가

다음 예시는 FILE을 만들고 테이블에 저장한 다음, 그 컬럼을 사용해 Parquet로 저장·로드, SnowPipe, 데이터셋, 구체화된 뷰, 동적 테이블, 시간 이동(time travel)을 포함한 클로닝 등의 다양한 작업을 수행하는 방법을 보여줘요.

FILE 컬럼이 있는 테이블 만들기:

CREATE OR REPLACE TABLE sample_table (a INT, f FILE NOT NULL);
DESCRIBE TABLE sample_table;
INSERT INTO sample_table SELECT 1, TO_FILE(@mystage, image.png);
INSERT INTO sample_table SELECT 1, TO_FILE(@mystage, relative_path) FROM DIRECTORY(@mystage);
SELECT * FROM sample_table WHERE fl_get_file_type(f) = image;

FILE 컬럼이 있는 테이블을 Parquet 파일로 스테이지에 쓰고 다시 로드하려면:

-- Write to stage as Parquet
CREATE OR REPLACE STAGE test_stage_parquet;

CREATE OR REPLACE FILE FORMAT parquet_format
  TYPE = PARQUET
  USE_LOGICAL_TYPE = TRUE;

COPY INTO @test_stage_parquet/file_copy.parquet FROM sample_table
  FILE_FORMAT = (FORMAT_NAME = parquet_format) HEADER = TRUE - SELECT rows_unloaded FROM $1;
ALTER STAGE test_stage_parquet SET DIRECTORY = (ENABLE=TRUE);
ALTER STAGE test_stage_parquet REFRESH;

-- Read Parquet files back from stage
SELECT * FROM @TEST_STAGE_PARQUET/file_copy.parquet_0_0_0.snappy.parquet(FILE_FORMAT = parquet_format);
SELECT * FROM @TEST_STAGE_PARQUET (PATTERN = .*.parquet, FILE_FORMAT = parquet_format);

Parquet 파일에서 데이터셋 만들기:

CREATE OR REPLACE DATASET mydataset;
ALTER DATASET mydataset ADD VERSION v1 FROM
  (SELECT * FROM @TEST_STAGE_PARQUET/file_copy.parquet_0_0_0.snappy.parquet(
    FILE_FORMAT = my_parquet_format))
  COMMENT = test dataset;

Parquet 파일을 테이블로 복사:

CREATE OR REPLACE TABLE t1_copy_parquet (a INT, f OBJECT NOT NULL);

COPY INTO t1_copy_parquet
  FROM @test_stage_parquet
  FILE_FORMAT = (FORMAT_NAME = parquet_format)
  MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE;

SELECT FL_GET_STAGE(f), FL_GET_RELATIVE_PATH(f) FROM t1_copy_parquet;

Snowpipe 만들기:

CREATE OR REPLACE TABLE t1_copy_parquet_snowpipe (f OBJECT NOT NULL);
CREATE OR REPLACE PIPE test_pipe AS
  COPY INTO t1_copy_parquet_snowpipe
  FROM @test_stage_parquet
FILE_FORMAT = (FORMAT_NAME = my_parquet_format)
MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE;

ALTER PIPE TEST_PIPE REFRESH;

테이블에서 구체화된 뷰 또는 동적 테이블 만들기:

CREATE OR REPLACE MATERIALIZED VIEW MV AS SELECT * FROM SAMPLE_TABLE;

CREATE OR REPLACE DYNAMIC TABLE sample_dynamic_table
  WAREHOUSE = my_warehouse
  TARGET_LAG = 60 minutes
AS SELECT f FROM sample_table;

테이블 컬럼의 배열에 파일 저장:

CREATE OR REPLACE TABLE files_array_table(files ARRAY);
INSERT INTO files_array_table SELECT ARRAY_CONSTRUCT(TO_FILE(@mystage, image.png));
CREATE OR REPLACE TABLE files_array_table_copy(files ARRAY);
INSERT INTO files_array_table_copy SELECT files[0] FROM files_array_table;

오류 예시

이 예시들은 함수가 오류를 발생시키는 TO_FILE 사용의 흔한 실수를 보여줘요.

다음 예시는 메타데이터 객체에서 FILE을 구성하지만 필수 필드를 생략해요:

SELECT TO_FILE(OBJECT_CONSTRUCT(RELATIVE_PATH, image.png, ETAG, ETAG value,
  LAST_MODIFIED, Wed, 11 Dec 2024 20:24:00 GMT, SIZE, 105859, CONTENT_TYPE, image/png));

Invalid file metadata. Must provide (STAGE and RELATIVE_PATH), SCOPED_FILE_URL, or STAGE_FILE_URL.

다음 예시는 비슷하지만 필수인 ETAG 필드를 생략해요.

SELECT TO_FILE(OBJECT_CONSTRUCT(STAGE, MYSTAGE, RELATIVE_PATH, image.png,
  LAST_MODIFIED, Wed, 11 Dec 2024 20:24:00 GMT, SIZE, 105859, CONTENT_TYPE, image/png));

Invalid file metadata. Missing required fields: ETAG.

다음 예시는 FILE 컬럼에 GROUP BY, ORDER BY, CLUSTER BY를 시도한 것을 보여줘요. FILE 값은 비교할 수 없기 때문에 지원되지 않아요.

SELECT f, count(*) FROM sample_table GROUP BY f;
-- Expressions of type FILE cannot be used as GROUP BY keys

SELECT * FROM sample_table ORDER by f;
-- Expressions of type FILE cannot be used as ORDER BY keys

CREATE OR REPLACE TABLE cluster_to_file (a int, url string) CLUSTER BY (to_file(url));
-- Unsupported type FILE for clustering keys

마지막 예시는 잘못된 스테이지 이름, 특히 스테이지 이름 끝의 슬래시를 사용해요. Snowflake는 이미 스테이지 이름과 상대 경로 사이에 슬래시를 추가하므로 결과적으로 슬래시가 두 개가 되고, 결합된 스테이지 경로는 어떤 파일도 지정하지 않아요.

SELECT TO_FILE(@mystage/, image.png);

Remote file @mystage//image.png was not found. There are several potential causes.
The file might not exist. The required credentials may be missing or invalid. If you
are running a copy command, please make sure files are not deleted when they are
being loaded or files are not being loaded into two different tables concurrently
with auto purge option.

알려진 제한 사항

• TO_FILE은 INSERT INTO TABLE t VALUES 절에서 사용할 수 없어요. 대신 INSERT INTO TABLE t SELECT를 사용하세요.