COPY INTO <tabela>

Carrega dados de arquivos preparados em uma tabela existente. Os arquivos já devem ser preparados em um dos seguintes locais:

  • Estágio interno nomeado (ou estágio de tabela/usuário). Os arquivos podem ser preparados usando o comando PUT.

  • Estágio externo nomeado que faz referência a um local externo (Amazon S3, Google Cloud Storage ou Microsoft Azure).

    Não é possível acessar dados mantidos em classes de armazenamento em nuvem que exigem restauração antes que possam ser recuperados. Estas classes de armazenamento de arquivos incluem, por exemplo, a Amazon S3 Glacier Flexible Retrieval ou Glacier Deep Archive, o ainda o Microsoft Azure Archive Storage.

  • Local externo (Amazon S3, Google Cloud Storage ou Microsoft Azure).

Consulte também:

COPY INTO <local>

Sintaxe

/* Standard data load */
COPY INTO [<namespace>.]<table_name>
     FROM { internalStage | externalStage | externalLocation }
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
                    TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
[ copyOptions ]
[ VALIDATION_MODE = RETURN_<n>_ROWS | RETURN_ERRORS | RETURN_ALL_ERRORS ]

/* Data load with transformation */
COPY INTO [<namespace>.]<table_name> [ ( <col_name> [ , <col_name> ... ] ) ]
     FROM ( SELECT [<alias>.]$<file_col_num>[.<element>] [ , [<alias>.]$<file_col_num>[.<element>] ... ]
            FROM { internalStage | externalStage } )
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
                    TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
[ copyOptions ]
Copy

Onde:

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>[/<path>]
  | @~[/<path>]
Copy
externalStage ::=
  @[<namespace>.]<ext_stage_name>[/<path>]
Copy
externalLocation (for Amazon S3) ::=
  's3://<bucket>[/<path>]'
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( {  { AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' [ AWS_TOKEN = '<string>' ] } } ) } ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] |
                   [ TYPE = 'AWS_SSE_S3' ] |
                   [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] |
                   [ TYPE = 'NONE' ] ) ]
Copy
externalLocation (for Google Cloud Storage) ::=
  'gcs://<bucket>[/<path>]'
  [ STORAGE_INTEGRATION = <integration_name> ]
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = 'NONE' ] ) ]
Copy
externalLocation (for Microsoft Azure) ::=
  'azure://<account>.blob.core.windows.net/<container>[/<path>]'
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( [ AZURE_SAS_TOKEN = '<string>' ] ) } ]
  [ ENCRYPTION = ( [ TYPE = { 'AZURE_CSE' | 'NONE' } ] [ MASTER_KEY = '<string>' ] ) ]
