COPY FILES¶

Sintaxe¶

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

Parâmetros obrigatórios¶

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

Especifica o local de destino dos arquivos copiados.

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

Especifica o local de origem onde os arquivos a serem copiados são preparados.

Para os parâmetros INTO e FROM:

• 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 origem incluir caracteres especiais ou espaços, você deverá colocar o valor INTO ... ou FROM ... entre aspas simples.

  • Os valores para INTO ... e FROM ... 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.

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.

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:

Observe que operar em qualquer objeto de um esquema também requer o privilégio USAGE no banco de dados e esquema principais.

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 de ou para estágios de usuário ou tabela.

  • 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, use a opção PATTERN para especificar quais arquivos copiar. 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';