# Referência de propriedade SerDe do Amazon Ion
<a name="ion-serde-using-ion-serde-properties"></a>

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](https://github.com/amzn/ion-hive-serde/blob/master/docs/serde-properties.md) (Propriedades SerDe) na documentação sobre o Amazon Ion Hive SerDe no [GitHub](https://github.com/amzn/ion-hive-serde/tree/master/docs).

## Como especificar propriedades SerDe do Amazon Ion
<a name="ion-serde-specifying-ion-serde-properties"></a>

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
<a name="ion-serde-ion-serde-properties"></a>

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](https://amzn.github.io/ion-docs/docs/binary.html) 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\$1on\$1overflow**  
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\$1extractor.case\$1sensitive**  
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\$1extractor**  
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-serde-using-path-extractors.md).

**ion.timestamp.serialization\$1offset**  
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](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-timestamp) 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\$1null**  
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\$1malformed**  
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](https://github.com/amzn/ion-hive-serde/blob/master/docs/serde-properties.md#ignore-malformed) (Ignorar entradas malformadas) na documentação do GitHub.

**ion.*<column>*.serialize\$1as**  
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](https://github.com/amzn/ion-hive-serde/blob/master/docs/type-mapping.md) (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](https://amzn.github.io/ion-docs/docs/stringclob.html#ion-clob) (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'       
```