Copy
formatTypeOptions ::=
-- If FILE_FORMAT = ( TYPE = CSV ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     RECORD_DELIMITER = '<character>' | NONE
     FIELD_DELIMITER = '<character>' | NONE
     PARSE_HEADER = TRUE | FALSE
     SKIP_HEADER = <integer>
     SKIP_BLANK_LINES = TRUE | FALSE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     ESCAPE = '<character>' | NONE
     ESCAPE_UNENCLOSED_FIELD = '<character>' | NONE
     TRIM_SPACE = TRUE | FALSE
     FIELD_OPTIONALLY_ENCLOSED_BY = '<character>' | NONE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
     ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     EMPTY_FIELD_AS_NULL = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
     ENCODING = '<string>' | UTF8
-- If FILE_FORMAT = ( TYPE = JSON ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
     ENABLE_OCTAL = TRUE | FALSE
     ALLOW_DUPLICATE = TRUE | FALSE
     STRIP_OUTER_ARRAY = TRUE | FALSE
     STRIP_NULL_VALUES = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     IGNORE_UTF8_ERRORS = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
-- If FILE_FORMAT = ( TYPE = AVRO ... )
     COMPRESSION = AUTO | GZIP | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If FILE_FORMAT = ( TYPE = ORC ... )
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If FILE_FORMAT = ( TYPE = PARQUET ... )
     COMPRESSION = AUTO | SNAPPY | NONE
     BINARY_AS_TEXT = TRUE | FALSE
     USE_LOGICAL_TYPE = TRUE | FALSE
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If FILE_FORMAT = ( TYPE = XML ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     IGNORE_UTF8_ERRORS = TRUE | FALSE
     PRESERVE_SPACE = TRUE | FALSE
     STRIP_OUTER_ELEMENT = TRUE | FALSE
     DISABLE_SNOWFLAKE_DATA = TRUE | FALSE
     DISABLE_AUTO_CONVERT = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
Copy
copyOptions ::=
     ON_ERROR = { CONTINUE | SKIP_FILE | SKIP_FILE_<num> | 'SKIP_FILE_<num>%' | ABORT_STATEMENT }
     SIZE_LIMIT = <num>
     PURGE = TRUE | FALSE
     RETURN_FAILED_ONLY = TRUE | FALSE
     MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
     ENFORCE_LENGTH = TRUE | FALSE
     TRUNCATECOLUMNS = TRUE | FALSE
     FORCE = TRUE | FALSE
     LOAD_UNCERTAIN_FILES = TRUE | FALSE
Copy

Parâmetros obrigatórios

[namespace.]table_name

Especifica o nome da tabela na qual os dados são carregados.

O namespace especifica opcionalmente o banco de dados e/ou esquema para a tabela, na forma de database_name.schema_name ou schema_name. É opcional se um banco de dados e um esquema estiverem em uso atualmente dentro da sessão do usuário; caso contrário, ele é obrigatório.

FROM ...

Especifica o local interno ou externo onde os arquivos contendo os dados a serem carregados são preparados:

@[namespace.]int_stage_name[/path]

Os arquivos estão no estágio interno nomeado especificado.

@[namespace.]ext_stage_name[/path]

Os arquivos estão no estágio externo nomeado especificado.

@[namespace.]%table_name[/path]

Os arquivos estão no estágio para a tabela especificada.

@~[/path]

Os arquivos estão no estágio para o usuário atual.

's3://bucket[/path]'

Os arquivos estão no local externo especificado (bucket S3). Parâmetros adicionais podem ser necessários. Para obter mais detalhes, consulte Parâmetros adicionais do provedor de nuvem (neste tópico).

'gcs://bucket[/path]'

Os arquivos estão no local externo especificado (Google Cloud Storage Bucket). Parâmetros adicionais podem ser necessários. Para obter mais detalhes, consulte Parâmetros adicionais do provedor de nuvem (neste tópico).

'azure://account.blob.core.windows.net/container[/path]'

Os arquivos estão no local externo especificado (contêiner Azure). Parâmetros adicionais podem ser necessários. Para obter mais detalhes, consulte Parâmetros adicionais do provedor de nuvem (neste tópico).

Onde:

  • namespace é o banco de dados e/ou esquema no qual está o estágio interno ou externo, na forma de database_name.schema_name ou schema_name. É opcional se um banco de dados e um esquema estiverem em uso atualmente dentro da sessão do usuário; 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 carregamento do conjunto de arquivos. Os caminhos são chamados alternativamente de prefixos ou pastas por diferentes serviços de armazenamento em nuvem.

    Os modificadores de caminhos relativos como /./ e /../ são interpretados literalmente porque «caminhos» são prefixos literais para um nome. Por exemplo:

    -- S3 bucket
    COPY INTO mytable FROM 's3://mybucket/./../a.csv';
    
    -- Google Cloud Storage bucket
    COPY INTO mytable FROM 'gcs://mybucket/./../a.csv';
    
    -- Azure container
    COPY INTO mytable FROM 'azure://myaccount.blob.core.windows.net/mycontainer/./../a.csv';
    
    Copy

    Nestas instruções COPY, o Snowflake procura por um arquivo literalmente chamado ./../a.csv no local externo.

Nota

  • Se o estágio interno ou externo ou o nome do caminho incluir caracteres especiais, incluindo espaços, delimite a cadeia de caracteres FROM ... com aspas simples.

  • O valor FROM ... deve ser uma constante literal. O valor não pode ser uma variável SQL.

Parâmetros adicionais do provedor de nuvem

STORAGE_INTEGRATION = integration_name ou . CREDENTIALS = ( cloud_specific_credentials )

Suportado quando o valor FROM na instrução COPY for um armazenamento externo URI em vez de um nome de estágio externo.

Necessário apenas para carregamento de um local externo de armazenamento privado/protegido em nuvem; não necessário para buckets/contêineres públicos

Especifica as credenciais de segurança para se conectar ao provedor da nuvem e acessar o contêiner de armazenamento privado/protegido onde os arquivos de dados são preparados.

Amazon S3

STORAGE_INTEGRATION = integration_name

Especifica o nome da integração de armazenamento utilizada para delegar a responsabilidade de autenticação do armazenamento em nuvem externo a uma entidade de gerenciamento de identidade e acesso (IAM) do Snowflake. Para obter mais detalhes, consulte CREATE STORAGE INTEGRATION.

Nota

Recomendamos fortemente o uso de integrações de armazenamento. Esta opção evita a necessidade de fornecer credenciais de armazenamento em nuvem usando o parâmetro CREDENTIALS ao criar estágios ou carregar dados.

CREDENTIALS = ( AWS_KEY_ID = 'string' AWS_SECRET_KEY = 'string' [ AWS_TOKEN = 'string' ] )

Especifica as credenciais de segurança para conexão com AWS e acesso ao bucket privado/protegido S3 onde os arquivos a serem carregados são preparados. Para obter mais informações, consulte Configuração de acesso seguro ao Amazon S3.

As credenciais especificadas dependerão da associação das permissões de acesso do Snowflake para o bucket com um usuário ou função do AWS IAM (Identity & Access Management):

  • Usuário IAM: credenciais temporárias de IAM são necessárias. As credenciais temporárias (também conhecidas como «com escopo») são geradas por AWS Security Token Service (STS) e consiste em três componentes:

    • AWS_KEY_ID

    • AWS_SECRET_KEY

    • AWS_TOKEN

    Todos os três são obrigatórios para ter acesso a um bucket privado/protegido. Após um período designado, as credenciais temporárias expiram e não podem mais ser utilizadas. Você deve então gerar um novo conjunto de credenciais temporárias válidas.

    Importante

    Os comandos COPY possuem uma sintaxe complexa e informações sensíveis, tais como credenciais. Além disso, elas são executadas com frequência e são geralmente armazenadas em scripts ou planilhas, o que pode fazer com que informações sensíveis sejam inadvertidamente expostas. O comando COPY permite o uso de credenciais permanentes (ou «de longo prazo»); no entanto, por razões de segurança, não use credenciais permanentes nos comandos COPY. Em vez disso, use credenciais temporárias.

    Se você tiver que usar credenciais permanentes, use estágios externos, para os quais as credenciais são inseridas uma vez e armazenadas com segurança, minimizando o potencial de exposição.

  • Função IAM: omitir as credenciais de segurança e chaves de acesso e, em vez disso, identificar a função usando AWS_ROLE e especificar a função AWS ARN (Amazon Resource Name).

Google Cloud Storage

STORAGE_INTEGRATION = integration_name

Especifica o nome da integração de armazenamento utilizada para delegar a responsabilidade de autenticação do armazenamento em nuvem externo a uma entidade de gerenciamento de identidade e acesso (IAM) do Snowflake. Para obter mais detalhes, consulte CREATE STORAGE INTEGRATION.

Microsoft Azure

STORAGE_INTEGRATION = integration_name

Especifica o nome da integração de armazenamento utilizada para delegar a responsabilidade de autenticação do armazenamento em nuvem externo a uma entidade de gerenciamento de identidade e acesso (IAM) do Snowflake. Para obter mais detalhes, consulte CREATE STORAGE INTEGRATION.

Nota

Recomendamos fortemente o uso de integrações de armazenamento. Esta opção evita a necessidade de fornecer credenciais de armazenamento em nuvem usando o parâmetro CREDENTIALS ao criar estágios ou carregar dados.

CREDENTIALS = ( AZURE_SAS_TOKEN = 'string' )

Especifica o símbolo SAS (assinatura de acesso compartilhado) para conexão com o Azure e acesso ao contêiner privado/protegido onde os arquivos contendo os dados são preparados. As credenciais são geradas pelo Azure.

ENCRYPTION = ( cloud_specific_encryption )

Para uso em instruções COPY ad hoc (instruções que não fazem referência a um estágio externo nomeado). Necessário apenas para carregamento de arquivos criptografados; não necessário se os arquivos não forem criptografados. Especifica as configurações de criptografia usadas para descriptografar arquivos criptografados no local de armazenamento.

Amazon S3

ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] | [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] | [ TYPE = 'NONE' ] )

TYPE = ...

Especifica o tipo de criptografia utilizado. Os valores possíveis são:

  • AWS_CSE: criptografia do lado do cliente (exige um valor MASTER_KEY). Atualmente, a chave mestra do lado do cliente que você fornece só pode ser uma chave simétrica. Note que, quando um valor MASTER_KEY é fornecido, o Snowflake assume TYPE = AWS_CSE (ou seja, quando um valor MASTER_KEY é fornecido, TYPE não é necessário).

  • AWS_SSE_S3: criptografia do lado do servidor que não exige configurações adicionais de criptografia.

  • AWS_SSE_KMS: criptografia do lado do servidor que aceita um valor opcional KMS_KEY_ID.

  • NONE: sem criptografia.

Para obter mais informações sobre os tipos de criptografia, consulte a documentação do AWS sobre criptografia do lado do cliente ou criptografia do lado do servidor.

MASTER_KEY = 'string' (aplica-se somente à criptografia AWS_CSE)

Especifica a chave mestra do lado do cliente utilizada para criptografar os arquivos no bucket. A chave mestra deve ser uma chave de 128 bits ou 256 bits na forma codificada em Base64.

KMS_KEY_ID = 'string' (aplica-se somente à criptografia AWS_SSE_KMS)

Opcionalmente especifica a ID para a chave AWS gerenciada por KMS usada para criptografar arquivos descarregados no bucket. Se nenhum valor for fornecido, sua ID de chave KMS é usada para criptografar arquivos ao descarregar.

Observe que este valor é ignorado para o carregamento de dados.

Google Cloud Storage

ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' | 'NONE' ] [ KMS_KEY_ID = 'string' ] )

TYPE = ...

Especifica o tipo de criptografia utilizado. Os valores possíveis são:

KMS_KEY_ID = 'string' (aplica-se somente à criptografia GCS_SSE_KMS)

Opcionalmente, especifica a ID da chave gerenciada por KMS da nuvem que é usada para criptografar arquivos descarregados no bucket. Se nenhum valor for fornecido, sua ID de chave padrão KMS definida no bucket é usada para criptografar arquivos ao descarregar.

Observe que este valor é ignorado para o carregamento de dados. A operação de carregamento deve ser bem sucedida se a conta de serviço tiver permissões suficientes para descriptografar os dados no bucket.

Microsoft Azure

ENCRYPTION = ( [ TYPE = 'AZURE_CSE' | 'NONE' ] [ MASTER_KEY = 'string' ] )

TYPE = ...

Especifica o tipo de criptografia utilizado. Os valores possíveis são:

MASTER_KEY = 'string' (aplica-se somente à criptografia AZURE_CSE)

Especifica a chave mestra do lado do cliente usada para descriptografar arquivos. A chave mestra deve ser uma chave de 128 bits ou 256 bits na forma codificada em Base64.

Parâmetros de transformação

( SELECT [alias.]$file_col_num[.element] [ , [alias.]$file_col_num[.element] ... ] FROM ... [ alias ] )

Necessário para transformar os dados durante o carregamento

Especifica um conjunto explícito de campos/colunas (separados por vírgulas) a ser carregado a partir dos arquivos de dados preparados. Os campos/colunas são selecionados a partir dos arquivos usando uma consulta padrão SQL (ou seja, lista SELECT), onde:

alias

Especifica um alias opcional para o valor FROM (por exemplo, d em COPY INTO t1 (c1) FROM (SELECT d.$1 FROM @mystage/file1.csv.gz d);).

file_col_num

Especifica o número posicional do campo/coluna (no arquivo) que contém os dados a serem carregados (1 para o primeiro campo, 2 para o segundo campo etc.)

element

Especifica o caminho e o nome do elemento de um valor de repetição no arquivo de dados (aplica-se somente aos arquivos de dados semiestruturados).

A lista SELECT define um conjunto de campos/colunas numeradas nos arquivos de dados dos quais você está carregando. A lista deve corresponder à sequência de colunas na tabela de destino. Você pode usar o parâmetro opcional ( col_name [ , col_name ... ] ) para mapear a lista para colunas específicas na tabela de destino.

Observe que a ordem real do campo/coluna nos arquivos de dados pode ser diferente da ordem da coluna na tabela de destino. É importante apenas que a lista SELECT mapeie os campos/colunas nos arquivos de dados para as colunas correspondentes da tabela.

Nota

A instrução SELECT utilizada para as transformações não oferece suporte a todas as funções. Para uma lista completa das funções suportadas e mais detalhes sobre transformações de carregamento de dados, incluindo exemplos, consulte as notas de uso em Transformação de dados durante um carregamento.

Além disso, a transformação de carregamento de dados oferece suporte à seleção de dados de estágios do usuário e estágios nomeadas (internos ou externos).

( col_name [ , col_name ... ] )

Opcionalmente especifica uma lista explícita de colunas da tabela (separadas por vírgulas) nas quais você deseja inserir dados:

  • A primeira coluna consome os valores produzidos a partir do primeiro campo/coluna extraído dos arquivos carregados.

  • A segunda coluna consome os valores produzidos do segundo campo/coluna extraídos dos arquivos carregados.

  • E assim por diante, na ordem especificada.

As colunas não podem ser repetidas nesta listagem. Quaisquer colunas excluídas desta lista de colunas são preenchidas com seu valor padrão (NULL, se não especificado). No entanto, as colunas excluídas não podem ter uma sequência como valor padrão.

Parâmetros opcionais

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

Especifica uma lista de um ou mais nomes de arquivos (separados por vírgulas) a serem carregados. Os arquivos já devem ter sido preparados no local interno do Snowflake ou no local externo especificado no comando. Se algum dos arquivos especificados não puder ser encontrado, o comportamento padrão ON_ERROR = ABORT_STATEMENT aborta a operação de carregamento a menos que uma opção diferente ON_ERROR seja explicitamente definida na instrução COPY.

O número máximo de nomes de arquivos que podem ser especificados é 1.000.

Nota

Somente para estágios externos (Amazon S3, Google Cloud Storage ou Microsoft Azure), o caminho do arquivo é definido concatenando o URL na definição do estágio e a lista de nomes de arquivos resolvidos.

No entanto, o Snowflake não insere um separador implícito entre o caminho e os nomes dos arquivos. Você deve incluir explicitamente um separador (/) no final do URL na definição do estágio ou no início de cada nome de arquivo especificado neste parâmetro.

PATTERN = 'regex_pattern'

Uma cadeia de caracteres de padrões de expressão regular, delimitada por aspas simples, especificando os nomes dos arquivos e/ou caminhos a serem combinados.

Dica

Para o melhor desempenho, tente evitar a aplicação de padrões que filtram em um grande número de arquivos.

Observe que a expressão regular é aplicada de forma diferente a carregamentos de dados em massa versus carregamentos de dados Snowpipe.

  • O Snowpipe reduz qualquer segmento do caminho na definição do estágio a partir do local de armazenamento e aplica a expressão regular a quaisquer segmentos de caminho e nomes de arquivo restantes. Para ver a definição do estágio, execute o comando DESCRIBE STAGE para o estágio. A propriedade do URL consiste no nome do bucket ou contêiner e zero ou mais segmentos de caminho. Por exemplo, se o local FROM em uma instrução COPY INTO <tabela> for @s/path1/path2/ e o valor do URL para o estágio @s for s3://mybucket/path1/, o Snowpipe reduzirá o /path1/ do local de armazenamento na cláusula FROM e aplicará a expressão regular a path2/ mais os nomes dos arquivos no caminho.

  • As operações de carregamento de dados em massa aplicam a expressão regular a todo o local de armazenamento na cláusula FROM.

FILE_FORMAT = ( FORMAT_NAME = 'file_format_name' ) ou . FILE_FORMAT = ( TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ] )

