Categories:: Funções de arquivo (AI Functions)

TO_FILE¶

Constrói um valor do tipo FILE a partir de um local de arquivo ou de metadados.

Sintaxe¶

Use uma das seguintes opções:

TO_FILE( <stage_name>, <relative_path> )

TO_FILE( <file_url> )

TO_FILE( <metadata> )

Argumentos¶

Especifique o arquivo fornecendo:

stage_name e relative_path
file_url
metadata

Apenas um desses métodos pode ser usado por vez.

stage_name

O nome do estágio em que o arquivo está localizado, como uma cadeia de caracteres, no formato '@stage_name'.

relative_path

O caminho para o arquivo no estágio especificado por stage_name como uma cadeia de caracteres.

file_url

Um URL de arquivo com escopo ou estágio válido como uma cadeia de caracteres.

metadata

Um OBJECT contendo os atributos FILE necessários. Um FILE deve ter os campos CONTENT_TYPE, SIZE, ETAG e LAST_MODIFIED. Ele também deve especificar a localização do arquivo de uma das seguintes maneiras:

Tanto STAGE quanto RELATIVE_PATH
STAGE_FILE_URL
SCOPED_FILE_URL

Retornos¶

Um FILE que representa o arquivo preparado.

Notas de uso¶

Gera um erro quando:

O URL fornecido não é válido.
O arquivo está em uma área de preparação ao qual o usuário não tem privilégios de acesso.
Os metadados fornecidos não contêm os campos obrigatórios do FILE.

Exemplos¶

Criação de objetos FILE usando TO_FILE¶

Um uso simples da função TO_FILE com um nome de cenário e caminho relativo:

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

Resultado:

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

Um uso simples da função TO_FILE com um o URL do arquivo preparado:

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

Resultado:

+--------------------------------------------------------------------------------------------------------------------+
| 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 use o FILE_URL de um arquivo no diretório da sua área de preparação:

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

Este exemplo usa a função TO_FILE diretamente com um URL do arquivo com escopo:

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

Isso mostra um exemplo de construção de um FILE a partir de um objeto que contém os metadados necessários:

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

Adição de FILE a uma tabela¶

O exemplo a seguir demonstra como criar FILE e armazená-lo em uma tabela e, em seguida, executar várias operações usando essa coluna, incluindo salvar e carregar do Parquet, SnowPipe, conjuntos de dados, exibições materializadas, tabelas dinâmicas e clonagem com Time Travel.

Criação de uma tabela com uma coluna 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';

Para gravar uma tabela contendo uma coluna FILE em uma área de preparação como um arquivo Parquet e carregá-la de volta:

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

Crie um conjunto de dados a partir de um arquivo 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';

Copie os arquivos Parquet para uma tabela:

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;

Crie um 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;

Crie uma exibição materializada ou uma tabela dinâmica a partir da tabela:

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;

Armazene arquivos em uma matriz em uma coluna da tabela:

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;

Exemplos de erros¶

Estes exemplos ilustram erros comuns no uso de TO_FILE que resultam na geração de um erro pela função.

O exemplo a seguir cria um FILE a partir de um objeto de metadados, mas omite um campo obrigatório:

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.

O exemplo a seguir é semelhante, mas omite o campo ETAG, que é obrigatório.

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.

O exemplo a seguir mostra tentativas de GROUP BY, ORDER BY e CLUSTER BY em uma coluna FILE, o que não é aceito porque os valores FILE não podem ser comparados.

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

Este exemplo final usa um nome de área de preparação incorreto, especificamente uma barra no fim do nome. O Snowflake já adiciona uma barra entre o nome da área de preparação e o caminho relativo, resultando em duas barras, e o caminho da área de preparação combinado não especifica nenhum arquivo.

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.

Limitações conhecidas¶

TO_FILE não pode ser usado na cláusula INSERT INTO TABLE <t> VALUES. Em vez disso, use INSERT INTO TABLE <t> SELECT.