TO_FILE¶
파일 위치 또는 메타데이터에서 FILE 타입의 값을 생성합니다.
구문¶
다음 중 하나를 사용하십시오.
TO_FILE( <stage_name>, <relative_path> ) TO_FILE( <file_url> ) TO_FILE( <metadata> )
인자¶
다음을 제공하여 파일을 지정합니다.
stage_name및relative_pathfile_urlmetadata
이러한 메서드는 한 번에 하나만 사용할 수 있습니다.
stage_name파일이 위치한 스테이지의 이름으로,
'@stage_name'형식의 문자열입니다.relative_pathstage_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" |
| } |
+--------------------------------------------------------------------------------------------------------------------+
이 예제에서는 TO_FILE 함수를 범위가 지정된 파일 URL 과 함께 직접 사용합니다.
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, 데이터 세트, 구체화된 뷰, 동적 테이블에서 저장 및 로드, 시간 이동을 통한 복제 등 해당 열을 사용하여 다양한 작업을 수행하는 방법을 보여줍니다.
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 값을 비교할 수 없어 지원되지 않는 FILE 열에 대한 GROUP BY, ORDER BY 및 CLUSTER BY 시도를 보여줍니다.
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는 이미 스테이징 이름과 상대 경로 사이에 슬래시를 추가하고 있으므로, 슬래시가 2개가 되며 결합된 스테이징 경로는 파일을 지정하지 않습니다.
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 를 사용합니다.