Especifica o formato dos arquivos de dados a serem carregados:

FORMAT_NAME = 'file_format_name'

Especifica um formato de arquivo nomeado existente a ser usado para carregar dados na tabela. O formato do arquivo nomeado determina o tipo de formato (CSV, JSON etc.), bem como quaisquer outras opções de formato, para os arquivos de dados. Para obter mais informações, consulte CREATE FILE FORMAT.

TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ]

Especifica o tipo de arquivos a serem carregados na tabela. Se um tipo de formato for especificado, então opções adicionais específicas de formato podem ser especificadas. Para obter mais detalhes, consulte Opções do tipo de formato (neste tópico).

Nota

FORMAT_NAME e TYPE são mutuamente exclusivos; especificar ambos no mesmo comando COPY pode resultar em comportamento inesperado.

COPY_OPTIONS = ( ... )

Especifica uma ou mais opções de cópia para os dados carregados. Para obter mais detalhes, consulte Opções de cópia (neste tópico).

VALIDATION_MODE = RETURN_n_ROWS | RETURN_ERRORS | RETURN_ALL_ERRORS

String (constante) que instrui o comando COPY a validar os arquivos de dados em vez de carregá-los na tabela especificada; ou seja, o comando COPY testa os arquivos quanto a erros, mas não os carrega. O comando valida os dados a serem carregados e retorna os resultados com base na opção de validação especificada:

Valores suportados

Notas

RETURN_n_ROWS (por exemplo, RETURN_10_ROWS)

Valida o número especificado de linhas se não forem encontrados erros; caso contrário, falha no primeiro erro encontrado nas linhas.

RETURN_ERRORS

Devolve todos os erros (análise, conversão etc.) em todos os arquivos especificados na instrução COPY.

RETURN_ALL_ERRORS

Devolve todos os erros em todos os arquivos especificados na instrução COPY, incluindo arquivos com erros que foram parcialmente carregados durante um carregamento anterior, porque a opção de cópia ON_ERROR foi definida como CONTINUE durante o carregamento.

Nota

  • VALIDATION_MODE não oferece suporte a instruções COPY que transformam dados durante um carregamento. Se o parâmetro for especificado, a instrução COPY retorna um erro.

  • Use a função de tabela VALIDATE para visualizar todos os erros encontrados durante um carregamento anterior. Note que esta função também não oferece suporte a instruções COPY que transformam dados durante um carregamento.

Opções de tipo de formato (formatTypeOptions)

Dependendo do tipo de formato de arquivo especificado (FILE_FORMAT = ( TYPE = ... )), você pode incluir uma ou mais das seguintes opções de formato específicas (separadas por espaços em branco, vírgulas ou novas linhas):

TYPE = CSV

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

String (constante) que especifica o algoritmo de compressão atual para os arquivos de dados a serem carregados. O Snowflake usa esta opção para detectar como os arquivos de dados já comprimidos foram comprimidos para que os dados comprimidos nos arquivos possam ser extraídos para carregamento.

Valores suportados

Notas

AUTO

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.

GZIP

BZ2

BROTLI

Deve ser especificado ao 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.

RECORD_DELIMITER = 'character' | NONE

Um ou mais caracteres que separam registros em um arquivo de entrada. Aceita sequências de escape comuns ou os seguintes caracteres de byte único ou multibyte:

Caracteres de byte único:

Valores octais (com prefixo \\) ou valores hexadecimais (com prefixo 0x ou \x). Por exemplo, para registros delimitados por acento circunflexo (^), especifique o valor octal (\\136) ou hexadecimal (0x5e).

Caracteres multibyte:

Valores hexadecimais (com prefixo \x). Por exemplo, para registros delimitados pelo caractere de centavo (¢), especifique o valor hexadecimal (\xC2\xA2).

