Parâmetros da conversão de dados - Amazon Redshift

Parâmetros da conversão de dados

À medida que carrega a tabela, COPY tenta converter implicitamente as strings nos dados de origem no tipo de dados da coluna de destino. Se precisar especificar uma conversão diferente do comportamento padrão, ou se a conversão padrão resultar em erros, você poderá gerenciar conversões de dados especificando os parâmetros a seguir. Para obter mais informações sobre a sintaxe desses parâmetros, consulte Sintaxe de COPY.

Parâmetros da conversão de dados
ACCEPTANYDATE

Permite que qualquer formato de data, inclusive formatos inválidos, como 00/00/00 00:00:00, seja carregado sem gerar um erro. Esse parâmetro se aplica somente a colunas TIMESTAMP e DATA. Use sempre ACCEPTANYDATE com o parâmetro DATEFORMAT. Se o formato de data dos dados não for correspondente à especificação DATEFORMAT, o Amazon Redshift inserirá um valor NULL nesse campo.

ACCEPTINVCHARS [AS] ['replacement_char']

Permite o carregamento de dados em colunas VARCHAR mesmo se os dados contiverem caracteres UTF-8 inválidos. Quando ACCEPTINVCHARS é especificado, COPY substitui todos os caracteres UTF-8 inválidos por uma string de mesmo tamanho que consiste no caractere especificado por replacement_char. Por exemplo, se o caractere substituto for '^', um caractere inválido de três bytes será substituído por '^^^'.

O caractere substituto pode ser qualquer caractere ASCII, exceto NULL. O padrão é um ponto de interrogação (?). Para obter informações sobre caracteres UTF-8 inválidos, consulte Erros no carregamento de caracteres multibyte.

COPY retorna o número de linhas que apresentavam caracteres UTF-8 inválidos e adiciona uma entrada à tabela do sistema STL_REPLACEMENTS para cada linha afetada, até 100 linhas, no máximo, para cada fatia de nó. Os caracteres UTF-8 inválidos adicionais também são substituídos, mas esses eventos substitutos não são registrados.

Se ACCEPTINVCHARS não for especificado, COPY retornará um erro sempre que encontrar um caractere UTF-8 inválido.

ACCEPTINVCHARS só é válido para colunas VARCHAR.

BLANKSASNULL

Carrega campos em branco, que consistem somente em caracteres de espaço em branco, como NULL. Essa opção se aplica somente a colunas CHAR e VARCHAR. Os campos em branco de outros tipos de dados, como INT, são sempre carregados com NULL. Por exemplo, uma string que contém três caracteres de espaço em sucessão (e qualquer outro caractere) é carregada como um NULL. O comportamento padrão, sem essa opção, é carregar os caracteres de espaço como estão.

DATEFORMAT [AS] {'dateformat_string' | 'auto' }

Se nenhum DATEFORMAT for especificado, o formato padrão será 'YYYY-MM-DD'. Por exemplo, um formato válido alternativo é 'MM-DD-YYYY'.

Se o comando COPY não reconhecer o formato dos valores de data ou hora, ou se os valores de data ou hora usarem formatos diferentes, use o argumento 'auto' com o parâmetro DATEFORMAT ou TIMEFORMAT. O argumento 'auto' reconhece diversos formatos não compatíveis ao usar uma string DATEFORMAT e TIMEFORMAT. A palavra-chave 'auto'' diferencia maiúsculas de minúsculas. Para obter mais informações, consulte Usar o reconhecimento automático com DATEFORMAT e TIMEFORMAT.

O formato de data pode incluir informações sobre horário (hora, minutos, segundos), mas essas informações são ignoradas. A palavra-chave AS é opcional. Para obter mais informações, consulte Strings DATEFORMAT e TIMEFORMAT.

EMPTYASNULL

