Usar propriedades do Amazon Ion SerDe

Este tópico contém informações sobre as propriedades SerDe para instruções CREATE TABLE no Athena. Para obter mais informações e exemplos do uso de propriedades do Amazon Ion SerDe, consulte SerDe properties (Propriedades SerDe) na documentação sobre o Amazon Ion Hive SerDe no GitHub.

Especificar propriedades SerDe do Amazon Ion

Para especificar propriedades para o Amazon Ion Hive SerDe na instrução CREATE TABLE, use a cláusula WITH SERDEPROPERTIES. Como WITH SERDEPROPERTIES é um subcampo da cláusula ROW FORMAT SERDE, você deve especificar primeiro ROW FORMAT SERDE e o caminho da classe do Amazon Ion Hive SerDe, como mostra a sintaxe a seguir.

...
ROW FORMAT SERDE
 'com.amazon.ionhiveserde.IonHiveSerDe'
WITH SERDEPROPERTIES (
 'property' = 'value',
 'property' = 'value',
...
)

Observe que, embora a cláusula ROW FORMAT SERDE seja obrigatória se você quiser usar WITH SERDEPROPERTIES, será possível usar STORED AS ION ou a sintaxe mais longa INPUTFORMAT e OUTPUTFORMAT para especificar o formato Amazon Ion.

Propriedades SerDe do Amazon Ion

As propriedades do Amazon Ion SerDe que podem ser usadas em instruções CREATE TABLE no Athena são listadas a seguir.

ion.encoding

Opcional

Padrão: BINARY

Valores: BINARY, TEXT

Esta propriedade declara se novos valores adicionados são serializados como Amazon Ion binário ou no formato de texto do Amazon Ion.

O exemplo de propriedade SerDe a seguir especifica o formato de texto do Amazon Ion.

'ion.encoding' = 'TEXT'

ion.fail_on_overflow

Opcional

Padrão: true

Valores: true, false

O Amazon Ion permite tipos numéricos arbitrariamente grandes, o que não é permitido pelo Hive. Por padrão, o SerDe falhará se o valor do Amazon Ion não se encaixar na coluna Hive, mas você pode usar a opção de configuração fail_on_overflow para permitir que o valor estoure em vez de falhar.

Essa propriedade pode ser definida no nível de tabela ou de coluna. Para defini-la no nível de tabela, especifique ion.fail_on_overflow como no exemplo a seguir. Isso define o comportamento padrão para todas as colunas.

'ion.fail_on_overflow' = 'true'

Para controlar uma coluna específica, defina o nome da coluna entre ion e fail_on_overflow, delimitado por pontos, como no exemplo a seguir.

'ion.<column>.fail_on_overflow' = 'false'

ion.path_extractor.case_sensitive

Opcional

Padrão: false

Valores: true, false

Determina se os nomes de campos do Amazon Ion devem diferenciar maiúsculas de minúsculas. Quando for definido como false, o SerDe ignorará a análise de maiúsculas e minúsculas nos nomes de campo do Amazon Ion.

Por exemplo, suponha que você tenha um esquema de tabela do Hive que defina um campo alias em minúsculas e um documento do Amazon Ion com os campos alias e ALIAS, como no exemplo a seguir.

-- Hive Table Schema
alias: STRING

-- Amazon Ion Document
{ 'ALIAS': 'value1'} 
{ 'alias': 'value2'}

O exemplo a seguir mostra as propriedades SerDe e a tabela extraída resultante quando a diferenciação de maiúsculas e minúsculas for definida como false:

-- Serde properties
'ion.alias.path_extractor' = '(alias)'
'ion.path_extractor.case_sensitive' = 'false'

--Extracted Table
| alias    |
|----------|
| "value1" |
| "value2" |

O exemplo a seguir mostra as propriedades SerDe e a tabela extraída resultante quando a diferenciação de maiúsculas e minúsculas for definida como true:

-- Serde properties
'ion.alias.path_extractor' = '(alias)'
'ion.path_extractor.case_sensitive' = 'true'

--Extracted Table
| alias    |
|----------|
| "value2" |

No segundo caso, o value1 do campo ALIAS é ignorado quando a diferenciação de maiúsculas e minúsculas é definida como true e o extrator de caminhos é especificado como alias.

ion.<column>.path_extractor

Opcional

Padrão: ND

Valores: string com caminho de pesquisa

Cria um extrator de caminhos com o caminho de pesquisa especificado para a coluna dada. Os extratores de caminhos mapeiam os campos do Amazon Ion para colunas do Hive. Se nenhum extrator de caminhos for especificado, o Athena criará dinamicamente extratores de caminhos em tempo de execução com base nos nomes das colunas.

O exemplo de extrator de caminhos a seguir mapeia example_ion_field para example_hive_column.

'ion.example_hive_column.path_extractor' = '(example_ion_field)'

Para obter mais informações sobre extratores de caminhos e caminhos de pesquisa, consulte Usar extratores de caminhos.

ion.timestamp.serialization_offset

Opcional

Padrão: 'Z'

Valores: OFFSET, em que OFFSET é representado como <signal>hh:mm. Valores de exemplo: 01:00, +01:00, -09:30, Z (UTC, mesmo que 00:00)

Ao contrário dos carimbos de data/hora do Apache Hive, que não têm fuso horário incorporado e são armazenados como um deslocamento da época UNIX, os carimbos de data/hora do Amazon Ion têm um deslocamento. Use essa propriedade para especificar o deslocamento na serialização para o Amazon Ion.

O exemplo a seguir adiciona um deslocamento de uma hora.

'ion.timestamp.serialization_offset' = '+01:00'       

ion.serialize_null

Opcional

Padrão: OMIT

Valores: OMIT, UNTYPED, TYPED

O Amazon Ion SerDe pode ser configurado para serializar ou omitir colunas que tenham valores nulos. Você pode optar por gravar nulos fortemente tipados (TYPED) ou nulos não tipados (UNTYPED). Nulos fortemente tipados são determinados com base no mapeamento padrão de tipos entre o Amazon Ion e o Hive.

O exemplo a seguir especifica nulos fortemente tipados.

'ion.serialize_null'='TYPED'

ion.ignore_malformed

Opcional

Padrão: false

Valores: true, false

Quando for definida como true, a propriedade ignorará as entradas malformadas ou todo o arquivo se o SerDe não conseguir lê-lo. Para obter mais informações, consulte Ignore malformed (Ignorar entradas malformadas) na documentação do GitHub.

ion.<column>.serialize_as

Opcional

Padrão: tipo padrão para a coluna.

Valores: string contendo o tipo do Amazon Ion

Determina o tipo de dado do Amazon Ion no qual um valor é serializado. Como os tipos do Amazon Ion e do Hive nem sempre têm um mapeamento direto, alguns tipos do Hive têm vários tipos de dados válidos para serialização. Para serializar dados como um tipo de dado não padrão, use essa propriedade. Para obter mais informações sobre o mapeamento de tipos, consulte a página Type mapping (Mapeamento de tipos) do Amazon Ion no GitHub.

Por padrão, as colunas binárias do Hive são serializadas como blobs do Amazon Ion, mas também podem ser serializadas como um clob do Amazon Ion (objeto grande de caracteres). O exemplo a seguir serializa a coluna example_hive_binary_column como um clob.

'ion.example_hive_binary_column.serialize_as' = 'clob'