O delimitador para RECORD_DELIMITER ou FIELD_DELIMITER não pode ser um substrato do delimitador para a outra opção de formato do arquivo (por exemplo, FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb').

O delimitador especificado deve ser um caractere válido UTF-8 e não uma sequência aleatória de bytes. Observe também que o delimitador é limitado a um máximo de 20 caracteres.

Também aceita um valor de NONE.

Padrão: caractere de nova linha Note que «nova linha» é lógica de tal forma que \r\n é entendido como uma nova linha para arquivos em uma plataforma Windows.

FIELD_DELIMITER = 'character' | NONE

Um ou mais caracteres de byte único ou multibyte que separam os campos em um arquivo de entrada. Aceita sequências de escape comuns ou os seguintes caracteres de byte único ou multibyte:

Caracteres de byte único:

Valores octais (com prefixo \\) ou valores hexadecimais (com prefixo 0x ou \x). Por exemplo, para registros delimitados por acento circunflexo (^), especifique o valor octal (\\136) ou hexadecimal (0x5e).

Caracteres multibyte:

Valores hexadecimais (com prefixo \x). Por exemplo, para registros delimitados pelo caractere de centavo (¢), especifique o valor hexadecimal (\xC2\xA2).

O delimitador para RECORD_DELIMITER ou FIELD_DELIMITER não pode ser um substrato do delimitador para a outra opção de formato do arquivo (por exemplo, FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb').

Nota

Para caracteres não ASCII, você deve usar o valor da sequência de bytes hexadecimais para obter um comportamento determinístico.

O delimitador especificado deve ser um caractere válido UTF-8 e não uma sequência aleatória de bytes. Observe também que o delimitador é limitado a um máximo de 20 caracteres.

Também aceita um valor de NONE.

Padrão: vírgula (,)

PARSE_HEADER = TRUE | FALSE

Booleano que especifica se deve usar os cabeçalhos da primeira linha nos arquivos de dados para determinar os nomes das colunas.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Detecção automática de definições de coluna usando a função INFER_SCHEMA.

  • Carregamento de dados CSV em colunas separadas usando a função INFER_SCHEMA e a opção de cópia MATCH_BY_COLUMN_NAME.

Se a opção estiver definida como TRUE, os cabeçalhos da primeira linha serão usados para determinar os nomes das colunas. O valor padrão FALSE retornará os nomes das colunas como c , onde é a posição da coluna.

Observe que a opção SKIP_HEADER não é suportada com PARSE_HEADER = TRUE.

Padrão: FALSE

SKIP_HEADER = integer

Número de linhas no início do arquivo a ser pulado.

Observe que SKIP_HEADER não usa os valores RECORD_DELIMITER ou FIELD_DELIMITER para determinar o que é uma linha de cabeçalho; em vez disso, simplesmente ignora o número especificado de linhas delimitadas de CRLF (Carriage Return, Line Feed) no arquivo. RECORD_DELIMITER e FIELD_DELIMITER são então usados para determinar as linhas de dados a serem carregadas.

Padrão: 0

SKIP_BLANK_LINES = TRUE | FALSE
Uso:

Somente carregamento de dados

Definição:

Booleano que especifica ignorar quaisquer linhas em branco encontradas nos arquivos de dados; caso contrário, linhas em branco produzem um erro de fim de registro (comportamento padrão).

Padrão: FALSE

DATE_FORMAT = 'string' | AUTO

String que define o formato dos valores de data nos arquivos de dados a serem carregados. Se um valor não for especificado ou for AUTO, é usado o valor para o parâmetro da sessão DATE_INPUT_FORMAT.

Padrão: AUTO

TIME_FORMAT = 'string' | AUTO

String que define o formato dos valores de hora nos arquivos de dados a serem carregados. Se um valor não for especificado ou for AUTO, é usado o valor para o parâmetro da sessão TIME_INPUT_FORMAT.

Padrão: AUTO

TIMESTAMP_FORMAT = 'string' | AUTO

String que define o formato dos valores de carimbo de data/hora nos arquivos de dados a serem carregados. Se um valor não for especificado ou for AUTO, é usado o valor para o parâmetro da sessão TIMESTAMP_INPUT_FORMAT.

Padrão: AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

String (constante) que define o formato de codificação para entrada ou saída binária. Esta opção só se aplica ao carregamento de dados em colunas binárias em uma tabela.

Padrão: HEX

ESCAPE = 'character' | NONE
Uso:

Carregamento e descarregamento de dados

Definição:

Um caractere de byte único usado como caractere de escape apenas para valores de campo delimitado. Um caractere de escape invoca uma interpretação alternativa em caracteres subsequentes em uma sequência de caracteres. Você pode usar o caractere ESCAPE para interpretar instâncias do caractere FIELD_OPTIONALLY_ENCLOSED_BY nos dados como literais.

Aceita sequências de escape comuns (por exemplo, \t para guia, \n para nova linha, \r para retorno de carro, \\ para contrabarra), valores octais ou valores hexadecimais.

Nota

Esta opção de formato de arquivo oferece suporte somente a caracteres de byte único. Observe que a codificação de caractere UTF-8 representa caracteres ASCII de ordem superior como caracteres multibyte. Se seu arquivo de dados for codificado com o conjunto de caracteres UTF-8, você não poderá especificar um caractere ASCII de ordem superior como o valor da opção.

Além disso, se você especificar um caractere ASCII de ordem superior, recomendamos que você defina a opção de formato de arquivo ENCODING = 'string' como a codificação de caracteres para seus arquivos de dados para garantir que o caractere seja interpretado corretamente.

Padrão:

NONE

ESCAPE_UNENCLOSED_FIELD = 'character' | NONE
Uso:

Carregamento e descarregamento de dados

Definição:

Um caractere de byte único usado como caractere de escape apenas para valores de campo não delimitados. Um caractere de escape invoca uma interpretação alternativa em caracteres subsequentes em uma sequência de caracteres. Você pode usar o caractere ESCAPE para interpretar instâncias dos caracteres FIELD_DELIMITER ou RECORD_DELIMITER nos dados como literais. O caractere de escape também pode ser usado para escapar de instâncias de si mesmo nos dados.

Aceita sequências de escape comuns (por exemplo, \t para guia, \n para nova linha, \r para retorno de carro, \\ para contrabarra), valores octais ou valores hexadecimais.

Nota

  • O valor padrão é \\. Se uma linha em um arquivo de dados terminar no caractere de barra invertida (\), este caractere escapa do caractere de linha nova ou de retorno de carro especificado para a opção de formato do arquivo RECORD_DELIMITER. Como resultado, a operação de carregamento trata esta linha e a próxima linha como uma única linha de dados. Para evitar este problema, defina o valor como NONE.

  • Esta opção de formato de arquivo oferece suporte somente a caracteres de byte único. Observe que a codificação de caractere UTF-8 representa caracteres ASCII de ordem superior como caracteres multibyte. Se seu arquivo de dados for codificado com o conjunto de caracteres UTF-8, você não poderá especificar um caractere ASCII de ordem superior como o valor da opção.

    Além disso, se você especificar um caractere ASCII de ordem superior, recomendamos que você defina a opção de formato de arquivo ENCODING = 'string' como a codificação de caracteres para seus arquivos de dados para garantir que o caractere seja interpretado corretamente.

Padrão:

barra invertida (\\)

TRIM_SPACE = TRUE | FALSE

Booleano que especifica se é necessário remover o espaço em branco dos campos.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Use esta opção para remover espaços indesejados durante o carregamento de dados.

Como outro exemplo, se houver espaço no início e no final das aspas que delimitam as cadeias de caracteres, você pode remover o espaço usando a opção TRIM_SPACE e o caractere de citação usando a opção FIELD_OPTIONALLY_ENCLOSED_BY. Note que qualquer espaço entre as aspas é preservado.

Por exemplo, se assumirmos que o delimitador de campo é | e FIELD_OPTIONALLY_ENCLOSED_BY = '"':

|"Hello world"|
|" Hello world "|
| "Hello world" |
Copy

torna-se:

+---------------+
| C1            |
|----+----------|
| Hello world   |
|  Hello world  |
| Hello world   |
+---------------+
Copy

Padrão: FALSE

FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE

Caractere usado para delimitar as cadeias de caracteres. O valor pode ser NONE, caractere de aspas simples (') ou caractere de aspas duplas ("). Para usar o caractere de aspas simples, use a representação octal ou hexadecimal (0x27) ou o escape de aspas simples dupla ('').

Quando um campo contém este caractere, aplique o escape usando o mesmo caractere. Por exemplo, se o valor for o caractere de aspas duplas e um campo tiver a cadeia de caracteres A "B" C, aplique o escape das aspas duplas como segue:

A ""B"" C

Padrão: NONE

NULL_IF = ( 'string1' [ , 'string2' ... ] )

String usada para converter de e para SQL NULL. O Snowflake substitui estas cadeias de caracteres na origem do carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

Por exemplo:

NULL_IF = ('\N', 'NULL', 'NUL', '')

Observe que esta opção pode incluir cadeias de caracteres vazias.

Padrão: \N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\ (padrão))

ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE

Booleano que especifica se deve gerar um erro de análise se o número de colunas delimitadas (isto é, campos) em um arquivo de dados de entrada não corresponder ao número de colunas na tabela correspondente.

Se definido como FALSE, um erro não é gerado e o carregamento continua. Se o arquivo for carregado com sucesso:

  • Se o arquivo de entrada tiver registros com mais campos do que colunas na tabela, os campos correspondentes serão carregados em ordem de ocorrência no arquivo e os campos restantes não serão carregados.

  • Se o arquivo de entrada tiver registros com menos campos do que colunas na tabela, as colunas não correspondentes na tabela são carregadas com valores NULL.

Esta opção assume que todos os registros dentro do arquivo de entrada têm o mesmo comprimento (ou seja, um arquivo contendo registros de comprimento variável retorna um erro independentemente do valor especificado para esta opção).

Padrão: TRUE

Nota

Ao transformar dados durante o carregamento (isto é, usando uma consulta como fonte do comando COPY INTO <tabela>), esta opção é ignorada. Não há exigência de que seus arquivos de dados tenham o mesmo número e ordenação de colunas que sua tabela de destino.

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). A opção de cópia realiza uma substituição de caracteres um a um.

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão: FALSE

EMPTY_FIELD_AS_NULL = TRUE | FALSE

Booleano que especifica se deve inserir SQL NULL para campos vazios em um arquivo de entrada, que são representados por dois delimitadores sucessivos (por exemplo, ,,).

Se definido como FALSE, o Snowflake tenta converter um campo vazio no tipo de coluna correspondente. Uma cadeia de caracteres vazia é inserida em colunas do tipo STRING. Para outros tipos de colunas, o comando COPY INTO <tabela> produz um erro.

Padrão: TRUE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

Booleano que especifica se deve ignorar o BOM (marca de ordem de byte), se presente em um arquivo de dados. Um BOM é um código de caracteres no início de um arquivo de dados que define a ordem de bytes e a forma de codificação.

Se definido como FALSE, o Snowflake reconhece qualquer BOM nos arquivos de dados, o que poderia resultar no BOM causando um erro ou sendo fundido na primeira coluna da tabela.

Padrão: TRUE

ENCODING = 'string'

Cadeia de caracteres (constante) que especifica o conjunto de caracteres dos dados de origem.

Conjunto de caracteres

Valor ENCODING 

Linguagens suportadas

Notas

Big5

BIG5

Chinês Tradicional

EUC-JP

EUCJP

Japonês

EUC-KR

EUCKR

Coreano

GB18030

GB18030

Chinês

IBM420

IBM420

Árabe

IBM424

IBM424

Hebraico

IBM949

IBM949

Coreano

ISO-2022-CN

ISO2022CN

Chinês simplificado

ISO-2022-JP

ISO2022JP

Japonês

ISO-2022-KR

ISO2022KR

Coreano

ISO-8859-1

ISO88591

Alemão, Dinamarquês, Espanhol, Francês, Holandês, Inglês, Italiano, Norueguês, Português, Sueco

ISO-8859-2

ISO88592

Tcheco, Húngaro, Polonês, Romeno

ISO-8859-5

ISO88595

Russo

ISO-8859-6

ISO88596

Árabe

ISO-8859-7

ISO88597

Grego

ISO-8859-8

ISO88598

Hebraico

ISO-8859-9

ISO88599

Turco

ISO-8859-15

ISO885915

Alemão, Dinamarquês, Espanhol, Francês, Holandês, Inglês, Italiano, Norueguês, Português, Sueco

Idêntico a ISO-8859-1 exceto para 8 caracteres, incluindo o símbolo da moeda Euro.

KOI8-R

KOI8R

Russo

Shift_JIS

SHIFTJIS

Japonês

UTF-8

UTF8

Todos os idiomas

Para carregar dados de arquivos delimitados (CSV, TSV etc.), UTF-8 é o padrão. . . Para carregar dados de todos os outros formatos de arquivo suportados (JSON, Avro etc.), bem como descarregar dados, o UTF-8 é o único conjunto de caracteres suportado.

UTF-16

UTF16

Todos os idiomas

UTF-16BE

UTF16BE

Todos os idiomas

UTF-16LE

UTF16LE

Todos os idiomas

UTF-32

UTF32

Todos os idiomas

UTF-32BE

UTF32BE

Todos os idiomas

UTF-32LE

UTF32LE

Todos os idiomas

windows-949

WINDOWS949

Coreano

windows-1250

WINDOWS1250

Tcheco, Húngaro, Polonês, Romeno

windows-1251

WINDOWS1251

Russo

windows-1252

WINDOWS1252

Alemão, Dinamarquês, Espanhol, Francês, Holandês, Inglês, Italiano, Norueguês, Português, Sueco

windows-1253

WINDOWS1253

Grego

windows-1254

WINDOWS1254

Turco

windows-1255

WINDOWS1255

Hebraico

windows-1256

WINDOWS1256

Árabe

Padrão: UTF8

Nota

O Snowflake armazena todos os dados internamente no conjunto de caracteres UTF-8. Os dados são convertidos em UTF-8 antes de serem carregados no Snowflake.

TYPE = JSON

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

String (constante) que especifica o algoritmo de compressão atual para os arquivos de dados a serem carregados. O Snowflake usa esta opção para detectar como os arquivos de dados já comprimidos foram comprimidos para que os dados comprimidos nos arquivos possam ser extraídos para carregamento.

Valores suportados

Notas

AUTO

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.

GZIP

BZ2

BROTLI

ZSTD

DEFLATE

Arquivos compactados Deflate (com cabeçalho zlib, RFC1950).

RAW_DEFLATE

Arquivos compactados Raw Deflate (sem cabeçalho, RFC1951).

NONE

Indica que os arquivos para carregamento de dados não foram comprimidos.

Padrão: AUTO

DATE_FORMAT = 'string' | AUTO

Define o formato dos valores da cadeia de caracteres de data nos arquivos de dados. Se um valor não for especificado ou for AUTO, é usado o valor para o parâmetro DATE_INPUT_FORMAT.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Carregamento de dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

  • Carregamento de dados JSON em colunas separadas especificando uma consulta na instrução COPY (isto é, transformação COPY).

Padrão: AUTO

TIME_FORMAT = 'string' | AUTO

Define o formato dos valores da cadeia de caracteres de hora nos arquivos de dados. Se um valor não for especificado ou for AUTO, é usado o valor para o parâmetro TIME_INPUT_FORMAT.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Carregamento de dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

  • Carregamento de dados JSON em colunas separadas especificando uma consulta na instrução COPY (isto é, transformação COPY).

Padrão: AUTO

TIMESTAMP_FORMAT = string' | AUTO

Define o formato dos valores da cadeia de caracteres de carimbo de data/hora nos arquivos de dados. Se um valor não for especificado ou for AUTO, é usado o valor para o parâmetro TIMESTAMP_INPUT_FORMAT.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Carregamento de dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

  • Carregamento de dados JSON em colunas separadas especificando uma consulta na instrução COPY (isto é, transformação COPY).

Padrão: AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

Define o formato de codificação dos valores binários da cadeia de caracteres nos arquivos de dados. A opção pode ser usada no carregamento de dados em colunas binárias em uma tabela.

Esta opção de formato de arquivo é aplicada apenas às seguintes ações:

  • Carregamento de dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

  • Carregamento de dados JSON em colunas separadas especificando uma consulta na instrução COPY (isto é, transformação COPY).

Padrão: HEX

TRIM_SPACE = TRUE | FALSE

Booleano que especifica se é necessário remover o espaço no início e no final das cadeias de caracteres.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Defina esta opção como TRUE para remover espaços indesejáveis durante o carregamento de dados.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Padrão: FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

String usada para converter de e para SQL NULL. O Snowflake substitui estas cadeias de caracteres na origem do carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados JSON em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

Por exemplo:

NULL_IF = ('\N', 'NULL', 'NUL', '')

Observe que esta opção pode incluir cadeias de caracteres vazias.

Padrão: \\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\)

