COPY FILES¶

Sintaxe¶

Como copiar de um estágio

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM @[<namespace>.]<stage_name>[/<path>/]
  [ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
  [ PATTERN = '<regex_pattern>' ]
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]

Como copiar de uma consulta

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM ( SELECT <existing_url> [ , <new_filename> ] FROM ... )
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]

Parâmetros obrigatórios¶

INTO @[namespace.]stage_name[/path/]

Especifica o local de destino dos arquivos copiados.

• namespace é o banco de dados ou esquema no qual está o estágio interno ou externo, na forma de database_name.schema_name ou schema_name. O namespace é opcional se um banco de dados e esquema estiverem em uso atualmente dentro da sessão do usuário; caso contrário, ele é obrigatório.

• path é um caminho opcional que diferencia maiúsculas de minúsculas no local de armazenamento em nuvem que especifica um conjunto de arquivos a serem copiados do estágio de origem ou de um local específico no estágio de destino. Seu serviço de armazenamento em nuvem pode chamar o caminho de prefixo ou pasta.

Nota

• Se um nome de caminho de destino ou de origem incluir caracteres especiais ou espaços, é necessário colocar o valor INTO ... entre aspas simples.

• Os valores para INTO ... devem ser constantes literais. Os valores não podem ser variáveis de SQL.

Parâmetros opcionais¶

FILES = ( 'file_name' [ , 'file_name' ... ] )

Especifica uma lista de um ou mais nomes de arquivos separados por vírgula para copiar. Os arquivos já devem estar preparados no local de origem especificado no comando. Snowflake ignora todos os arquivos especificados que não podem ser encontrados.

Você pode especificar no máximo 1.000 nomes de arquivo.

Copiar arquivos da consulta não é compatível com essa opção. Em vez disso, use a consulta para fornecer a lista de nomes de arquivo.

Nota

Para definir o caminho do arquivo para estágios externos, o Snowflake acrescenta o URL na definição do estágio a cada nome de arquivo na lista.

No entanto, o Snowflake não insere um separador entre o caminho e o nome do arquivo. Você deve incluir explicitamente um separador (/) no fim do URL na definição do estágio ou no início de cada nome de arquivo na lista FILES.

PATTERN = 'regex_pattern'

Especifica um padrão de expressão regular para filtrar a lista de arquivos a serem copiados. Este comando aplica a expressão regular a todo o local de armazenamento na cláusula FROM.

Copiar arquivos da consulta não é compatível com essa opção. Em vez disso, use a consulta para corresponder ao padrão.

Dica

Para obter melhor desempenho, evite padrões que filtrem um grande número de arquivos.

DETAILED_OUTPUT = { TRUE | FALSE }

Especifica se a saída do comando deve resumir os resultados da operação de cópia ou listar cada arquivo copiado.

Valores:

• Se TRUE, a saída incluirá uma linha para cada arquivo copiado no local de destino. Uma única coluna chamada file contém o caminho de destino (se aplicável) e o nome do arquivo para cada arquivo copiado.

• Se FALSE, a saída será uma única linha com o número de arquivos que foram copiados.

Padrão:

TRUE

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios (dependendo dos locais de origem e destino) no mínimo:

O privilégio USAGE no banco de dados e no esquema pai é necessário para executar operações em qualquer objeto de um esquema.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

• Esse comando não é compatível com o seguinte:

  • Cópia de arquivos para ou de estágios de tabela.

  • Ao usar um estágio como fonte, a cópia de arquivos de ou para os estágios de usuário.

  • Cópia de dados em classes de armazenamento em nuvem de arquivo que exigem restauração antes de serem recuperados. As classes de armazenamento de arquivos incluem Amazon S3 Glacier Flexible Retrieval, Glacier Deep Archive ou Microsoft Azure Archive Storage.

  • Copiando arquivos maiores que 5GB.

