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