ENABLE_OCTAL = TRUE | FALSE

Booleano que permite a análise dos números octais.

Padrão: FALSE

ALLOW_DUPLICATE = TRUE | FALSE

Booleano que permite a duplicação de nomes de campos de objetos (somente o último será preservado).

Padrão: FALSE

STRIP_OUTER_ARRAY = TRUE | FALSE

Booleano que instrui o analisador JSON a remover os parênteses externos [ ].

Padrão: FALSE

STRIP_NULL_VALUES = TRUE | FALSE

Booleano que instrui o analisador JSON a remover campos de objetos ou elementos de matriz contendo valores null. Por exemplo, quando definido como TRUE:

Antes

Depois

[null]

[]

[null,null,3]

[,,3]

{"a":null,"b":null,"c":123}

{"c":123}

{"a":[1,null,2],"b":{"x":null,"y":88}}

{"a":[1,,2],"b":{"y":88}}

Padrão: FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). A opção de cópia realiza uma substituição de caracteres um a um.

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão: FALSE

IGNORE_UTF8_ERRORS = TRUE | FALSE

Booleano que especifica se os erros da codificação UTF-8 produzem condições de erro. É uma sintaxe alternativa para REPLACE_INVALID_CHARACTERS.

Se definido como TRUE, qualquer sequência inválida UTF-8 é silenciosamente substituída pelo caractere Unicode U+FFFD (ou seja, “caractere de substituição”).

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão: FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

Booleano que especifica se deve ignorar qualquer BOM (marca de ordem de byte) presente em um arquivo de entrada. Um BOM é um código de caracteres no início de um arquivo de dados que define a ordem de bytes e a forma de codificação.

Se definido como FALSE, o Snowflake reconhece qualquer BOM nos arquivos de dados, o que poderia resultar no BOM causando um erro ou sendo fundido na primeira coluna da tabela.

Padrão: TRUE

TYPE = AVRO

COMPRESSION = AUTO | GZIP | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

String (constante) que especifica o algoritmo de compressão atual para os arquivos de dados a serem carregados. O Snowflake usa esta opção para detectar como os arquivos de dados já comprimidos foram comprimidos para que os dados comprimidos nos arquivos possam ser extraídos para carregamento.

Valores suportados

Notas

AUTO

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.

GZIP

BROTLI

ZSTD

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.

Nota

Recomendamos que você use a opção padrão AUTO porque ela determinará a compactação do arquivo e do codec. A especificação de uma opção de compactação refere-se à compactação de arquivos, não à compactação de blocos (codecs).

TRIM_SPACE = TRUE | FALSE

Booleano que especifica se é necessário remover o espaço no início e no final das cadeias de caracteres.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Defina esta opção como TRUE para remover espaços indesejáveis durante o carregamento de dados.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados Avro em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Padrão: FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). A opção de cópia realiza uma substituição de caracteres um a um.

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão: FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

String usada para converter de e para SQL NULL. O Snowflake substitui estas cadeias de caracteres na origem do carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados Avro em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

Por exemplo:

NULL_IF = ('\N', 'NULL', 'NUL', '')

Observe que esta opção pode incluir cadeias de caracteres vazias.

Padrão: \\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\)

TYPE = ORC

TRIM_SPACE = TRUE | FALSE

Booleano que especifica se é necessário remover o espaço no início e no final das cadeias de caracteres.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Defina esta opção como TRUE para remover espaços indesejáveis durante o carregamento de dados.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados Orc em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Padrão: FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). A opção de cópia realiza uma substituição de caracteres um a um.

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão: FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

String usada para converter de e para SQL NULL. O Snowflake substitui estas cadeias de caracteres na origem do carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar dados Orc em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

Por exemplo:

NULL_IF = ('\N', 'NULL', 'NUL', '')

Observe que esta opção pode incluir cadeias de caracteres vazias.

Padrão: \\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\)

TYPE = PARQUET

COMPRESSION = AUTO | SNAPPY | NONE

String (constante) que especifica o algoritmo de compressão atual para os arquivos de dados a serem carregados. O Snowflake usa esta opção para detectar como os arquivos de dados já comprimidos foram comprimidos para que os dados comprimidos nos arquivos possam ser extraídos para carregamento.

Valores suportados

Notas

AUTO

Algoritmo de compressão detectado automaticamente. Oferece suporte aos seguintes algoritmos de compressão: Brotli, gzip, Lempel-Ziv-Oberhumer (LZO), LZ4, Snappy ou Zstandard v0.8 (e superior).

SNAPPY

NONE

Os arquivos de dados a serem carregados não foram comprimidos.

BINARY_AS_TEXT = TRUE | FALSE

Booleano que especifica se deve interpretar colunas sem tipo de dados lógicos definidos como texto UTF-8. Quando definido como FALSE, o Snowflake interpreta estas colunas como dados binários.

Padrão: TRUE

Nota

Snowflake recomenda que você defina BINARY_AS_TEXT como FALSE para evitar possíveis problemas de conversão.

TRIM_SPACE = TRUE | FALSE

Booleano que especifica se é necessário remover o espaço no início e no final das cadeias de caracteres.

Por exemplo, se seu software de banco de dados externo delimita os campos com aspas, mas insere um espaço à esquerda, o Snowflake lê o espaço à esquerda em vez do caractere de abertura de aspas como o início do campo (ou seja, as aspas são interpretadas como parte da cadeia de caracteres de dados do campo). Defina esta opção como TRUE para remover espaços indesejáveis durante o carregamento de dados.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar os dados do Parquet em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Padrão: FALSE

USE_LOGICAL_TYPE = TRUE | FALSE

Booleano que especifica se devem ser usados tipos lógicos Parquet. Com esta opção de formato de arquivo, Snowflake pode interpretar tipos lógicos Parquet durante o carregamento de dados. Para obter mais informações, consulte Definições do tipo lógico Parquet. Para ativar os tipos lógicos Parquet, defina USE_LOGICAL_TYPE como TRUE ao criar uma nova opção de formato de arquivo.

Padrão: FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). A opção de cópia realiza uma substituição de caracteres um a um.

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão: FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

String usada para converter de e para SQL NULL. O Snowflake substitui estas cadeias de caracteres na origem do carregamento de dados por SQL NULL. Para especificar mais de uma cadeia de caracteres, coloque a lista de cadeias de caracteres entre parênteses e use vírgulas para separar cada valor.

Esta opção de formato de arquivo é aplicada às seguintes ações somente ao carregar os dados do Parquet em colunas separadas usando a opção de cópia MATCH_BY_COLUMN_NAME.

Observe que o Snowflake converte todas as instâncias do valor em NULL, independentemente do tipo de dados. Por exemplo, se 2 for especificado como um valor, todas as instâncias de 2 como uma cadeia de caracteres ou número são convertidas.

Por exemplo:

NULL_IF = ('\N', 'NULL', 'NUL', '')

Observe que esta opção pode incluir cadeias de caracteres vazias.

Padrão: \\N (ou seja, NULL, que considera que o valor ESCAPE_UNENCLOSED_FIELD é \\)

TYPE = XML

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

String (constante) que especifica o algoritmo de compressão atual para os arquivos de dados a serem carregados. O Snowflake usa esta opção para detectar como os arquivos de dados já comprimidos foram comprimidos para que os dados comprimidos nos arquivos possam ser extraídos para carregamento.

Valores suportados

Notas

AUTO

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.

GZIP

BZ2

BROTLI

ZSTD

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

IGNORE_UTF8_ERRORS = TRUE | FALSE

