Categories:: Dateifunktionen (AI Functions)

TO_FILE¶

Erstellt einen Wert vom Typ FILE aus einem Dateispeicherort oder aus Metadaten.

Syntax¶

Verwenden Sie eine der folgenden Optionen:

TO_FILE( <stage_name>, <relative_path> )

TO_FILE( <file_url> )

TO_FILE( <metadata> )

Argumente¶

Geben Sie die Datei an, indem Sie Folgendes angeben:

Sowohl stage_name als auch relative_path
file_url
metadata

Es kann jeweils nur eine dieser Methoden verwendet werden.

stage_name

Der Name des Stagingbereichs, in dem sich die Datei befindet, als Zeichenfolge im Format '@stage_name'.

relative_path

Der Pfad zu der Datei im durch stage_name als Zeichenfolge angegebenen Stagingbereich.

file_url

Ein gültiger Stagingbereich oder eine Bereichsdatei-URL als Zeichenfolge.

metadata

Ein OBJECT, das die erforderlichen FILE-Attribute enthält. Eine FILE muss Felder des Typs CONTENT_TYPE, SIZE, ETAG und LAST_MODIFIED haben. Außerdem muss der Speicherort der Datei auf eine der folgenden Arten angegeben werden:

Sowohl STAGE als auch RELATIVE_PATH
STAGE_FILE_URL
SCOPED_FILE_URL

Rückgabewerte¶

Eine FILE, die die Stagingdatei darstellt.

Nutzungshinweise¶

Gibt in den folgenden Fällen einen Fehler aus:

Die angegebene URL ist nicht gültig.
Die Datei befindet sich in einem Stagingbereich, für den der Benutzende keine Zugriffsrechte hat.
Die angegebenen Metadaten enthalten nicht die erforderlichen FILE-Felder.

Beispiele¶

Erstellen von FILE-Objekte mit TO_FILE¶

Eine einfache Verwendung der TO_FILE-Funktion mit dem Namen eines Stagingbereichs und relativem Pfad:

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

Ergebnis:

+-----------------------------------------------------+
| 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"                 |
| }                                                   |
+-----------------------------------------------------+

Eine einfache Anwendung der Funktion TO_FILE mit einer Stagingdatei-URL:

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

Ergebnis:

+--------------------------------------------------------------------------------------------------------------------+
| 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"   |
| }                                                                                                                  |
+--------------------------------------------------------------------------------------------------------------------+

Oder verwenden Sie die FILE_URL aus einer Datei im Verzeichnis Ihres Stagingbereichs:

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"   |
| }                                                                                                                  |
+--------------------------------------------------------------------------------------------------------------------+

In diesem Beispiel wird die Funktion TO_FILE direkt mit einer Bereichsdatei-URL verwendet:

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                                                                                                                               |
| }                                                                                                                                              |
+-----------------------------------------------------------------------------------------------------------------------------------------------+|

Hier sehen Sie ein Beispiel für die Erstellung einer FILE aus einem Objekt, das die erforderlichen Metadaten enthält:

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"                                                                                                                                                                |
| }                                                                                                                                                                                                  |
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Hinzufügen von FILE zu einer Tabelle¶

Im folgenden Beispiel wird gezeigt, wie Sie FILE erstellen und in einer Tabelle speichern und dann verschiedene Vorgänge mit dieser Spalte ausführen, darunter das Speichern und Laden aus Parquet, SnowPipe, Datensets, materialisierten Ansichten, dynamischen Tabellen sowie das Klonen mit Time Travel.

So erstellen Sie eine Tabelle mit einer FILE-Spalte:

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';

So schreiben Sie eine Tabelle mit einer FILE-Spalte als Parquet-Datei in einen Stagingbereich und laden sie zurück:

-- 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);

So erstellen Sie ein Datenset aus einer Parquet-Datei:

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';

So kopieren Sie Parquet-Dateien in eine Tabelle:

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;

So erstellen Sie eine 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;

So erstellen Sie eine materialisierte Ansicht oder eine dynamische Tabelle aus der Tabelle:

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;

So speichern Sie Dateien in einem Array in einer Tabellenspalte:

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;

Beispiele für Fehler¶

Diese Beispiele veranschaulichen häufige Fehler bei der Verwendung von TO_FILE, die dazu führen, dass die Funktion einen Fehler auslöst.

Im folgenden Beispiel wird eine FILE aus einem Metadatenobjekt erstellt, jedoch wird ein erforderliches Feld weggelassen:

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.

Das folgende Beispiel ist ähnlich, enthält aber nicht das ETAG-Feld, das erforderlich ist.

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.

Das folgende Beispiel zeigt Versuche mit GROUP BY, ORDER BY und CLUSTER BY für eine FILE-Spalte, was nicht unterstützt wird, da FILE-Werte können nicht verglichen werden können.

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

Dieses letzte Beispiel verwendet einen falschen Stagingbereichsnamen, genauer gesagt einen Schrägstrich am Ende des Stagingbereichsnamens. Snowflake fügt bereits einen Schrägstrich zwischen dem Namen des Stagingbereichs und dem relativen Pfad ein, sodass dies zu zwei Schrägstrichen führt und der kombinierte Stagingbereichspfad keine Datei angibt.

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.

Bekannte Einschränkungen¶

TO_FILE kann nicht in der Klausel INSERT INTO TABLE <t> VALUES verwendet werden. Verwenden Sie stattdessen INSERT INTO TABLE <t> SELECT.