PUT¶

Sintaxe¶

PUT file://<absolute_path_to_file>/<filename> internalStage
    [ PARALLEL = <integer> ]
    [ AUTO_COMPRESS = TRUE | FALSE ]
    [ SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE ]
    [ OVERWRITE = TRUE | FALSE ]

Onde:

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>[/<path>]
  | @~[/<path>]

Copy

Parâmetros obrigatórios¶

file://absolute_path_to_file/filename

Especifica o URI para os arquivos de dados na máquina do cliente, em que:

• absolute_path_to_file é o caminho do diretório local para os arquivos a serem carregados.

• filename é o nome do arquivo a ser carregado. Você pode usar caracteres curinga (*, ?) para fazer upload de vários arquivos. Se o caminho do diretório ou nome do arquivo incluir caracteres especiais ou espaços, coloque o URI do arquivo inteiro entre aspas simples.

  Atenção

  Tenha cuidado ao selecionar vários arquivos usando uma consulta PUT. As consultas PUT que correspondem a um grande número de arquivos podem ter consequências significativas em termos de custo e desempenho.

A formatação do URI é diferente dependendo do sistema operacional de seu cliente:

Linux/macOS:

Especifique o caminho absoluto para o arquivo a partir do diretório raiz (/). Por exemplo, para um arquivo chamado my-data.csv use file:///my/file/path/my-data.csv.

Windows:

Especifique o caminho absoluto a partir da raiz da unidade em que o arquivo ou arquivos estão localizados. Por exemplo, para um arquivo chamado my-data.csv use file://C:temp\my-data.csv.

Se o caminho do arquivo incluir caracteres especiais, você deverá colocar todo o caminho entre aspas simples e alterar o separador de unidade e caminho de uma barra invertida para uma barra invertida (/). Por exemplo, para um arquivo chamado my$data.csv, use: 'file://C:/temp/my$data.csv'.

Nota

O Snowflake não suporta arquivos tar (tape archive).

internalStage

Especifica o local do estágio interno para o upload dos arquivos:

@[namespace.]int_stage_name[/path]	Os arquivos são carregados no estágio interno nomeado especificado.
@[namespace.]%table_name[/path]	Os arquivos são carregados no estágio para a tabela especificada.
@~[/path]	Os arquivos são carregados no estágio para o usuário atual.

Onde:

• namespace é o banco de dados ou esquema que contém o estágio ou tabela interna nomeada. É opcional se um banco de dados e um esquema forem usados dentro da sessão.

• path é um caminho opcional que distingue letras maiúsculas de minúsculas para arquivos no local de armazenamento em nuvem que limita o acesso a um conjunto de arquivos. Os caminhos são chamados alternativamente de prefixos ou pastas por diferentes serviços de armazenamento em nuvem.

Nota

Se o nome do estágio ou o caminho incluir espaços ou caracteres especiais, coloque-os entre aspas simples. Por exemplo, use '@"my stage"' para um estágio chamado "my stage".

Parâmetros opcionais¶

PARALLEL = integer

Especifica o número de threads a serem utilizados para o carregamento de arquivos. O Snowflake faz o upload de lotes separados de arquivos de dados por tamanho:

• Os arquivos menores que 64 MB (compactados ou descompactados) são preparados em paralelo como arquivos individuais.

• Os arquivos maiores são automaticamente divididos em partes, preparados ao mesmo tempo e remontados no estágio de destino. Um único thread pode carregar várias partes.

O aumento do número de threads pode melhorar o desempenho ao carregar arquivos grandes.

Valores suportados: qualquer valor inteiro de 1 (sem paralelismo) até 99 (use 99 threads para carregar os arquivos).

Padrão: 4

Nota

Um limite de 16 MB se aplica às versões mais antigas dos drivers do Snowflake, incluindo:

• Versões do driver JDBC anteriores a 3.12.1.

• Versões do driver ODBC anteriores a 2.20.5.

• Versões do Python Connector anteriores a 2.2.0.

AUTO_COMPRESS = TRUE | FALSE

Especifica se o Snowflake usa gzip para comprimir arquivos durante o upload:

• TRUE: Snowflake compacta os arquivos (se eles ainda não estiverem compactados).

• FALSE: Snowflake não compacta os arquivos.

Esta opção não oferece suporte a outros tipos de compressão. Para utilizar um tipo de compressão diferente, comprima o arquivo separadamente antes de executar o comando PUT. Em seguida, identificar o tipo de compressão usando a opção SOURCE_COMPRESSION.

Certifique-se de que sua pasta local tenha espaço suficiente para que o Snowflake comprima os arquivos de dados antes de prepará-los. Se necessário, defina a variável de ambiente TEMP, TMPDIR ou TMP em seu sistema operacional para apontar para uma pasta local que contenha espaço livre adicional.

Padrão: TRUE

SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

Especifica o método de compressão usado em arquivos já compactados que estão sendo preparados:

Valores suportados	Notas
AUTO_DETECT	Algoritmo de compressão detectado automaticamente, exceto para arquivos comprimidos com Brotli, que atualmente não podem ser detectados automaticamente. Se estiver fazendo upload de arquivos compactados do Brotli, use explicitamente BROTLI em vez de AUTO_DETECT.
GZIP	Não oferece suporte ao formato de arquivo *.tar.gz.
BZ2	Não oferece suporte ao formato de arquivo *.tar.bz2.
BROTLI	Deve ser usado para fazer upload de arquivos compactados pelo Brotli.
ZSTD	Zstandard v0.8 (e superior) suportado.
DEFLATE	Arquivos compactados Deflate (com cabeçalho zlib, RFC1950).
RAW_DEFLATE	Arquivos compactados Raw Deflate (sem cabeçalho, RFC1951).
NONE	Os arquivos de dados não foram comprimidos.

Padrão: AUTO_DETECT

Nota

O Snowflake usa esta opção para detectar como os arquivos de dados foram comprimidos para que possam ser descomprimidos e os dados extraídos para o upload; ele não usa esta opção para comprimir os arquivos.

No momento, não há suporte para o carregamento de arquivos compactados com outros utilitários.

OVERWRITE = TRUE | FALSE

Especifica se o Snowflake substitui um arquivo existente com o mesmo nome durante o upload:

• TRUE: um arquivo existente com o mesmo nome é substituído.

• FALSE: um arquivo existente com o mesmo nome não é substituído.

  O Snowflake executa uma operação LIST no estágio em segundo plano, o que pode afetar o desempenho da operação PUT.

  Se as tentativas de PUT um arquivo falharem porque existe um arquivo com o mesmo nome no estágio de destino, você pode tomar as seguintes medidas:

  • Carregar os dados do arquivo existente em uma ou mais tabelas, e remover o arquivo do estágio. Em seguida, PUT um arquivo com dados novos ou atualizados no estágio.

  • Renomear o arquivo local, e depois tentar a operação PUT novamente.

  • Definir OVERWRITE = TRUE na instrução PUT. Faça isso somente se for seguro sobrescrever o arquivo existente (preparado) com o mesmo nome.

Se a sua conta Snowflake estiver hospedada em Google Cloud, as instruções PUT não serão reconhecidas quando o parâmetro OVERWRITE for definido como TRUE. Uma operação PUT sempre sobrescreve todos os arquivos existentes no estágio de destino com os arquivos locais que você está carregando.

Os clientes a seguir oferecem suporte à opção OVERWRITE para contas Snowflake hospedadas em Amazon Web Services ou Microsoft Azure:

• SnowSQL

• Driver Snowflake ODBC

• Driver Snowflake JDBC

• Conector Snowflake para Python

Valores suportados: TRUE, FALSE.

Padrão: FALSE.

Notas de uso¶

• O comando não pode ser executado a partir da página Worksheets na interface da web do Snowflake; em vez disso, use o cliente SnowSQL ou Drivers para carregar arquivos de dados, ou verifique a documentação de um cliente específico do Snowflake para verificar o suporte a este comando.

  Como alternativa, você pode usar o Snowsight UI para carregar arquivos em um estágio interno nomeado.

• Padrões de recursos de englobamento de arquivos, como curingas, são suportados, a menos que os arquivos que correspondam ao padrão tenham caminhos de diretório divergentes. O comando não oferece suporte ao upload de vários arquivos com caminhos de diretório divergentes, porque o Snowflake não preserva a estrutura de diretório do sistema de arquivos ao fazer o upload de arquivos para o estágio.

  Por exemplo, a instrução PUT a seguir retorna um erro, pois não é possível especificar vários arquivos em subdiretórios aninhados.

  PUT file:///tmp/data/** @my_int_stage AUTO_COMPRESS=FALSE;
  

  Copy

• O comando não cria ou renomeia arquivos.

• Todos os arquivos armazenados em estágios internos para operações de carregamento e descarregamento de dados são criptografados automaticamente usando criptografia forte AES-256 no lado do servidor. Por padrão, o Snowflake fornece criptografia adicional do lado do cliente com uma chave de 128 bits (com a opção de configurar uma chave de 256 bits). Para obter mais informações, consulte tipos de criptografia para estágios internos.

• O comando ignora quaisquer arquivos duplicados que você tente carregar para o mesmo estágio. Um arquivo duplicado é um arquivo não modificado com o mesmo nome de um arquivo já preparado.

  Para substituir um arquivo já preparado, você deve modificar o arquivo que está carregando para que seu conteúdo seja diferente do arquivo preparado, o que resulta em uma nova soma de verificação para o novo arquivo preparado.

• Para os comandos PUT e GET, um EXECUTION_STATUS de success em QUERY_HISTORY não significa que os arquivos de dados foram carregados ou baixados com sucesso. Em vez disso, o status indica que o Snowflake recebeu autorização para prosseguir com a transferência do arquivo.

Exemplos¶

PUT file:///tmp/data/mydata.csv @my_int_stage;

PUT file:///tmp/data/orders_001.csv @%orderstiny_ext
  AUTO_COMPRESS = FALSE;

PUT file:///tmp/data/orders_*01.csv @my_int_stage
  AUTO_COMPRESS = FALSE;

PUT 'file:///tmp/data/orders 001.csv' @my_int_stage
  AUTO_COMPRESS = FALSE;

PUT file://C:\temp\data\mydata.csv @~
  AUTO_COMPRESS = TRUE;

PUT 'file://C:/temp/data/my data.csv' @my_int_stage
  AUTO_COMPRESS = TRUE;