Booleano que especifica se os erros da codificação UTF-8 produzem condições de erro. É uma sintaxe alternativa para REPLACE_INVALID_CHARACTERS.

Se definido como TRUE, qualquer sequência inválida UTF-8 é silenciosamente substituída pelo caractere Unicode U+FFFD (ou seja, “caractere de substituição”).

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão: FALSE

PRESERVE_SPACE = TRUE | FALSE

Booleano que especifica se o analisador XML preserva espaços no início e no final no conteúdo de elementos.

Padrão: FALSE

STRIP_OUTER_ELEMENT = TRUE | FALSE

Booleano que especifica se o analisador XML retira o elemento XML externo, expondo elementos de segundo nível como documentos separados.

Padrão: FALSE

DISABLE_SNOWFLAKE_DATA = TRUE | FALSE

Booleano que especifica se o analisador XML desabilita o reconhecimento das tags de dados semiestruturados do Snowflake.

Padrão: FALSE

DISABLE_AUTO_CONVERT = TRUE | FALSE

Booleano que especifica se o analisador XML desativa a conversão automática de valores numéricos e booleanos de texto para representação nativa.

Padrão: FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

Booleano que especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (). A opção de cópia realiza uma substituição de caracteres um a um.

Se definido como TRUE, o Snowflake substitui os caracteres inválidos UTF-8 pelo caractere de substituição Unicode.

Se definido como FALSE, a operação de carregamento produz um erro quando a codificação de caracteres UTF-8 inválida é detectada.

Padrão: FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

Booleano que especifica se deve ignorar qualquer BOM (marca de ordem de byte) presente em um arquivo de entrada. Um BOM é um código de caracteres no início de um arquivo de dados que define a ordem de bytes e a forma de codificação.

Se definido como FALSE, o Snowflake reconhece qualquer BOM nos arquivos de dados, o que poderia resultar no BOM causando um erro ou sendo fundido na primeira coluna da tabela.

Padrão: TRUE

Opções de cópia (copyOptions)

Você pode especificar uma ou mais das seguintes opções de cópia (separadas por espaços em branco, vírgulas ou novas linhas):

ON_ERROR = CONTINUE | SKIP_FILE | SKIP_FILE_num | 'SKIP_FILE_num%' | ABORT_STATEMENT
Uso:

Somente carregamento de dados

Definição:

Cadeia de caracteres (constante) que especifica o tratamento do erro para a operação de carga.

Importante

Considere cuidadosamente o valor da opção de cópia ON_ERROR. O valor padrão é adequado em cenários comuns, mas nem sempre é a melhor opção.

Valores:
  • CONTINUE

    Continuar a carregar o arquivo se forem encontrados erros. A instrução COPY retorna uma mensagem de erro para um máximo de um erro encontrado por arquivo de dados.

    Observe que a diferença entre os valores das colunas ROWS_PARSED e ROWS_LOADED representa o número de linhas que incluem os erros detectados. No entanto, cada uma dessas linhas poderia incluir vários erros. Para visualizar todos os erros nos arquivos de dados, use o parâmetro VALIDATION_MODE ou consulte a função VALIDATE.

  • SKIP_FILE

    Ignorar um arquivo quando for encontrado um erro.

    Observe que a ação SKIP_FILE armazena em buffer o arquivo inteiro, quer sejam ou não encontrados erros. Por este motivo, SKIP_FILE é mais lento que CONTINUE ou ABORT_STATEMENT. Ignorar arquivos grandes devido a um pequeno número de erros pode resultar em atrasos e desperdício de créditos. Ao carregar um grande número de registros de arquivos que não têm delimitação lógica (por exemplo, os arquivos foram gerados automaticamente em intervalos aproximados), considere especificar CONTINUE em vez disso.

    Padrões adicionais:

    SKIP_FILE_num (por exemplo, SKIP_FILE_10)

    Ignorar um arquivo quando o número de linhas de erro encontrado no arquivo for igual ou maior que o número especificado.

    'SKIP_FILE_num%' (por exemplo, 'SKIP_FILE_10%')

    Pular um arquivo quando a porcentagem de linhas de erro encontradas no arquivo exceder a porcentagem especificada.

  • ABORT_STATEMENT

    Abortar a operação de carregamento se algum erro for encontrado em um arquivo de dados.

    Observe que a operação de carregamento não é abortada se o arquivo de dados não puder ser encontrado (por exemplo, porque ele não existe ou não pode ser acessado), exceto quando arquivos de dados explicitamente especificados no parâmetro FILES não puderem ser encontrados.

Padrão:
Carregamento em massa utilizando COPY:

ABORT_STATEMENT

Snowpipe:

SKIP_FILE

SIZE_LIMIT = num
Definição:

Número (> 0) que especifica o tamanho máximo (em bytes) dos dados a serem carregados para uma determinada instrução COPY. Quando o limite é excedido, a operação COPY interrompe o carregamento dos arquivos. Esta opção é comumente usada para carregar um grupo comum de arquivos usando múltiplas instruções COPY. Para cada instrução, o carregamento de dados continua até que o SIZE_LIMIT especificado seja excedido, antes de passar para a instrução seguinte.

Por exemplo, suponha que um conjunto de arquivos em um caminho do estágio tivesse um tamanho de 10 MB cada. Se múltiplas instruções COPY definissem SIZE_LIMIT como 25000000 (25 MB), cada uma carregaria 3 arquivos. Ou seja, cada operação COPY seria interrompida após o limite SIZE_LIMIT ter sido excedido.

Observe que pelo menos um arquivo é carregado independentemente do valor especificado para SIZE_LIMIT, a menos que não haja nenhum arquivo a ser carregado.

Padrão:

nulo (sem limite de tamanho)

PURGE = TRUE | FALSE
Definição:

Booleano que especifica se os arquivos de dados devem ser removidos automaticamente do estágio depois que os dados forem carregados com sucesso.

Se esta opção for definida como TRUE, observe que é feito o melhor possível para remover arquivos de dados carregados com sucesso. Se a operação de limpeza falhar por qualquer motivo, nenhum erro é devolvido no momento. Recomendamos que você liste arquivos preparados periodicamente (usando LIST) e remova manualmente os arquivos carregados com sucesso, se houver algum.

Padrão:

FALSE

RETURN_FAILED_ONLY = TRUE | FALSE
Definição:

Booleano que especifica se devem ser devolvidos apenas os arquivos que não tenham sido carregados no resultado da instrução.

Padrão:

FALSE

MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
Definição:

Cadeia de caracteres que especifica se dados semiestruturados devem ser carregados em colunas na tabela de destino que correspondem às colunas representadas nos dados.

Importante

Não use a opção de cópia MATCH_BY_COLUMN_NAME ao transformar dados durante um carregamento, pois usá-los juntos gerará resultados inesperados.

Por exemplo, a seguinte sintaxe não é permitida:

COPY INTO [<namespace>.]<table_name> [ ( <col_name> [ , <col_name> ... ] ) ]
FROM ( SELECT [<alias>.]$<file_col_num>[.<element>] [ , [<alias>.]$<file_col_num>[.<element>] ... ]
    FROM { internalStage | externalStage } )
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
            TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
[ other copyOptions ]
Copy

Use transformações MATCH_BY_COLUMN_NAME ou COPY com base nas necessidades do seu negócio, mas nunca use as duas juntas. Para obter mais informações, consulte Transformação de dados durante um carregamento.

Esta opção de cópia é suportada para os seguintes formatos de dados:

  • JSON

  • Avro

  • ORC

  • Parquet

  • CSV (Recurso em versão preliminar - Aberto)

Para que uma coluna seja correspondente, os seguintes critérios devem ser verdadeiros:

  • A coluna representada nos dados deve ter exatamente o mesmo nome que a coluna da tabela. A opção de cópia oferece suporte à diferenciação de letras maiúsculas e minúsculas em nomes de colunas. A ordem das colunas não importa.

  • A coluna na tabela deve ter um tipo de dados compatível com os valores na coluna representada nos dados. Por exemplo, os valores da cadeia de caracteres, número e booleano podem ser todos carregados em uma coluna variante.

Valores:
CASE_SENSITIVE | CASE_INSENSITIVE

Carregar dados semiestruturados em colunas da tabela de destino que correspondam às colunas representadas nos dados. Os nomes das colunas distinguem letras maiúsculas de minúsculas (CASE_SENSITIVE) ou não (CASE_INSENSITIVE).

A operação COPY verifica se pelo menos uma coluna na tabela de destino corresponde a uma coluna representada nos arquivos de dados. Se for encontrada uma correspondência, os valores nos arquivos de dados são carregados na coluna ou colunas. Se nenhuma correspondência for encontrada, um conjunto de valores NULL para cada registro nos arquivos é carregado na tabela.

Nota

  • Se colunas adicionais não correspondentes estiverem presentes nos arquivos de dados, os valores nestas colunas não serão carregados.

  • Se colunas adicionais não correspondentes estiverem presentes na tabela de destino, a operação COPY insere valores NULL nestas colunas. Estas colunas devem oferecer suporte a valores NULL.

NONE

A operação COPY carrega os dados semiestruturados em uma coluna variante ou, se uma consulta for incluída na instrução COPY, transforma os dados.

Padrão:

NONE

Nota

As seguintes limitações se aplicam atualmente:

  • MATCH_BY_COLUMN_NAME não pode ser usado com o parâmetro VALIDATION_MODE em uma instrução COPY para validar os dados preparados em vez de carregá-los na tabela de destino.

  • Somente dados Parquet. Quando MATCH_BY_COLUMN_NAME está definido como CASE_SENSITIVE ou CASE_INSENSITIVE, um valor de coluna vazio (por exemplo, "col1": "") produz um erro.

ENFORCE_LENGTH = TRUE | FALSE
Definição:

