Categories:: Fonctions de fichiers (AI Functions)

TO_FILE¶

Construit une valeur de type FILE à partir de l’emplacement d’un fichier ou de métadonnées.

Syntaxe¶

Utilisez l’une des méthodes suivantes :

TO_FILE( <stage_name>, <relative_path> )

TO_FILE( <file_url> )

TO_FILE( <metadata> )

Arguments¶

Spécifiez le fichier en fournissant :

stage_name et relative_path
file_url
metadata

Une seule de ces méthodes peut être utilisée à la fois.

stage_name

Le nom de la zone de préparation où se trouve le fichier, sous forme de chaîne, au format ‘@stage_name'.

relative_path

Le chemin d’accès au fichier de la zone de préparation spécifiée par stage_name sous forme de chaîne.

file_url

Une zone de préparation ou une URL de fichier limitée valide sous la forme d’une chaîne.

metadata

Un OBJECT contenant les attributs FILE requis. Un FILE doit comporter les champs CONTENT_TYPE, SIZE, ETAG, et LAST_MODIFIED. Il doit également spécifier l’emplacement du fichier de l’une des manières suivantes :

Les deux valeurs STAGE et RELATIVE_PATH
STAGE_FILE_URL
SCOPED_FILE_URL

Renvoie¶

Un FILE qui représente le fichier en zone de préparation.

Notes sur l’utilisation¶

Lève une erreur lorsque :

L’URL fournie n’est pas valide.
Le fichier se trouve sur une zone de préparation à laquelle l’utilisateur ne peut pas accéder.
Les métadonnées fournies ne contiennent pas les champs FILE requis.

Exemples¶

Création d’objets FILE utilisant TO_FILE¶

Une utilisation simple de la fonctionTO_FILE avec un nom et un chemin relatif de zone de préparation :

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

Résultat :

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

Utilisation simple de la fonction TO_FILE avec une URL de fichier en zone de préparation :

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

Résultat :

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

Ou utilisez l’objetFILE_URL depuis un fichier dans le répertoire de votre zone de préparation :

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

Cet exemple utilise la fonction TO_FILE directement avec une URL de fichier limitée :

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

Voici un exemple de construction d’un FILE à partir d’un objet contenant les métadonnées requises :

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

Ajout deFILE à une table¶

L’exemple suivant montre comment créer une colonne FILE et la stocker dans une table, puis effectuer diverses opérations en utilisant cette colonne, y compris l’enregistrement et le chargement depuis Parquet, SnowPipe, des ensembles de données, des vues matérialisées, des tables dynamiques et le clonage avec Time Travel.

Créer une table avec une colonne 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';

Pour écrire une table contenant une colonne FILE dans une zone de préparation en tant que fichier Parquet et le recharger :

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

Créez un ensemble de données à partir d’un fichier 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';

Copiez des fichiers Parquet dans une table :

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;

Créez un 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;

Créez une vue matérialisée ou une table dynamique à partir de la table :

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;

Stockez les fichiers d’un tableau dans une colonne de 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;

Exemples d’erreurs¶

Ces exemples illustrent des erreurs courantes lors de l’utilisation de TO_FILE qui entraînent une erreur dans la fonction.

L’exemple suivant construit un FILE à partir d’un objet de métadonnées, mais omet un champ obligatoire :

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.

L’exemple suivant est similaire, mais omet le champ ETAG, qui est obligatoire.

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.

L’exemple suivant montre les tentatives de GROUP BY, ORDER BY, et CLUSTER BY une colonne FILE, ce qui n’est pas pris en charge, car les valeurs FILE ne peuvent pas être comparées.

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

Ce dernier exemple utilise un nom de zone de préparation incorrect, en particulier une barre oblique à la fin du nom de la zone de préparation. Snowflake ajoute déjà une barre oblique entre le nom de la zone de préparation et le chemin relatif, de sorte que cela donne deux barres obliques, et le chemin de zone de préparation combiné ne spécifie aucun fichier.

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.

Limitations connues¶

TO_FILE ne peut être utilisé dans la clause INSERT INTO TABLE <t> VALUES. Utilisez plutôt INSERT INTO TABLE <t> SELECT.