COPY INTO <tabela>¶

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:

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

  Para obter mais informações, consulte a documentação do Google Cloud Platform:

  • https://cloud.google.com/storage/docs/encryption/customer-managed-keys

  • https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys

• NONE: sem criptografia.

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:

• AZURE_CSE: criptografia do lado do cliente (exige um valor MASTER_KEY). Para obter mais informações, consulte as informações sobre criptografia do lado do cliente na documentação do Microsoft Azure.

• NONE: sem criptografia.

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 só 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.

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

Carregamento de arquivos a partir de um estágio interno¶

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