Sintaxe alternativa para TRUNCATECOLUMNS com lógica reversa (para compatibilidade com outros sistemas)

Booleano que especifica se deve truncar cadeias de caracteres de texto que excedam o comprimento da coluna de destino:

  • Se TRUE, a instrução COPY produz um erro se uma cadeia de caracteres carregada exceder o comprimento da coluna alvo.

  • Se FALSE, as cadeias de caracteres são automaticamente truncadas para o comprimento da coluna de destino.

Esta opção de cópia oferece suporte a dados CSV, bem como valores de cadeia de caracteres em dados semiestruturados quando carregados em colunas separadas em tabelas relacionais.

Padrão:

TRUE

Nota

  • Se o comprimento da coluna da cadeia de caracteres de destino for definido como o máximo (por exemplo, VARCHAR (16777216)), uma cadeia de caracteres de entrada não pode exceder este comprimento; caso contrário, o comando COPY produz um erro.

  • Este parâmetro é funcionalmente equivalente a TRUNCATECOLUMNS, mas tem o comportamento oposto. É fornecido para compatibilidade com outros bancos de dados. É necessário apenas incluir um destes dois parâmetros em uma instrução COPY para produzir a saída desejada.

TRUNCATECOLUMNS = TRUE | FALSE
Definição:

Sintaxe alternativa para ENFORCE_LENGTH com lógica reversa (para compatibilidade com outros sistemas)

Booleano que especifica se deve truncar cadeias de caracteres de texto que excedam o comprimento da coluna de destino:

  • Se TRUE, as cadeias de caracteres são automaticamente truncadas para o comprimento da coluna de destino.

  • Se FALSE, a instrução COPY produz um erro se uma cadeia de caracteres carregada exceder o comprimento da coluna alvo.

Esta opção de cópia oferece suporte a dados CSV, bem como valores de cadeia de caracteres em dados semiestruturados quando carregados em colunas separadas em tabelas relacionais.

Padrão:

FALSE

Nota

  • Se o comprimento da coluna da cadeia de caracteres de destino for definido como o máximo (por exemplo, VARCHAR (16777216)), uma cadeia de caracteres de entrada não pode exceder este comprimento; caso contrário, o comando COPY produz um erro.

  • Este parâmetro é funcionalmente equivalente a ENFORCE_LENGTH, mas tem o comportamento oposto. É fornecido para compatibilidade com outros bancos de dados. É necessário apenas incluir um destes dois parâmetros em uma instrução COPY para produzir a saída desejada.

FORCE = TRUE | FALSE
Definição:

Booleano que especifica o carregamento de todos os arquivos, independentemente de terem sido carregados anteriormente e não terem mudado desde que foram carregados. Note que esta opção recarrega os arquivos, potencialmente duplicando dados em uma tabela.

Padrão:

FALSE

LOAD_UNCERTAIN_FILES = TRUE | FALSE
Definição:

Booleano que especifica para carregar arquivos para os quais o status de carregamento é desconhecido. O comando COPY ignora estes arquivos por padrão.

O status da carga é desconhecido se todas as seguintes condições forem verdadeiras:

  • A data LAST_MODIFIED do arquivo (ou seja, a data em que o arquivo foi preparado) é mais antiga do que 64 dias.

  • O conjunto inicial de dados foi carregado na tabela há mais de 64 dias.

  • Se o arquivo já foi carregado com sucesso na tabela, este evento ocorreu há mais de 64 dias.

Para forçar o comando COPY a carregar todos os arquivos independentemente do status de carregamento ser conhecido, use a opção FORCE em seu lugar.

Para obter mais informações sobre a incerteza do status de carregamento, consulte Carregamento de arquivos mais antigos.

Padrão:

FALSE

Notas de uso

  • A palavra-chave DISTINCT nas instruções SELECT não é totalmente suportada. A especificação da palavra-chave pode levar a um comportamento de opção de cópia ON_ERROR inconsistente ou inesperado.

  • Carregamento somente do Google Cloud Storage: a lista de objetos devolvidos para um estágio externo pode incluir um ou mais “blobs de diretório”; essencialmente, caminhos que terminam em um caractere de barra (/), por exemplo:

    LIST @my_gcs_stage;
    
    +---------------------------------------+------+----------------------------------+-------------------------------+
    | name                                  | size | md5                              | last_modified                 |
    |---------------------------------------+------+----------------------------------+-------------------------------|
    | my_gcs_stage/load/                    |  12  | 12348f18bcb35e7b6b628ca12345678c | Mon, 11 Sep 2019 16:57:43 GMT |
    | my_gcs_stage/load/data_0_0_0.csv.gz   |  147 | 9765daba007a643bdff4eae10d43218y | Mon, 11 Sep 2019 18:13:07 GMT |
    +---------------------------------------+------+----------------------------------+-------------------------------+
    
    Copy

    Esses blobs são listados quando os diretórios são criados no console do Google Cloud Platform, em vez de usar qualquer outra ferramenta fornecida pelo Google.

    Instruções COPY que fazem referência a um estágio podem falhar quando a lista de objetos inclui blobs de diretório. Para evitar erros, recomendamos usar a correspondência de padrão de arquivo para identificar os arquivos para inclusão (ou seja, a cláusula PATTERN) quando a lista de arquivos para um estágio inclui blobs de diretório. Para um exemplo, consulte Carregamento usando a correspondência de padrões (neste tópico). Como alternativa, é possível definir ON_ERROR = SKIP_FILE na instrução COPY.

  • STORAGE_INTEGRATION CREDENTIALS e ENCRYPTION só se aplicam se você estiver carregando diretamente de um local de armazenamento privado/protegido:

    • Se você estiver carregando de um bucket público, o acesso seguro não é necessário.

    • Se você estiver carregando de um estágio externo nomeado, o estágio fornece todas as informações de credenciais necessárias para acessar o bucket.

  • Se você encontrar erros durante a execução do comando COPY depois que o comando for concluído, você pode validar os arquivos que produziram os erros usando a função de tabela VALIDATE.

    Nota

    A função VALIDATE só retorna saída para comandos COPY usados para executar o carregamento de dados padrão; ela não oferece suporte a comandos COPY que executam transformações durante o carregamento de dados (por exemplo, carregar um subconjunto de colunas de dados ou reordenar colunas de dados).

  • A menos que você especifique explicitamente FORCE = TRUE como uma das opções de cópia, o comando ignora os arquivos de dados preparados já carregados na tabela. Para recarregar os dados, você deve especificar FORCE = TRUE ou modificar o arquivo e prepará-lo novamente, o que gera uma nova soma de verificação.

  • O comando COPY não valida as conversões de tipo de dados para arquivos Parquet.

Saída

O comando retorna as seguintes colunas:

Nome da coluna

Tipo de dados

Descrição

FILE

TEXT

Nome do arquivo de origem e caminho relativo ao arquivo

STATUS

TEXT

Status: carregado, falha ao carregar ou parcialmente carregado

ROWS_PARSED

NUMBER

Número de linhas analisadas a partir do arquivo de origem

ROWS_LOADED

NUMBER

Número de linhas carregadas a partir do arquivo de origem

ERROR_LIMIT

NUMBER

Se o número de erros atingir este limite, então abortar

ERRORS_SEEN

NUMBER

Número de linhas de erro no arquivo de origem

FIRST_ERROR

TEXT

Primeiro erro do arquivo de origem

FIRST_ERROR_LINE

NUMBER

Número da linha do primeiro erro

FIRST_ERROR_CHARACTER

NUMBER

Posição do primeiro caractere de erro

FIRST_ERROR_COLUMN_NAME

TEXT

Nome da coluna do primeiro erro

Exemplos

Para exemplos de transformações de carregamento de dados, consulte Transformação de dados durante um carregamento.

Carregamento de arquivos a partir de um estágio interno

Nota

Estes exemplos assumem que os arquivos foram copiados para o estágio anteriormente usando o comando PUT.

Carregar arquivos de um estágio interno nomeado em uma tabela:

COPY INTO mytable
FROM @my_int_stage;
Copy

Carregar arquivos de um estágio da tabela em uma tabela:

COPY INTO mytable
FILE_FORMAT = (TYPE = CSV);
Copy

Nota

Ao copiar dados de arquivos em um local de tabela, a cláusula FROM pode ser omitida porque o Snowflake verifica automaticamente se há arquivos no local da tabela.

Carregar os arquivos do estágio pessoal do usuário em uma tabela:

COPY INTO mytable from @~/staged
FILE_FORMAT = (FORMAT_NAME = 'mycsv');
Copy

Carregamento de arquivos a partir de um estágio externo nomeado

Carregue arquivos de um estágio externo nomeado que você criou anteriormente usando o comando CREATE STAGE. O estágio externo nomeado faz referência a um local externo (Amazon S3, Google Cloud Storage ou Microsoft Azure) e inclui todas as credenciais e outros detalhes necessários para acessar o local:

COPY INTO mycsvtable
  FROM @my_ext_stage/tutorials/dataloading/contacts1.csv;
Copy

Carregamento de arquivos usando a correspondência de colunas

Carregue os arquivos de um estágio externo nomeado em uma tabela com a opção de cópia MATCH_BY_COLUMN_NAME, por meio da combinação dos nomes das colunas nos arquivos com os nomes das colunas definidos na tabela, sem distinção de maiúsculas e minúsculas. Com esta opção, a ordenação da coluna do arquivo não precisa corresponder à ordenação da coluna da tabela.

COPY INTO mytable
  FROM @my_ext_stage/tutorials/dataloading/sales.json.gz
  FILE_FORMAT = (TYPE = 'JSON')
  MATCH_BY_COLUMN_NAME='CASE_INSENSITIVE';
Copy

Carregamento de arquivos diretamente de um local externo