Indica que o Amazon Redshift deve carregar campos CHAR e VARCHAR vazios como NULL. Os campos vazios de outros tipos de dados, como INT, são sempre carregados com NULL. Os campos vazios ocorrem quando os dados contêm dois delimitadores em sucessão sem caracteres entre os delimitadores. EMPTYASNULL e NULL AS '' (string vazia) produzem o mesmo comportamento.

ENCODING [AS] file_encoding

Especifica o tipo de codificação dos dados de carregamento. O comando COPY converte os dados da codificação especificada em UTF-8 durante o carregamento.

Os valores válidos para file_encoding são os seguintes:

  • UTF8

  • UTF16

  • UTF16LE

  • UTF16BE

O padrão é UTF8.

Os nomes de arquivo de origem devem usar codificação UTF-8.

Os seguintes arquivos devem usar codificação UTF-8, mesmo se uma codificação diferente for especificada para os dados de carregamento:

  • Arquivos de manifesto

  • Arquivos JSONPaths

As string de argumento que acompanham os seguintes parâmetros devem usar UTF-8:

  • FIXEDWIDTH 'fixedwidth_spec'

  • ACCEPTINVCHARS 'replacement_char'

  • DATEFORMAT 'dateformat_string'

  • TIMEFORMAT 'timeformat_string'

  • NULL AS 'null_string'

Os arquivos de dados de largura fixa devem usar codificação UTF-8. As larguras de campo se baseiam no número de caracteres, e não no número de bytes.

Todos os dados de carregamento devem usar a codificação especificada. Se encontrar uma codificação diferente, COPY ignorará o arquivo e retornará um erro.

Se você especificar UTF16, os dados deverão ter uma Byte Order Mark (BOM – Marca da ordem de bytes). Se souber se os dados UTF-16 são LE (Little-Endian) ou BE (Big-Endian), você poderá usar UTF16LE ou UTF16BE, independentemente da presença de uma BOM.

ESCAPE

Quando esse parâmetro é especificado, o caractere de barra invertida (\) em dados de entrada é tratado como um caractere de escape. O caractere logo depois do caractere de barra invertida será carregado na tabela como parte do valor de coluna atual, mesmo se for um caractere que normalmente atende a uma finalidade especial. Por exemplo, você poderá usar esse parâmetro para escapar o caractere delimitador, aspas, um caractere de nova linha integrado ou o próprio caractere de escape quando qualquer um desses caracteres for uma parte legítima de um valor de coluna.

