# Amazon Ion Hive SerDe
<a name="ion-serde"></a>

Você pode usar o Amazon Ion Hive SerDe para consultar dados armazenados no formato [Amazon Ion](https://amzn.github.io/ion-docs/guides/cookbook.html). O Amazon Ion é um formato de dados de código aberto ricamente tipado e autodescritivo. O formato do Amazon Ion é usado na linguagem de consulta SQL de código aberto [PartiQL](https://partiql.org/).

O Amazon Ion tem formatos binários e de texto intercambiáveis. Esse recurso combina a facilidade de uso do texto com a eficiência da codificação binária.

Para consultar dados do Amazon Ion no Athena, você pode usar o [Amazon Ion Hive SerDe](https://github.com/amzn/ion-hive-serde), que serializa e desserializa os dados do Amazon Ion. A desserialização permite que você execute consultas nos dados do Amazon Ion ou leia os dados para gravá-los em um formato diferente, como Parquet ou ORC. A serialização permite gerar dados no formato Amazon Ion usando consultas `CREATE TABLE AS SELECT` (CTAS) ou `INSERT INTO` para copiar dados de tabelas existentes.

**nota**  
Como o Amazon Ion é um superconjunto de JSON, você pode usar o Amazon Ion Hive SerDe para consultar conjuntos de dados JSON em formatos diferentes do Amazon Ion. Ao contrário de outras [bibliotecas de SerDe JSON](https://docs.aws.amazon.com/athena/latest/ug/json-serde.html), o Amazon Ion SerDe não espera que cada linha de dados esteja em uma única linha. Esse recurso é útil quando você deseja consultar conjuntos de dados JSON que passaram por reformatação automática ou usar caracteres de nova linha para dividir os campos em uma linha.

Para obter informações adicionais e exemplos de como consultar o Amazon Ion com o Athena, consulte [Analise conjuntos de dados do Amazon Ion usando o Amazon Athena](https://aws.amazon.com/blogs/big-data/analyze-amazon-ion-datasets-using-amazon-athena/).

## Nome da biblioteca de serialização
<a name="library-name"></a>

O nome da biblioteca de serialização do Amazon Ion SerDe é `com.amazon.ionhiveserde.IonHiveSerDe`. Para obter informações sobre o código-fonte, consulte [Amazon Ion Hive SerDe](https://github.com/amazon-ion/ion-hive-serde) em GitHub.com.

## Considerações e limitações
<a name="ion-serde-considerations-and-limitations"></a>
+ **Campos duplicados**: as structs do Amazon Ion são ordenadas e oferecem suporte a campos duplicados, o que não acontece com `STRUCT<>` e `MAP<>` do Hive. Assim, quando você desserializa um campo duplicado de uma struct do Amazon Ion, um único valor é escolhido de forma não determinística e os outros são ignorados.
+ **Tabelas de símbolos externos sem suporte**: atualmente, o Athena não oferece suporte a tabelas de símbolos externos ou às seguintes propriedades do Amazon Ion Hive SerDe:
  + `ion.catalog.class`
  + `ion.catalog.file`
  + `ion.catalog.url`
  + `ion.symbol_table_imports`
+ **Extensões de arquivo**: o Amazon Ion usa extensões de arquivo para determinar o codec de compactação a ser usado na desserialização de arquivos do Amazon Ion. Assim, os arquivos compactados devem ter a extensão que corresponde ao algoritmo de compactação usado. Por exemplo, se for usado o ZSTD, os arquivos correspondentes deverão ter a extensão `.zst`.
+ **Dados homogêneos**: o Amazon Ion não tem restrições de tipos de dados que podem ser usados como valores em campos específicos. Por exemplo, dois documentos diferentes do Amazon Ion podem ter um campo com o mesmo nome que tenha tipos de dados diferentes. No entanto, como o Hive usa um esquema, todos os valores extraídos para uma única coluna do Hive devem ter o mesmo tipo de dado.
+ **Restrições de tipo de chave**: ao serializar dados de outro formato para o Amazon Ion, certifique-se de que o tipo de chave do mapa seja `STRING`, `VARCHAR` ou `CHAR`. Embora o Hive permita usar qualquer tipo de dado primitivo como chave do mapa, os [símbolos do Amazon Ion](https://amzn.github.io/ion-docs/docs/symbols.html) devem ser um tipo de string.
+ **Tipo union**: atualmente, o Athena não oferece suporte ao [tipo union](https://cwiki.apache.org/confluence/display/hive/languagemanual+types/#LanguageManualTypes-UnionTypesunionUnionTypes) do Hive.
+ **Tipo de dados “double”**: no momento, o Amazon Ion não oferece suporte ao tipo de dados `double`.

**Topics**
+ [Nome da biblioteca de serialização](#library-name)
+ [Considerações e limitações](#ion-serde-considerations-and-limitations)
+ [Criar tabelas do Amazon Ion](ion-serde-using-create-table.md)
+ [Usar CTAS e INSERT INTO para criar tabelas do Amazon Ion](ion-serde-using-ctas-and-insert-into-to-create-ion-tables.md)
+ [Referência de propriedade SerDe do Amazon Ion](ion-serde-using-ion-serde-properties.md)
+ [Usar extratores de caminhos](ion-serde-using-path-extractors.md)

# Criar tabelas do Amazon Ion
<a name="ion-serde-using-create-table"></a>

Para criar uma tabela no Athena com dados armazenados no formato Amazon Ion, você pode usar uma das seguintes técnicas em uma instrução CREATE TABLE:
+ Especifique `STORED AS ION`. Neste uso, você não precisa especificar explicitamente o Amazon Ion Hive SerDe. Essa escolha é a opção mais direta.
+ Especifique os caminhos de classe do Amazon Ion nos campos `ROW FORMAT SERDE`, `INPUTFORMAT` e `OUTPUTFORMAT`.

Você também pode usar instruções `CREATE TABLE AS SELECT` (CTAS) para criar tabelas do Amazon Ion no Athena. Para mais informações, consulte [Usar CTAS e INSERT INTO para criar tabelas do Amazon Ion](ion-serde-using-ctas-and-insert-into-to-create-ion-tables.md).

## Especificar STORED AS ION
<a name="ion-serde-specifying-stored-as-ion"></a>

O exemplo a seguir de instrução `CREATE TABLE` usa `STORED AS ION` antes da cláusula `LOCATION` para criar uma tabela com base em dados de voo no formato Amazon Ion. A cláusula `LOCATION` especifica o bucket ou a pasta em que estão localizados os arquivos de entrada no formato Ion. Todos os arquivos no local especificado estão verificados.

```
CREATE EXTERNAL TABLE flights_ion (
    yr INT,
    quarter INT,
    month INT,
    dayofmonth INT,
    dayofweek INT,
    flightdate STRING,
    uniquecarrier STRING,
    airlineid INT,
)
STORED AS ION
LOCATION 's3://amzn-s3-demo-bucket/'
```

## Especificar caminhos de classe do Amazon Ion
<a name="ion-serde-specifying-the-ion-class-paths"></a>

Em vez de usar a sintaxe `STORED AS ION`, você pode especificar explicitamente os valores de caminho de classe do Ion para as cláusulas `ROW FORMAT SERDE`, `INPUTFORMAT` e `OUTPUTFORMAT`, como mostrado a seguir.


****  

| Parâmetro | Caminho de classe do Ion | 
| --- | --- | 
| ROW FORMAT SERDE | 'com.amazon.ionhiveserde.IonHiveSerDe' | 
| STORED AS INPUTFORMAT | 'com.amazon.ionhiveserde.formats.IonInputFormat' | 
| OUTPUTFORMAT | 'com.amazon.ionhiveserde.formats.IonOutputFormat' | 

A consulta DDL a seguir usa essa técnica para criar a mesma tabela externa do exemplo anterior.

```
CREATE EXTERNAL TABLE flights_ion (
    yr INT,
    quarter INT,
    month INT,
    dayofmonth INT,
    dayofweek INT,
    flightdate STRING,
    uniquecarrier STRING,
    airlineid INT,
)
ROW FORMAT SERDE
 'com.amazon.ionhiveserde.IonHiveSerDe'
STORED AS INPUTFORMAT
 'com.amazon.ionhiveserde.formats.IonInputFormat'
OUTPUTFORMAT
 'com.amazon.ionhiveserde.formats.IonOutputFormat'
LOCATION 's3://amzn-s3-demo-bucket/'
```

Para obter informações sobre as propriedades SerDe para instruções `CREATE TABLE` no Athena, consulte [Referência de propriedade SerDe do Amazon Ion](ion-serde-using-ion-serde-properties.md).

# Usar CTAS e INSERT INTO para criar tabelas do Amazon Ion
<a name="ion-serde-using-ctas-and-insert-into-to-create-ion-tables"></a>

Você pode usar as instruções `CREATE TABLE AS SELECT` (CTAS) e `INSERT INTO` para copiar ou inserir dados de uma tabela em uma nova tabela no formato Amazon Ion no Athena.

Em uma consulta CTAS, especifique `format='ION'` na cláusula `WITH`, como no exemplo a seguir.

```
CREATE TABLE new_table
WITH (format='ION')
AS SELECT * from existing_table
```

Por padrão, o Athena serializa os resultados do Amazon Ion em [formato binário Ion](https://amzn.github.io/ion-docs/docs/binary.html), mas você também pode usar o formato de texto. Para usar o formato de texto, especifique `ion_encoding = 'TEXT'` na cláusula CTAS `WITH`, como no exemplo a seguir.

```
CREATE TABLE new_table
WITH (format='ION', ion_encoding = 'TEXT')
AS SELECT * from existing_table
```

Para obter mais informações sobre as propriedades específicas do Amazon Ion na cláusula `WITH` de CTAS, consulte [Propriedades do Amazon Ion para a cláusula WITH de CTAS](#ion-serde-ctas-with-clause-properties).

## Propriedades do Amazon Ion para a cláusula WITH de CTAS
<a name="ion-serde-ctas-with-clause-properties"></a>

Em uma consulta CTAS, você pode usar a cláusula `WITH` para especificar o formato Amazon Ion e, opcionalmente, especificar a codificação do Amazon Ion e/ou o algoritmo de compactação a usar.

**formato**  
Você pode especificar a palavra-chave `ION` como a opção de formato na cláusula `WITH` de uma consulta CTAS. Ao fazer isso, a tabela que você cria usa o formato especificado de `IonInputFormat` para leituras e serializa dados no formato especificado de `IonOutputFormat`.  
O exemplo a seguir especifica que a consulta CTAS usa o formato Amazon Ion.  

```
WITH (format='ION')
```

**ion\$1encoding**  
Opcional  
Padrão: `BINARY`  
Valores: `BINARY`, `TEXT`  
Especifica se os dados são serializados no formato binário ou no formato de texto do Amazon Ion. O exemplo a seguir especifica o formato de texto do Amazon Ion.  

```
WITH (format='ION', ion_encoding='TEXT')
```

**write\$1compression**  
Opcional  
Padrão: `GZIP`  
Valores: `GZIP`, `ZSTD`, `BZIP2`, `SNAPPY`, `NONE`  
Especifica o algoritmo de compactação a ser usado para compactar os arquivos de saída.  
O exemplo a seguir especifica que a consulta CTAS grava a saída no formato Amazon Ion usando o algoritmo de compactação [Zstandard](https://facebook.github.io/zstd/).  

```
WITH (format='ION', write_compression = 'ZSTD')       
```
Para obter mais informações sobre compactação de dados no Athena, consulte [Usar compactação no Athena](compression-formats.md). 

Para obter informações sobre outras propriedades de CTAS em Athena, consulte [Propriedades da tabela CTAS](create-table-as.md#ctas-table-properties).

# 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'       
```

# Usar extratores de caminhos
<a name="ion-serde-using-path-extractors"></a>

O Amazon Ion é um formato de arquivo em estilo de documento, mas o Apache Hive é um formato de coluna simples. Você pode usar propriedades especiais do Amazon Ion SerDe, chamadas de `path extractors`, para fazer o mapeamento entre os dois formatos. Os extratores de caminhos nivelam o formato hierárquico do Amazon Ion, mapeiam valores do Amazon Ion em relação às colunas do Hive e podem ser usados para renomear campos.

O Athena pode gerar seus extratores, mas você também poderá definir os próprios extratores, se necessário.

**Topics**
+ [Usar extratores de caminhos gerados pelo Athena](ion-serde-generated-path-extractors.md)
+ [Especificar seus próprios extratores de caminhos](ion-serde-specifying-your-own-path-extractors.md)
+ [Usar caminhos de pesquisa em extratores de caminhos](ion-serde-using-search-paths-in-path-extractors.md)
+ [Exemplos de extratores de caminhos](ion-serde-examples.md)

# Usar extratores de caminhos gerados pelo Athena
<a name="ion-serde-generated-path-extractors"></a>

Por padrão, o Athena pesquisa valores de nível superior do Amazon Ion que correspondam aos nomes de coluna do Hive e cria extratores de caminhos em tempo de execução com base nesses valores. Se o formato de dados do Amazon Ion corresponder ao esquema da tabela do Hive, o Athena gerará dinamicamente os extratores e você não precisará adicionar nenhum extrator de caminho adicional. Esses extratores de caminhos padrão não são armazenados nos metadados da tabela.

O exemplo a seguir mostra como o Athena gera extratores com base no nome da coluna.

```
-- Example Amazon Ion Document
{
    identification: {
        name: "John Smith",
        driver_license: "XXXX"
    },
    
    alias: "Johnny"    
}

-- Example DDL
CREATE EXTERNAL TABLE example_schema2 (
    identification MAP<STRING, STRING>,
    alias STRING
)
STORED AS ION
LOCATION 's3://amzn-s3-demo-bucket/path_extraction1/'
```

Os extratores no exemplo a seguir são gerados pelo Athena. O primeiro extrai o campo `identification` para a coluna `identification`, e o segundo extrai o campo `alias` para a coluna `alias`.

```
'ion.identification.path_extractor' = '(identification)'
'ion.alias.path_extractor' = '(alias)'
```

O exemplo a seguir mostra a tabela extraída.

```
|                  identification                    |  alias   |
|----------------------------------------------------|----------|
|{["name", "driver_license"],["John Smith", "XXXX"]} | "Johnny" |
```

# Especificar seus próprios extratores de caminhos
<a name="ion-serde-specifying-your-own-path-extractors"></a>

Se os campos do Amazon Ion não forem mapeados perfeitamente para as colunas do Hive, você poderá especificar seus próprios extratores de caminhos. Use a sintaxe a seguir na cláusula `WITH SERDEPROPERTIES` da instrução `CREATE TABLE`.

```
WITH SERDEPROPERTIES (
   "ion.path_extractor.case_sensitive" = "<Boolean>", 
   "ion.<column_name>.path_extractor" = "<path_extractor_expression>"
)
```

**nota**  
Por padrão, os extratores de caminhos não diferenciam maiúsculas de minúsculas. Para substituir essa configuração, defina a propriedade SerDe [ion.path_extractor.case_sensitive](ion-serde-using-ion-serde-properties.md#ioncase) como `true`.

# Usar caminhos de pesquisa em extratores de caminhos
<a name="ion-serde-using-search-paths-in-path-extractors"></a>

A sintaxe da propriedade SerDe para extratores de caminhos contém uma *<path\$1extractor\$1expression>*:

```
"ion.<column_name>.path_extractor" = "<path_extractor_expression>"         
```

Você pode usar a *<path\$1extractor\$1expression>* para especificar um caminho de pesquisa que analise o documento do Amazon Ion e encontre os dados correspondentes. O caminho de pesquisa é colocado entre parênteses e pode conter um ou mais dos componentes separados por espaços a seguir.
+ **Curinga**: corresponde todos os valores.
+ **Índice**: corresponde o valor com o índice numérico especificado. Os índices são baseados em zero.
+ **Texto**: corresponde todos os valores cujos nomes de campo são equivalentes ao texto especificado.
+ **Anotações**: correspondem valores especificados por um componente de caminho empacotado com as anotações especificadas.

O exemplo a seguir mostra um documento do Amazon Ion e alguns exemplos de caminhos de pesquisa.

```
-- Amazon Ion document
{
    foo: ["foo1", "foo2"] ,
    bar: "myBarValue", 
    bar: A::"annotatedValue"
}

-- Example search paths
(foo 0)       # matches "foo1"
(1)           # matches "myBarValue"
(*)           # matches ["foo1", "foo2"], "myBarValue" and A::"annotatedValue"
()            # matches {foo: ["foo1", "foo2"] , bar: "myBarValue", bar: A::"annotatedValue"}
(bar)         # matches "myBarValue" and A::"annotatedValue"
(A::bar)      # matches A::"annotatedValue"
```

# Exemplos de extratores de caminhos
<a name="ion-serde-examples"></a>

Os exemplos de extratores de caminhos a seguir mostram como nivelar e renomear campos ou extrair dados como texto do Amazon Ion.

## Nivelar e renomear campos
<a name="ion-serde-flattening-and-renaming-fields"></a>

O exemplo a seguir mostra um conjunto de caminhos de pesquisa que nivelam e renomeiam campos. O exemplo usa caminhos de pesquisa para:
+ Mapear a coluna `nickname` ao campo `alias`
+ Mapear a coluna `name` ao subcampo `name` localizado no struct `identification`.

O exemplo a seguir mostra o documento do Amazon Ion.

```
-- Example Amazon Ion Document
{
    identification: {
        name: "John Smith",
        driver_license: "XXXX"
    },
    
    alias: "Johnny"    
}
```

O exemplo a seguir mostra a instrução `CREATE TABLE` que define os extratores de caminhos.

```
-- Example DDL Query
CREATE EXTERNAL TABLE example_schema2 (
    name STRING,
    nickname STRING
)
ROW FORMAT SERDE
 'com.amazon.ionhiveserde.IonHiveSerDe'
WITH SERDEPROPERTIES (
 'ion.nickname.path_extractor' = '(alias)',
 'ion.name.path_extractor' = '(identification name)'
 )
STORED AS ION
LOCATION 's3://amzn-s3-demo-bucket/path_extraction2/'
```

O exemplo a seguir mostra os dados extraídos.

```
-- Extracted Table
| name         |   nickname   |
|--------------|--------------|
| "John Smith" |  "Johnny"    |
```

Para obter mais informações sobre caminhos de pesquisa e exemplos adicionais, consulte a página [Ion Java Path Extraction](https://github.com/amzn/ion-java-path-extraction) (Extração de caminhos Java em Ion) no GitHub.

## Extrair dados de voo para formato de texto
<a name="ion-serde-extracting-flight-data-to-text-format"></a>

O exemplo de consulta `CREATE TABLE` a seguir usa `WITH SERDEPROPERTIES` para adicionar extratores de caminhos para extrair dados de voo e especificar a codificação de saída como texto do Amazon Ion. O exemplo usa a sintaxe `STORED AS ION`.

```
CREATE EXTERNAL TABLE flights_ion (
    yr INT,
    quarter INT,
    month INT,
    dayofmonth INT,
    dayofweek INT,
    flightdate STRING,
    uniquecarrier STRING,
    airlineid INT,
)
ROW FORMAT SERDE
 'com.amazon.ionhiveserde.IonHiveSerDe'
WITH SERDEPROPERTIES (
 'ion.encoding' = 'TEXT',
 'ion.yr.path_extractor'='(year)',
 'ion.quarter.path_extractor'='(results quarter)',
 'ion.month.path_extractor'='(date month)')
STORED AS ION
LOCATION 's3://amzn-s3-demo-bucket/'
```