O exemplo a seguir carrega todos os arquivos prefixados com data/files de um local de armazenamento (Amazon S3, Google Cloud Storage ou Microsoft Azure) usando um formato de arquivo chamado my_csv_format:

Amazon S3

Acesse o bucket S3 referenciado usando uma integração de armazenamento referenciada chamada myint. Observe que ambos os exemplos truncam o valor MASTER_KEY:

COPY INTO mytable
  FROM s3://mybucket/data/files
  STORAGE_INTEGRATION = myint
  ENCRYPTION=(MASTER_KEY = 'eSx...')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy

Acessar o bucket S3 referenciado usando as credenciais fornecidas:

COPY INTO mytable
  FROM s3://mybucket/data/files
  CREDENTIALS=(AWS_KEY_ID='$AWS_ACCESS_KEY_ID' AWS_SECRET_KEY='$AWS_SECRET_ACCESS_KEY')
  ENCRYPTION=(MASTER_KEY = 'eSx...')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy

Google Cloud Storage

Acessar o bucket GCS referenciado usando uma integração de armazenamento referenciada chamada myint:

COPY INTO mytable
  FROM 'gcs://mybucket/data/files'
  STORAGE_INTEGRATION = myint
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy

Microsoft Azure

Acesse o contêiner referenciado usando uma integração de armazenamento referenciada chamada myint. Observe que ambos os exemplos truncam o valor MASTER_KEY:

COPY INTO mytable
  FROM 'azure://myaccount.blob.core.windows.net/data/files'
  STORAGE_INTEGRATION = myint
  ENCRYPTION=(TYPE='AZURE_CSE' MASTER_KEY = 'kPx...')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy

Acessar o contêiner referenciado usando as credenciais fornecidas:

COPY INTO mytable
  FROM 'azure://myaccount.blob.core.windows.net/mycontainer/data/files'
  CREDENTIALS=(AZURE_SAS_TOKEN='?sv=2016-05-31&ss=b&srt=sco&sp=rwdl&se=2018-06-27T10:05:50Z&st=2017-06-27T02:05:50Z&spr=https,http&sig=bgqQwoXwxzuD2GJfagRg7VOS8hzNr3QLT7rhS8OFRLQ%3D')
  ENCRYPTION=(TYPE='AZURE_CSE' MASTER_KEY = 'kPx...')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy

Carregamento usando a correspondência de padrões

Carregar arquivos do estágio de uma tabela em uma tabela usando a correspondência de padrões para carregar somente dados de arquivos comprimidos CSV em qualquer caminho:

COPY INTO mytable
  FILE_FORMAT = (TYPE = 'CSV')
  PATTERN='.*/.*/.*[.]csv[.]gz';
Copy

Onde .* é interpretado como «zero ou mais ocorrências de qualquer caráter». Os colchetes escapam do caractere de período (.) que precede uma extensão de arquivo.

Carregar arquivos de um estágio de tabela em uma tabela usando a correspondência de padrões para carregar somente arquivos não comprimidos CSV cujos nomes incluem a cadeia de caracteres sales:

COPY INTO mytable
  FILE_FORMAT = (FORMAT_NAME = myformat)
  PATTERN='.*sales.*[.]csv';
Copy

Carregamento de dados JSON em uma coluna VARIANT

O exemplo seguinte carrega dados JSON em uma tabela com uma única coluna do tipo VARIANT.

A matriz JSON preparada compreende três objetos separados por novas linhas:

[{
    "location": {
      "city": "Lexington",
      "zip": "40503",
      },
      "sq__ft": "1000",
      "sale_date": "4-25-16",
      "price": "75836"
},
{
    "location": {
      "city": "Belmont",
      "zip": "02478",
      },
      "sq__ft": "1103",
      "sale_date": "6-18-16",
      "price": "92567"
}
{
    "location": {
      "city": "Winchester",
      "zip": "01890",
      },
      "sq__ft": "1122",
      "sale_date": "1-31-16",
      "price": "89921"
}]
Copy
/* Create a JSON file format that strips the outer array. */

CREATE OR REPLACE FILE FORMAT json_format
  TYPE = 'JSON'
  STRIP_OUTER_ARRAY = TRUE;

/* Create an internal stage that references the JSON file format. */

CREATE OR REPLACE STAGE mystage
  FILE_FORMAT = json_format;

/* Stage the JSON file. */

PUT file:///tmp/sales.json @mystage AUTO_COMPRESS=TRUE;

/* Create a target table for the JSON data. */

CREATE OR REPLACE TABLE house_sales (src VARIANT);

/* Copy the JSON data into the target table. */

COPY INTO house_sales
   FROM @mystage/sales.json.gz;

SELECT * FROM house_sales;

+---------------------------+
| SRC                       |
|---------------------------|
| {                         |
|   "location": {           |
|     "city": "Lexington",  |
|     "zip": "40503"        |
|   },                      |
|   "price": "75836",       |
|   "sale_date": "4-25-16", |
|   "sq__ft": "1000",       |
|   "type": "Residential"   |
| }                         |
| {                         |
|   "location": {           |
|     "city": "Belmont",    |
|     "zip": "02478"        |
|   },                      |
|   "price": "92567",       |
|   "sale_date": "6-18-16", |
|   "sq__ft": "1103",       |
|   "type": "Residential"   |
| }                         |
| {                         |
|   "location": {           |
|     "city": "Winchester", |
|     "zip": "01890"        |
|   },                      |
|   "price": "89921",       |
|   "sale_date": "1-31-16", |
|   "sq__ft": "1122",       |
|   "type": "Condo"         |
| }                         |
+---------------------------+
Copy

Recarregamento de arquivos

Adicione FORCE = TRUE a um comando COPY para recarregar (duplicar) dados de um conjunto de arquivos de dados preparados que não mudaram (ou seja, têm a mesma verificação de soma de quando foram carregados pela primeira vez).

No exemplo a seguir, o primeiro comando carrega os arquivos especificados e o segundo comando força os mesmos arquivos a serem carregados novamente (produzindo linhas duplicadas), mesmo que o conteúdo dos arquivos não tenha mudado:

COPY INTO load1 FROM @%load1/data1/
    FILES=('test1.csv', 'test2.csv');

COPY INTO load1 FROM @%load1/data1/
    FILES=('test1.csv', 'test2.csv')
    FORCE=TRUE;
Copy

Limpeza de arquivos após o carregamento

Carregue os arquivos do estágio de uma tabela em uma tabela e limpe os arquivos após o carregamento. Por padrão, COPY não limpa os arquivos carregados do local. Para limpar os arquivos após o carregamento:

  • Defina PURGE=TRUE para que a tabela especifique que todos os arquivos carregados com sucesso na tabela sejam limpos após o carregamento:

    ALTER TABLE mytable SET STAGE_COPY_OPTIONS = (PURGE = TRUE);
    
    COPY INTO mytable;
    
    Copy
  • Você também pode substituir qualquer uma das opções de cópia diretamente no comando COPY:

    COPY INTO mytable PURGE = TRUE;
    
    Copy

Validação de arquivos preparados

Validar os arquivos em um estágio sem carregamento:

  • Execute o comando COPY no modo de validação e consulte todos os erros:

    COPY INTO mytable VALIDATION_MODE = 'RETURN_ERRORS';
    
    +-------------------------------------------------------------------------------------------------------------------------------+------------------------+------+-----------+-------------+----------+--------+-----------+----------------------+------------+----------------+
    |                                                         ERROR                                                                 |            FILE        | LINE | CHARACTER | BYTE_OFFSET | CATEGORY |  CODE  | SQL_STATE |   COLUMN_NAME        | ROW_NUMBER | ROW_START_LINE |
    +-------------------------------------------------------------------------------------------------------------------------------+------------------------+------+-----------+-------------+----------+--------+-----------+----------------------+------------+----------------+
    | Field delimiter ',' found while expecting record delimiter '\n'                                                               | @MYTABLE/data1.csv.gz  | 3    | 21        | 76          | parsing  | 100016 | 22000     | "MYTABLE"["QUOTA":3] | 3          | 3              |
    | NULL result in a non-nullable column. Use quotes if an empty field should be interpreted as an empty string instead of a null | @MYTABLE/data3.csv.gz  | 3    | 2         | 62          | parsing  | 100088 | 22000     | "MYTABLE"["NAME":1]  | 3          | 3              |
    | End of record reached while expected to parse column '"MYTABLE"["QUOTA":3]'                                                   | @MYTABLE/data3.csv.gz  | 4    | 20        | 96          | parsing  | 100068 | 22000     | "MYTABLE"["QUOTA":3] | 4          | 4              |
    +-------------------------------------------------------------------------------------------------------------------------------+------------------------+------+-----------+-------------+----------+--------+-----------+----------------------+------------+----------------+
    
    Copy
  • Execute o comando COPY no modo de validação para um número especificado de linhas. Neste exemplo, a primeira execução não encontra erros no número especificado de linhas e é concluída com sucesso, exibindo as informações como elas aparecerão quando carregadas na tabela. A segunda execução encontra um erro no número especificado de linhas e falha com o erro encontrado:

    COPY INTO mytable VALIDATION_MODE = 'RETURN_2_ROWS';
    
    +--------------------+----------+-------+
    |        NAME        |    ID    | QUOTA |
    +--------------------+----------+-------+
    | Joe Smith          |  456111  | 0     |
    | Tom Jones          |  111111  | 3400  |
    +--------------------+----------+-------+
    
    COPY INTO mytable VALIDATION_MODE = 'RETURN_3_ROWS';
    
    FAILURE: NULL result in a non-nullable column. Use quotes if an empty field should be interpreted as an empty string instead of a null
      File '@MYTABLE/data3.csv.gz', line 3, character 2
      Row 3, column "MYTABLE"["NAME":1]
    
    Copy