• Considerações para executar este comando:

  • As instruções COPY FILES substituem quaisquer arquivos existentes com nomes correspondentes no local de destino. O comando não remove nenhum arquivo existente que não corresponda aos nomes dos arquivos copiados.

  • Se uma operação de cópia de arquivo falhar, o Snowflake não realizará nenhuma limpeza automática.

  • Copiar arquivos do Google Cloud Storage: uma instrução COPY FILES poderá falhar se a lista de objetos de um estágio externo incluir um ou mais blobs de diretório. Um blob de diretório é um caminho que termina com uma barra (/). Na saída de exemplo a seguir para LIST @<stage>, my_gcs_stage/load/ é um blob de diretório.

    +---------------------------------------+------+----------------------------------+-------------------------------+
    | name                                  | size | md5                              | last_modified                 |
    |---------------------------------------+------+----------------------------------+-------------------------------|
    | my_gcs_stage/load/                    |  12  | 12348f18bcb35e7b6b628ca12345678c | Mon, 11 Aug 2022 16:57:43 GMT |
    | my_gcs_stage/load/data_0_0_0.csv.gz   |  147 | 9765daba007a643bdff4eae10d43218y | Mon, 11 Aug 2022 18:13:07 GMT |
    +---------------------------------------+------+----------------------------------+-------------------------------+
    

    O Google cria blobs de diretório quando você usa o console do Google Cloud para criar um diretório.

    Para evitar esse problema e especificar quais arquivos devem ser copiados, use a opção PATTERN (para copiar do estágio) ou FROM (para copiar da consulta).

    Para obter um exemplo, consulte Cópia de arquivos usando correspondência de padrões.

• O comando COPY FILES incorre em custos de transferência de dados e computação:

  • Transferência de dados: os provedores de nuvem podem cobrar pelos dados transferidos de sua própria rede. Para recuperar essas despesas, o Snowflake cobra uma taxa por byte quando você copia arquivos de um estágio interno do Snowflake para um estágio externo em uma região diferente ou com um provedor de nuvem diferente. O Snowflake não cobra pela entrada de dados (por exemplo, ao copiar arquivos de um estágio externo para um estágio interno).

    Para obter mais informações sobre faturamento por transferência de dados, consulte Explicação do custo de transferência de dados.

  • Computar: COPY FILES é um recurso sem servidor e não requer um warehouse virtual. O item de linha do comando COPY FILES na sua fatura do Snowflake não inclui nenhuma cobrança de serviços de nuvem.

    Para obter mais informações sobre o faturamento de recursos de computação, consulte Explicação dos custos de computação.

  Nota

  Alguns recursos do Snowflake, como Native Apps e planilhas, geram cobranças de COPY FILES. Como resultado, você poderá ver cobranças de COPY FILES, mesmo que não tenha executado o comando COPY FILES. Para obter mais informações sobre essas cobranças, entre em contato com o suporte Snowflake.

• Snowflake não mantém um histórico de cópia de arquivo para este comando.

Exemplos¶

COPY FILES
  INTO @trg_stage
  FROM @src_stage;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  FILES = ('file1.csv', 'file2.csv');

COPY FILES
  INTO @trg_stage/trg_path/
  FROM @src_stage/src_path/;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*/.*/.*[.]csv[.]gz';

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*sales.*[.]csv';

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt');

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt', 'new_filename.txt');

-- Create a table with URLs
CREATE TABLE urls(src_file STRING, trg_file STRING);
INSERT INTO urls VALUES ('@src_stage/file.txt', 'new_filename.txt');

-- Insert additional URLs here
COPY FILES
  INTO @trg_stage
  FROM (SELECT src_file, trg_file FROM urls);

COPY FILES
  INTO @trg_stage
  FROM (SELECT src_file, trg_file FROM urls WHERE src_file LIKE '%file%');

COPY FILES
  INTO @trg_stage
  FROM (SELECT relative_path FROM directory(@src_stage) WHERE relative_path LIKE '%.txt');