TO_FILE¶
ファイルの場所またはメタデータから FILE タイプの値を構築します。
構文¶
次のいずれかを使用します。
TO_FILE( <stage_name>, <relative_path> ) TO_FILE( <file_url> ) TO_FILE( <metadata> )
引数¶
次を指定して、ファイルを指定します。
stage_nameおよび :samp:`{relative_path}`の両方。file_urlmetadata
一度に使用できるメソッドは1つだけです。
stage_nameファイルが文字列として
'@stage_name'の形式で配置されているステージの名前。relative_path文字列として
stage_nameで指定されたステージ上のファイルへのパス。file_url有効なステージまたはスコープ付きファイル URL を文字列で指定します。
metadataOBJECT に必要なFILE 属性を含むもの。FILE には CONTENT_TYPE、 SIZE、ETAGおよび LAST_MODIFIED フィールドが必要です。また、次のいずれかの方法でファイルの場所を指定する必要があります。
STAGE と RELATIVE_PATH の両方
STAGE_FILE_URL
SCOPED_FILE_URL
戻り値¶
ステージングされたファイルを表している FILE。
使用上の注意¶
次の場合、エラーが発生します。
指定された URL は無効である。
ファイルは、ユーザーにアクセス権限がないステージにあります。
提供されたメタデータに必須である FILE フィールドが含まれていない。
例¶
FILE を使用した TO_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" | | } | +-----------------------------------------------------+ TO_FILE 関数をステージングされたファイル URL で使用する簡単な方法:
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. 次の例は、 GROUPBY, ORDERBYおよび CLUSTERBY または FILE 列に対する試行を示しています。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はすでにステージ名と相対パスの間にスラッシュを追加しているため、これにより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 を使用します。