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

Puede utilizar el SerDe de Amazon Ion Hive para consultar datos almacenados en formato [Amazon Ion](https://amzn.github.io/ion-docs/guides/cookbook.html). Amazon Ion es un formato de datos altamente codificado, autodescriptivo y de código abierto. El formato Amazon Ion se utiliza en el lenguaje de consultas SQL de código abierto [PartiQL](https://partiql.org/).

Amazon Ion tiene formatos binarios y de texto que son intercambiables. Esta característica combina la facilidad de uso del texto con la eficacia de la codificación binaria.

Para consultar los datos de Amazon Ion desde Athena, puede utilizar el [SerDe de Amazon Ion Hive](https://github.com/amzn/ion-hive-serde), que serializa y deserializa los datos de Amazon Ion. La deserialización permite ejecutar consultas sobre los datos de Amazon Ion o leerlos para escribir en un formato diferente como Parquet u ORC. La serialización permite generar datos en formato Amazon Ion mediante consultas `CREATE TABLE AS SELECT` (CTAS) o `INSERT INTO` para copiar datos de tablas existentes.

**nota**  
Dado que Amazon Ion es un superconjunto de JSON, puede utilizar el SerDe de Amazon Ion Hive para consultar conjuntos de datos JSON que no sean de Amazon Ion. A diferencia de otras [bibliotecas de SerDe JSON](https://docs.aws.amazon.com/athena/latest/ug/json-serde.html), el SerDe de Amazon Ion no espera que cada fila de datos esté en una sola línea. Esta característica resulta útil si desea consultar conjuntos de datos JSON que presentan “un buen formato de impresión” o dividir los campos en una fila con caracteres de nueva línea.

Para obtener información adicional y ejemplos de consultas de Amazon Ion con Athena, consulte [Analizar conjuntos de datos de Amazon Ion con Amazon Athena](https://aws.amazon.com/blogs/big-data/analyze-amazon-ion-datasets-using-amazon-athena/).

## Nombre de la biblioteca de serialización
<a name="library-name"></a>

El nombre de la biblioteca de serialización de SerDe de Amazon Ion es `com.amazon.ionhiveserde.IonHiveSerDe`. Para obtener información sobre el código fuente, consulte [Amazon Ion Hive SerDe](https://github.com/amazon-ion/ion-hive-serde) en GitHub.com.

## Consideraciones y limitaciones
<a name="ion-serde-considerations-and-limitations"></a>
+ **Campos duplicados**: las estructuras de Amazon Ion están ordenadas y admiten campos duplicados, mientras que `STRUCT<>` y `MAP<>` de Hive no lo hacen. Por lo tanto, cuando se deserializa un campo duplicado de una estructura de Amazon Ion, se elige un solo valor de forma no determinista y los demás se ignoran.
+ **Tablas de símbolos externas no compatibles**: en la actualidad, Athena no admite tablas de símbolos externas ni las siguientes propiedades del SerDe de Amazon Ion Hive:
  + `ion.catalog.class`
  + `ion.catalog.file`
  + `ion.catalog.url`
  + `ion.symbol_table_imports`
+ **Extensiones de archivo**: Amazon Ion utiliza extensiones de archivo para determinar qué códec de compresión se debe utilizar para deserializar archivos de Amazon Ion. Por lo tanto, los archivos comprimidos deben tener la extensión de archivo que corresponde al algoritmo de compresión utilizado. Por ejemplo, si se utiliza ZSTD, los archivos correspondientes deben tener la extensión `.zst`.
+ **Datos homogéneos**: Amazon Ion no tiene restricciones sobre los tipos de datos que se pueden utilizar para valores en campos determinados. Por ejemplo, dos documentos de Amazon Ion diferentes pueden tener un campo con el mismo nombre, pero con tipos de datos diferentes. Sin embargo, dado que Hive utiliza un esquema, todos los valores que se extraen en una sola columna de Hive deben tener el mismo tipo de datos.
+ **Restricciones del tipo de clave de asignación**: cuando serialice datos de otro formato en Amazon Ion, asegúrese de que el tipo de clave de asignación sea uno de los siguientes: `STRING`, `VARCHAR`, o `CHAR`. Si bien Hive permite utilizar cualquier tipo de datos primitivo como clave de asignación, los [símbolos de Amazon Ion](https://amzn.github.io/ion-docs/docs/symbols.html) deben ser de tipo cadena.
+ **Tipo de unión**: Athena no admite actualmente el [tipo de unión](https://cwiki.apache.org/confluence/display/hive/languagemanual+types/#LanguageManualTypes-UnionTypesunionUnionTypes) de Hive.
+ **Tipo de datos double**: Amazon Ion no admite actualmente el tipo de datos `double`.

**Topics**
+ [Nombre de la biblioteca de serialización](#library-name)
+ [Consideraciones y limitaciones](#ion-serde-considerations-and-limitations)
+ [Creación de tablas de Amazon Ion](ion-serde-using-create-table.md)
+ [Uso de CTAS e INSERT INTO para crear tablas de Amazon Ion](ion-serde-using-ctas-and-insert-into-to-create-ion-tables.md)
+ [Referencia de la propiedad de SerDe de Amazon Ion](ion-serde-using-ion-serde-properties.md)
+ [Uso de extractores de rutas](ion-serde-using-path-extractors.md)

# Creación de tablas de Amazon Ion
<a name="ion-serde-using-create-table"></a>

Para crear una tabla en Athena a partir de los datos almacenados en formato Amazon Ion, puede utilizar una de las siguientes técnicas en una instrucción CREATE TABLE:
+ Especifique: . `STORED AS ION`. En este uso, no es necesario que especifique el SerDe de Amazon Ion Hive de forma explícita. Esta elección es la opción más sencilla.
+ Especifique las rutas de clases de Amazon Ion en los campos `ROW FORMAT SERDE`, `INPUTFORMAT`, y `OUTPUTFORMAT`.

También puede utilizar las instrucciones `CREATE TABLE AS SELECT` (CTAS) para crear tablas de Amazon Ion en Athena. Para obtener más información, consulte [Uso de CTAS e INSERT INTO para crear tablas de Amazon Ion](ion-serde-using-ctas-and-insert-into-to-create-ion-tables.md).

## Especificación de STORED AS ION
<a name="ion-serde-specifying-stored-as-ion"></a>

La próxima instrucción `CREATE TABLE` de ejemplo utiliza `STORED AS ION` antes de la cláusula `LOCATION` para crear una tabla basada en datos de vuelos en formato Amazon Ion. La cláusula `LOCATION` especifica el bucket o la carpeta donde se encuentran los archivos de entrada en formato Ion. Se analizan todos los archivos de la ubicación especificada.

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

## Especificación de las rutas de clases de Amazon Ion
<a name="ion-serde-specifying-the-ion-class-paths"></a>

En lugar de utilizar la sintaxis `STORED AS ION`, puede especificar de forma explícita los valores de la ruta de clase de Ion para las cláusulas `ROW FORMAT SERDE`, `INPUTFORMAT`, y `OUTPUTFORMAT` de la siguiente manera.


****  

| Parámetro | Ruta de clase de Ion | 
| --- | --- | 
| ROW FORMAT SERDE | 'com.amazon.ionhiveserde.IonHiveSerDe' | 
| STORED AS INPUTFORMAT | 'com.amazon.ionhiveserde.formats.IonInputFormat' | 
| OUTPUTFORMAT | 'com.amazon.ionhiveserde.formats.IonOutputFormat' | 

La siguiente consulta DDL utiliza esta técnica para crear la misma tabla externa que en el ejemplo 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 obtener información sobre las propiedades del SerDe para instrucciones `CREATE TABLE` en Athena, consulte [Referencia de la propiedad de SerDe de Amazon Ion](ion-serde-using-ion-serde-properties.md).

# Uso de CTAS e INSERT INTO para crear tablas de Amazon Ion
<a name="ion-serde-using-ctas-and-insert-into-to-create-ion-tables"></a>

Puede utilizar las instrucciones `CREATE TABLE AS SELECT` (CTAS) y `INSERT INTO` para copiar o insertar los datos de una tabla en una tabla nueva en formato de Amazon Ion en Athena.

En una consulta CTAS, especifique `format='ION'` en la cláusula `WITH`, como en el siguiente ejemplo.

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

Athena serializa de forma predeterminada los resultados de Amazon Ion en [formato binario Ion](https://amzn.github.io/ion-docs/docs/binary.html), pero también se puede utilizar el formato de texto. Para utilizar el formato de texto, especifique `ion_encoding = 'TEXT'` en la cláusula `WITH` de la CTAS, como en el siguiente ejemplo.

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

Para más información sobre las propiedades específicas de Amazon Ion en la cláusula `WITH` de CTAS, consulte [Propiedades de Amazon Ion para la cláusula WITH de CTAS](#ion-serde-ctas-with-clause-properties).

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

En una consulta CTAS, puede utilizar la cláusula `WITH` para especificar el formato de Amazon Ion y, opcionalmente, especificar la codificación o el algoritmo de compresión de escritura de Amazon Ion que se utilizará.

**format**  
Puede especificar la palabra clave `ION` como opción de formato en la cláusula `WITH` de una consulta CTAS. Cuando hace esto, la tabla que crea utiliza el formato que especifica para `IonInputFormat` para las lecturas, y serializa los datos en el formato que especifica para `IonOutputFormat`.  
En el siguiente ejemplo, se especifica que la consulta CTAS utiliza el formato de Amazon Ion.  

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

**ion\$1encoding**  
Opcional  
Valor predeterminado: `BINARY`  
Valores: `BINARY`, `TEXT`  
Especifica si los datos se serializan en formato binario de Amazon Ion o en formato de texto de Amazon Ion. En el siguiente ejemplo, se especifica el formato de texto de Amazon Ion.  

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

**write\$1compression**  
Opcional  
Valor predeterminado: `GZIP`  
Valores: `GZIP`, `ZSTD`, `BZIP2`, `SNAPPY`, `NONE`  
Especifica el algoritmo de compresión que se utilizará para comprimir los archivos de salida.  
En el siguiente ejemplo, se especifica que la consulta CTAS escribe su salida en formato de Amazon Ion mediante el algoritmo de compresión [Zstandard](https://facebook.github.io/zstd/).  

```
WITH (format='ION', write_compression = 'ZSTD')       
```
Para obtener información sobre el uso de la compresión en Athena, consulte [Uso de la compresión en Athena](compression-formats.md). 

Para obtener información sobre otras propiedades de CTAS en Athena, consulte [Propiedades de la tabla CTAS](create-table-as.md#ctas-table-properties).

# Referencia de la propiedad de SerDe de Amazon Ion
<a name="ion-serde-using-ion-serde-properties"></a>

Este tema contiene información sobre las propiedades del SerDe para instrucciones `CREATE TABLE` en Athena. Si desea obtener más información y ejemplos del uso de las propiedades del SerDe de Amazon Ion, consulte [Propiedades del SerDe](https://github.com/amzn/ion-hive-serde/blob/master/docs/serde-properties.md) en la documentación de Amazon Ion Hive SerDe en [GitHub](https://github.com/amzn/ion-hive-serde/tree/master/docs).

## Cómo especificar las propiedades de SerDe de Amazon Ion
<a name="ion-serde-specifying-ion-serde-properties"></a>

Para especificar las propiedades del SerDe de Amazon Ion Hive en la instrucción `CREATE TABLE`, utilice la cláusula `WITH SERDEPROPERTIES`. Dado que `WITH SERDEPROPERTIES` es un subcampo de la cláusula `ROW FORMAT SERDE`, primero debe especificar `ROW FORMAT SERDE` y la ruta de clase del SerDe de Amazon Ion Hive, como se muestra en la siguiente sintaxis.

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

Tenga en cuenta que si bien la cláusula `ROW FORMAT SERDE` es necesaria si desea utilizar `WITH SERDEPROPERTIES`, puede utilizar `STORED AS ION` o las sintaxis más largas `INPUTFORMAT` y `OUTPUTFORMAT` para especificar el formato Amazon Ion.

## Propiedades del SerDe de Amazon Ion
<a name="ion-serde-ion-serde-properties"></a>

A continuación, se presentan las propiedades del SerDe de Amazon Ion que se pueden utilizar en instrucciones `CREATE TABLE` en Athena.

**ion.encoding**  
Opcional  
Valor predeterminado: `BINARY`  
Valores: `BINARY`, `TEXT`  
Esta propiedad declara si los valores nuevos agregados se serializan como formato [binario Amazon Ion](https://amzn.github.io/ion-docs/docs/binary.html) o formato de texto Amazon Ion.  
En la siguiente propiedad del SerDe de ejemplo se especifica el formato de texto Amazon Ion.  

```
'ion.encoding' = 'TEXT'
```

**ion.fail\$1on\$1overflow**  
Opcional  
Valor predeterminado: `true`  
Valores: `true`, `false`  
Amazon Ion permite tipos numéricos arbitrariamente grandes, mientras que Hive no lo permite. El SerDe falla de forma predeterminada si el valor de Amazon Ion no se ajusta a la columna de Hive. Sin embargo, usted puede utilizar la opción de configuración `fail_on_overflow` para permitir que el valor se desborde en lugar de fallar.  
Esta propiedad se puede configurar a nivel de tabla o de columna. Para configurarla a nivel de tabla, especifique `ion.fail_on_overflow` como en el siguiente ejemplo. Esto configura el comportamiento predeterminado de todas las columnas.  

```
'ion.fail_on_overflow' = 'true'
```
Para controlar una columna específica, especifique el nombre de la columna entre `ion` y `fail_on_overflow`, delimitado por puntos, como en el siguiente ejemplo.  

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

**ion.path\$1extractor.case\$1sensitive**  
Opcional  
Predeterminado: `false`  
Valores: `true`, `false`  
Determina si se debe hacer distinción entre mayúsculas y minúsculas en los nombres de los campos de Amazon Ion. Cuando es `false`, el SerDe ignora el análisis de mayúsculas y minúsculas de los nombres de los campos de Amazon Ion.  
Por ejemplo, supongamos que usted tiene un esquema de tabla de Hive que define un campo `alias` en minúsculas y un documento de Amazon Ion con un campo `alias` y un campo `ALIAS`, como en el siguiente ejemplo.  

```
-- Hive Table Schema
alias: STRING

-- Amazon Ion Document
{ 'ALIAS': 'value1'} 
{ 'alias': 'value2'}
```
En el siguiente ejemplo, se muestran las propiedades del SerDe y la tabla resultante que se extrae cuando la distinción entre mayúsculas y minúsculas se establece en `false`:  

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

--Extracted Table
| alias    |
|----------|
| "value1" |
| "value2" |
```
En el siguiente ejemplo, se muestran las propiedades del SerDe y la tabla resultante que se extrae cuando la distinción entre mayúsculas y minúsculas se establece en `true`:  

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

--Extracted Table
| alias    |
|----------|
| "value2" |
```
En el segundo caso, `value1` para el campo `ALIAS` se ignora cuando la distinción entre mayúsculas y minúsculas se establece en `true` y el extractor de rutas se especifica como `alias`.

**ion.*<column>*.path\$1extractor**  
Opcional  
Predeterminado: N/A  
Valores: cadena con ruta de búsqueda  
Crea un extractor de rutas con la ruta de búsqueda especificada para la columna determinada. Los extractores de rutas asignan campos de Amazon Ion a las columnas de Hive. Si no se especifica ningún extractor de rutas, Athena crea de forma dinámica extractores de rutas en tiempo de ejecución en función de los nombres de las columnas.  
En el siguiente extractor de rutas de ejemplo se asigna el `example_ion_field` a la `example_hive_column`.  

```
'ion.example_hive_column.path_extractor' = '(example_ion_field)'
```
Si desea obtener más información sobre los extractores de rutas y las rutas de búsqueda, consulte [Uso de extractores de rutas](ion-serde-using-path-extractors.md).

**ion.timestamp.serialization\$1offset**  
Opcional  
Valor predeterminado: `'Z'`  
Valores: `OFFSET`, donde `OFFSET ` está representado como `<signal>hh:mm`. Valores de ejemplo: `01:00`, `+01:00`, `-09:30`, `Z` (UTC, igual que 00:00)  
A diferencia de las [marcas temporales](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-timestamp) de Apache Hive, que no tienen zona horaria integrada y se almacenan como una diferencia horaria de la fecha de inicio de UNIX, las marcas temporales de Amazon Ion sí tienen una diferencia horaria. Utilice esta propiedad para especificar la diferencia horaria cuando serialice en Amazon Ion.  
En el siguiente ejemplo , se agrega una diferencia horaria de una hora.  

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

**ion.serialize\$1null**  
Opcional  
Valor predeterminado: `OMIT`  
Valores: `OMIT`, `UNTYPED`, `TYPED`  
El SerDe de Amazon Ion se puede configurar para que serialice u omita columnas que tengan valores nulos. Puede elegir escribir valores nulos con tipos sólidos (`TYPED`) o valores nulos sin tipo alguno (`UNTYPED`). Los valores nulos con tipos sólidos se determinan en función de la asignación de tipos predeterminada de Amazon Ion para Hive.  
En el siguiente ejemplo, se especifican valores nulos con tipos sólidos.  

```
'ion.serialize_null'='TYPED'
```

**ion.ignore\$1malformed**  
Opcional  
Predeterminado: `false`  
Valores: `true`, `false`  
Cuando es `true`, se ignoran las entradas con formato incorrecto o se ignora el archivo completo si el SerDe no puede leerlo. Para obtener más información, consulte [Ignorar elementos con formato incorrecto](https://github.com/amzn/ion-hive-serde/blob/master/docs/serde-properties.md#ignore-malformed) en la documentación de GitHub.

**ion.*<column>*.serialize\$1as**  
Opcional  
Predeterminado: tipo predeterminado para la columna.  
Valores: cadena que contiene el tipo de Amazon Ion  
Determina el tipo de datos de Amazon Ion en el que se serializa un valor. Dado que los tipos de Amazon Ion y Hive no siempre tienen una asignación directa, algunos tipos de Hive tienen varios tipos de datos válidos para la serialización. Para serializar los datos como un tipo de datos no predeterminado, utilice esta propiedad. Si desea obtener más información sobre la asignación de tipos, consulte la página [Asignación de tipos](https://github.com/amzn/ion-hive-serde/blob/master/docs/type-mapping.md) de Amazon Ion en GitHub.  
Las columnas binarias de Hive se serializan de forma predeterminada como blobs de Amazon Ion, pero también se pueden serializar como un [clob de Amazon Ion](https://amzn.github.io/ion-docs/docs/stringclob.html#ion-clob), es decir, un objeto grande de caracteres. En el siguiente ejemplo, se serializa la columna `example_hive_binary_column` como un clob.  

```
'ion.example_hive_binary_column.serialize_as' = 'clob'       
```

# Uso de extractores de rutas
<a name="ion-serde-using-path-extractors"></a>

Amazon Ion es un formato de archivo de estilo de documento. Por otro lado, Apache Hive es un formato de columnas plano. Puede utilizar las propiedades especiales del SerDe de Amazon Ion denominadas `path extractors` para asignar entre los dos formatos. Los extractores de rutas aplanan el formato Amazon Ion jerárquico, asignan valores de Amazon Ion a columnas de Hive y se pueden utilizar para cambiar los nombres de los campos.

Athena puede generar los extractores por usted; sin embargo, usted también puede definir sus propios extractores si es necesario.

**Topics**
+ [Utilice extractores de rutas generados por Athena](ion-serde-generated-path-extractors.md)
+ [Especificación de sus propios extractores de rutas](ion-serde-specifying-your-own-path-extractors.md)
+ [Uso de rutas de búsqueda en extractores de rutas](ion-serde-using-search-paths-in-path-extractors.md)
+ [Ejemplos de extractores de rutas](ion-serde-examples.md)

# Utilice extractores de rutas generados por Athena
<a name="ion-serde-generated-path-extractors"></a>

Athena busca de forma predeterminada valores de Amazon Ion de nivel superior que coincidan con los nombres de las columnas de Hive y crea extractores de rutas en tiempo de ejecución en función de estos valores coincidentes. Si el formato de datos de Amazon Ion coincide con el esquema de tabla de Hive, Athena genera de forma dinámica los extractores por usted y usted no necesita agregar ningún extractor de ruta adicional. Estos extractores de rutas predeterminados no se almacenan en los metadatos de la tabla.

En el siguiente ejemplo, se muestra cómo Athena genera extractores en función del nombre de la columna.

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

Athena genera los siguientes extractores de ejemplo. El primero extrae el campo `identification` a la columna `identification` y el segundo extrae el campo `alias` a la columna `alias`.

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

En el siguiente ejemplo, se muestra la tabla que se extrajo.

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

# Especificación de sus propios extractores de rutas
<a name="ion-serde-specifying-your-own-path-extractors"></a>

Si los campos de Amazon Ion no se asignan de forma perfecta a las columnas de Hive, puede especificar sus propios extractores de ruta. En la cláusula `WITH SERDEPROPERTIES` de la instrucción `CREATE TABLE`, utilice la siguiente sintaxis.

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

**nota**  
Los extractores de rutas distinguen entre mayúsculas y minúsculas de forma predeterminada. Para anular esta configuración, configure la propiedad del SerDe [ion.path_extractor.case_sensitive](ion-serde-using-ion-serde-properties.md#ioncase) en `true`.

# Uso de rutas de búsqueda en extractores de rutas
<a name="ion-serde-using-search-paths-in-path-extractors"></a>

La sintaxis de la propiedad del SerDe para el extractor de ruta contiene *<path\$1extractor\$1expression>*:

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

Puede utilizar *<path\$1extractor\$1expression>* para especificar una ruta de búsqueda que analice el documento de Amazon Ion y encuentre datos coincidentes. La ruta de búsqueda está entre paréntesis y puede contener uno o más de los siguientes componentes separados por espacios.
+ **Comodín**: coincide con todos los valores.
+ **Índice**: coincide con el valor del índice numérico especificado. Los índices están basados en cero.
+ **Texto**: coincide con todos los valores cuya coincidencia de nombres de campo son equivalentes al texto especificado.
+ **Anotaciones**: coincide con los valores especificados por un componente de ruta encapsulado que tiene las anotaciones especificadas.

En el siguiente ejemplo, se muestra un documento de Amazon Ion y algunas rutas de búsqueda de ejemplo.

```
-- 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"
```

# Ejemplos de extractores de rutas
<a name="ion-serde-examples"></a>

En los ejemplos siguientes de extractores de rutas se muestra cómo aplanar los campos y cambiarles el nombre o extraer datos como texto de Amazon Ion.

## Aplanado y cambio de nombre de los campos
<a name="ion-serde-flattening-and-renaming-fields"></a>

En el siguiente ejemplo, se muestra un conjunto de rutas de búsqueda que aplanan y cambian los nombres de los campos. En el ejemplo, se utilizan las rutas de búsqueda para hacer lo siguiente:
+ asignar la columna `nickname` al campo `alias` y
+ asignar la columna `name` al subcampo `name` ubicado en la estructura `identification`.

A continuación, se presenta el documento de Amazon Ion de ejemplo.

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

A continuación, se muestra la instrucción `CREATE TABLE` de ejemplo que define los extractores de rutas.

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

En el siguiente ejemplo, se muestran los datos extraídos.

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

Para obtener más información sobre las rutas de búsqueda y ejemplos de rutas de búsqueda adicionales, consulte [Extracción de rutas Ion Java](https://github.com/amzn/ion-java-path-extraction) en GitHub.

## Extracción de datos de vuelo en formato de texto
<a name="ion-serde-extracting-flight-data-to-text-format"></a>

En el siguiente ejemplo, la consulta `CREATE TABLE` utiliza `WITH SERDEPROPERTIES` para agregar extractores de rutas con el objetivo de extraer datos de vuelo y especificar la codificación de salida como texto de Amazon Ion. En el ejemplo se utiliza la sintaxis `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/'
```