PUT

Carregar (ou seja, preparar) arquivos de dados a partir de um diretório/pasta local em uma máquina cliente para um dos seguintes estágios do Snowflake:

  • Estágio interno nomeado.

  • Estágio interno de uma tabela específica.

  • Estágio interno do usuário atual

Uma vez que os arquivos estão preparados, os dados nos arquivos podem ser carregados em uma tabela usando o comando COPY INTO <tabela>.

Nota

  • PUT não oferece suporte ao carregamento de arquivos para estágios externos. Para carregar arquivos para estágios externos, use os utilitários fornecidos pelo serviço de nuvem.

  • O driver ODBC oferece suporte a PUT com contas Snowflake hospedadas nas seguintes plataformas:

    • Amazon Web Services (usando driver ODBC versão 2.17.5 e superior).

    • Google Cloud Platform (usando driver ODBC versão 2.21.5 e superior).

    • Microsoft Azure (usando driver ODBC versão 2.20.2 e superior).

Consulte também:

GET , LIST , REMOVE

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 ]
Copy

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 o(s) arquivo(s) de dados na máquina do cliente, em que:

  • path_to_file é o caminho do diretório local do(s) arquivo(s) a ser(em) carregado(s).

  • filename é o nome do(s) arquivo(s) a ser(em) carregado(s). Os caracteres curinga (*, ?) são suportados para permitir o upload de múltiplos arquivos em um diretório.

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

Linux/macOS

Você deve incluir a barra inicial no caminho (por exemplo, file:///tmp/load).

Se o caminho do diretório e/ou nome do arquivo incluir caracteres especiais, o URI do arquivo inteiro deve ser delimitado por aspas simples.

Windows

Você deve incluir a unidade e a barra invertida no caminho (por exemplo, file://C:\temp\load).

Se o caminho do diretório e/ou nome do arquivo incluir caracteres especiais, o URI do arquivo inteiro deve ser delimitado por aspas simples. Observe que o caractere separador é uma barra (/) em URIs delimitados (por exemplo, 'file://C:/temp/load data' para um caminho no Windows que inclui um diretório chamado 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 e/ou esquema no qual se encontra a tabela ou o estágio interno. É opcional se um banco de dados e um esquema estiverem em uso atualmente na sessão; caso contrário, ele é obrigatório.

  • path é um caminho opcional que distingue letras maiúsculas de minúsculas para arquivos no local de armazenamento em nuvem (ou seja, os arquivos têm nomes que começam com uma cadeia de caracteres comum) 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 caminho incluir espaços ou caracteres especiais, ele deve ser colocado entre aspas simples (por exemplo, '@"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 (em vez de 64 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: os arquivos são comprimidos (se ainda não estiverem comprimidos).

  • FALSE: os arquivos não são comprimidos (ou seja, os arquivos são carregados como estão).

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 (por exemplo, lzip, lzma, lzop e xz) 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 Worksheet tab 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.

  • São suportados os padrões de englobamento (ou seja, curingas).

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

Dica

Por razões de segurança, o comando se esgota após um determinado período. Isto pode ocorrer ao carregar arquivos de dados grandes e não compactados. Para evitar problemas de tempo limite de sessão, recomendamos comprimir grandes arquivos de dados usando um dos tipos de compressão suportados antes de fazer o upload dos arquivos. Em seguida, especificar o tipo de compressão para os arquivos usando a opção SOURCE_COMPRESSION.

Você também pode considerar o aumento do valor da opção PARALLEL, que pode ajudar no desempenho ao carregar grandes arquivos de dados.

Além disso, para aproveitar as operações paralelas ao carregar dados em tabelas (usando o comando COPY INTO <tabela>), recomendamos o uso de arquivos de dados que variam em tamanho de aproximadamente 100 a 250 MB comprimido. Se seus arquivos de dados forem maiores, considere o uso de uma ferramenta de terceiros para dividi-los em arquivos menores antes de compactá-los e carregá-los.

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