PUT¶

Sintaxe¶

PUT file://<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://path_to_file/filename

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

• 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.

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

Linux/macOS:

Você deve incluir a barra inicial no caminho. Por exemplo, para um arquivo chamado load use file:///tmp/load.

Windows:

Você deve incluir a unidade e a barra invertida no caminho e substituir os caracteres de barra invertida por barras. Por exemplo, para um arquivo chamado load data use file://C:/temp/load data.

internalStage

Especifica o local no Snowflake onde carregar os 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 da tabela especificada.
@~[/path]	Os arquivos são carregados no estágio do 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 processo de upload separa os lotes de arquivos de dados por tamanho:

• Pequenos arquivos (<64 MB, comprimidos ou não) 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 carregar arquivos comprimidos com Brotli, use explicitamente BROTLI em vez de AUTO_DETECT.
GZIP
BZ2
BROTLI	Deve ser usado se carregar arquivos comprimidos com 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 a serem carregados 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 carregamento; ele não usa esta opção para comprimir os arquivos.

O upload de arquivos que foram comprimidos com outras recursos não é suportado atualmente.

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.

  Observe que uma operação LIST no estágio é realizada em segundo plano, o que pode afetar o desempenho da operação PUT.

  Se as tentativas de PUT um arquivo falhar porque existe um arquivo com o mesmo nome no estágio de destino, as seguintes opções estão disponíveis:

  • Carregar os dados do arquivo existente em uma ou mais tabelas, e remover o arquivo do estágio. Depois 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 realmente seguro substituir um arquivo por dados que talvez ainda não tenham sido carregados no Snowflake.

Observe que se sua conta Snowflake estiver hospedada no Google Cloud Platform, as instruções PUT não reconhecem quando o parâmetro OVERWRITE é definido como TRUE. Uma operação PUT sempre substitui quaisquer arquivos existentes no estágio de destino pelos arquivos locais que você está carregando.

Os seguintes clientes oferecem suporte à opção OVERWRITE para contas Snowflake hospedadas no Amazon Web Services ou no 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.

• O comando não suporta o upload de vários arquivos com caminhos de diretório divergentes, porque não preserva a estrutura de diretórios do sistema de arquivos ao fazer upload de arquivos para seu 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

• 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 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.

Exemplos¶

Carregar um arquivo chamado mydata.csv no diretório /tmp/data (em um ambiente Linux ou macOS) em um estágio interno chamado my_int_stage:

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

Copy

Carregar um arquivo chamado orders_001.csv no diretório /tmp/data (em um ambiente Linux ou macOS) no estágio da tabela orderstiny_ext, com a compressão automática de dados desabilitada:

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

Copy

O mesmo exemplo como acima, mas usando caracteres curinga no nome do arquivo para carregar vários arquivos:

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

Copy

Carregar um arquivo chamado mydata.csv no diretório C:\temp\data (em um ambiente Windows) no estágio do usuário atual, com a compressão automática de dados habilitada:

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

Copy

Como o exemplo anterior, mas carregando o arquivo do diretório C:\temp\load data (em um ambiente Windows):

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

Copy