Se especificar o parâmetro ESCAPE em combinação com o parâmetro REMOVEQUOTES, você poderá escapar e manter aspas (' ou ") que possam ser removidas de outra maneira. A string nula padrão, \N, funciona como está, mas também pode ser escapada nos dados de entrada como \\N. Desde que você não especifique uma string nula alternativa com o parâmetro NULL AS, \N e \\N produzem os mesmos resultados.

nota

O caractere de controle 0x00 (NUL) não pode ser escapado e deve ser removido dos dados de entrada ou convertido. Esse caractere é tratado como um marcador End Of Record (EOR – Fim do registro), truncando o restante do registro.

Você não pode usar o parâmetro ESCAPE para cargas FIXEDWIDTH, e você não pode especificar o caractere de escape propriamente dito; o caractere de escape é sempre o caractere de barra invertida. Além disso, você deve garantir que os dados de entrada contenham o caractere de escape nos lugares apropriados.

Aqui estão alguns exemplos de dados de entrada e os dados carregados resultantes quando o parâmetro ESCAPE é especificado. O resultado da linha 4 pressupõe que o parâmetro REMOVEQUOTES também esteja especificado. Os dados de entrada consistem em dois campos delimitados por barra: 

1|The quick brown fox\[newline]
jumped over the lazy dog.
2| A\\B\\C
3| A \| B \| C
4| 'A Midsummer Night\'s Dream'

Os dados carregados na coluna 2 têm esta aparência: 

The quick brown fox
jumped over the lazy dog.
A\B\C
A|B|C
A Midsummer Night's Dream
nota

A aplicação do caractere de escape aos dados de entrada de uma carga é responsabilidade do usuário. Uma exceção a esse requisito é quando você recarrega dados que foram descarregados anteriormente com o parâmetro ESCAPE. Nesse caso, os dados já conterão os caracteres de escape necessários.

O parâmetro ESCAPE não interpreta octal, hex, Unicode nem outras notações da sequência de escape. Por exemplo, se os dados de origem contiverem o valor de alimentação de linha octal (\012) e você tentar carregar esses dados com o parâmetro ESCAPE, o Amazon Redshift carregará o valor 012 na tabela e não interpretará esse valor como uma alimentação de linha com escape.

Para escapar caracteres de nova linha em dados originados de plataformas do Microsoft Windows, você pode precisar usar dois caracteres de escape: um para o retorno de carro e um para a alimentação de linha. Você também pode remover os retorno de carro antes de carregar o arquivo (por exemplo, usando o utilitário dos2unix).

EXPLICIT_IDS

Use EXPLICIT_IDS com tabelas que tenham colunas IDENTITY se você quiser substituir os valores gerados automaticamente por valores explícitos dos arquivos de dados de origem das tabelas. Se o comando incluir uma lista de colunas, essa lista deverá incluir as colunas IDENTITY para usar esse parâmetro. O formato de dados de valores EXPLICIT_IDS deve corresponder ao formato IDENTITY especificado pela definição de CREATE TABLE.

Depois de executar o comando COPY em relação a uma tabela com a opção EXPLICIT_IDS, o Amazon Redshift não conferirá a exclusividade de colunas IDENTITY na tabela.

Se uma coluna estiver definida com GENERATED BY DEFAULT AS IDENTITY, será possível copiá-la. Os valores são gerados ou atualizados com os valores fornecidos. A opção EXPLICIT_IDS não é necessária. COPY não atualiza a marca d'água alta de identidade.

Para obter um exemplo de um comando COPY usando EXPLICIT_IDS, consulte Carregar VENUE com valores explícitos para uma coluna IDENTITY.

FILLRECORD

Permite que arquivos de dados sejam carregados quando colunas contíguas não forem encontradas ao final de alguns dos registros. As colunas ausentes são carregadas como NULLs. Para formatos de texto e CSV, se a coluna ausente for uma coluna VARCHAR, as strings de comprimento zero serão carregadas em vez de NULLs. Para carregar NULLs em colunas VARCHAR a partir de texto e CSV, especifique a palavra-chave EMPTYASNULL. A substituição de NULL funcionará somente se a definição de coluna permitir NULLs.

Por exemplo, se a definição de tabela contiver quatro colunas CHAR anuláveis e um registro contiver os valores apple, orange, banana, mango, o comando COPY poderá carregar e preencher um registro que contenha somente os valores apple, orange. Os valores CHAR não encontrados seriam carregados como valores NULL.

IGNOREBLANKLINES

Ignora linhas em branco que contêm somente uma alimentação de linha em um arquivo de dados e não tenta carregá-las.

IGNOREHEADER [ AS ] number_rows

Trata as number_rows especificadas como um cabeçalho de arquivo e não as carrega. Use IGNOREHEADER para ignorar cabeçalhos de arquivo em todos os arquivos em uma carga paralela.

NULL AS 'null_string'

Carrega campos que correspondam a null_string como NULL, em que null_string pode ser qualquer string. Se os dados incluírem um terminador nulo, também conhecido como NUL (UTF-8 0000) ou zero binário (0x000), COPY o tratará como qualquer outro caractere. Por exemplo, um registro contendo '1' || NUL || '2' é copiado como string de comprimento de 3 bytes. Se um campo contiver somente NUL, você poderá usar NULL AS para substituir o terminador nulo por NULL, especificando '\0' ou '\000'. Por exemplo, NULL AS '\0' ou NULL AS '\000'. Se um campo contiver uma string que termina com NUL e NULL AS for especificado, a string será inserida com NUL ao final. Não use '\n' (nova linha) para o valor null_string. O Amazon Redshift reserva o uso de '\n' como um delimitador de linha. O null_string padrão é '\N'.

nota

Se você tentar carregar nulos em uma coluna definida como NOT NULL, o comando COPY falhará.

REMOVEQUOTES

Remove as aspas de strings nos dados recebidos. Todos os caracteres entre aspas, inclusive delimitadores, são mantidos. Se uma string tiver aspas simples ou duplas de abertura, mas nenhuma de fechamento correspondente, o comando COPY deixará de carregar essa linha e retornará um erro. A tabela a seguir mostra alguns exemplos simples de strings que contêm aspas e os valores carregados resultantes.

String de entrada Valor carregado com opção REMOVEQUOTES
"O delimitador é um caractere de barra (|)" O delimitador é um caractere de barra (|)
'Preto' Preto
"Branco" Branco
Azul' Azul'
Azul' Valor não carregado: condição de erro
"Azul Valor não carregado: condição de erro
' ' 'Preto' ' ' ' 'Preto' '
' ' <espaço em branco>
ROUNDEC

Arredonda para cima valores numéricos quando a escala do valor de entrada é maior que a escala da coluna. Por padrão, COPY trunca valores quando necessário para caber na escala da coluna. Por exemplo, se um valor de 20.259 for carregado em uma coluna DECIMAL(8,2), COPY truncará o valor em 20.25, por padrão. Se ROUNDEC for especificado, COPY arredondará o valor para 20.26. Como o comando INSERT sempre arredonda valores quando necessário de acordo com a escala da coluna, um comando COPY com o parâmetro ROUNDEC se comporta da mesma maneira que um comando INSERT.

TIMEFORMAT [AS] {'timeformat_string' | 'auto' | 'epochsecs' | 'epochmillisecs' }

Especifica o formato de hora. Se nenhum TIMEFORMAT for especificado, o formato padrão será YYYY-MM-DD HH:MI:SS para colunas TIMESTAMP ou YYYY-MM-DD HH:MI:SSOF para colunas TIMESTAMPTZ, em que OF é a diferença em relação ao Universal Coordinated Time (UTC – Tempo universal coordenado). Você não pode incluir um especificador de fuso horário no timeformat_string. Para carregar dados TIMESTAMPTZ em um formato diferente do formato padrão, especifique 'auto'; para obter mais informações, consulte Usar o reconhecimento automático com DATEFORMAT e TIMEFORMAT. Para obter mais informações sobre timeformat_string, consulte Strings DATEFORMAT e TIMEFORMAT.

O argumento 'auto' reconhece diversos formatos não compatíveis ao usar uma string DATEFORMAT e TIMEFORMAT. Se o comando COPY não reconhecer o formato dos valores de data ou hora, ou se os valores de data e hora usarem formatos diferentes, use o argumento 'auto' com o parâmetro DATEFORMAT ou TIMEFORMAT. Para obter mais informações, consulte Usar o reconhecimento automático com DATEFORMAT e TIMEFORMAT.

Se os dados de origem forem representados como hora epoch, ou seja o número de segundos ou milissegundos desde 1º de janeiro de 1970, 00:00:00 UTC, especifique 'epochsecs' ou 'epochmillisecs'.

As palavras-chave 'auto', 'epochsecs' e 'epochmillisecs' diferenciam maiúsculas de minúsculas.

A palavra-chave AS é opcional.

TRIMBLANKS

Remove os caracteres de espaço em branco à direita de uma string VARCHAR. Esse parâmetro se aplica somente a colunas com um tipo de dados VARCHAR.

TRUNCATECOLUMNS

Trunca dados em colunas no número apropriado de caracteres, de maneira que ele caiba na especificação da coluna. Aplica-se somente a colunas com um tipo de dados VARCHAR ou CHAR e linhas com 4 MB ou menos.