# 使用路径提取器


Amazon Ion 是一种文档样式的文件格式，但 Apache Hive 是一种平面列式格式。您可以使用名为 `path extractors` 的特殊 Amazon Ion SerDe 属性在两种格式之间进行映射。路径提取器将分层的 Amazon Ion 格式展平，将 Amazon Ion 值映射到 Hive 列，并可用于重命名字段。

Athena 可以为您生成提取器，但如有必要，您也可以定义自己的提取器。

**Topics**
+ [

# 使用 Athena 生成的路径提取器
](ion-serde-generated-path-extractors.md)
+ [

# 指定自己的路径提取器
](ion-serde-specifying-your-own-path-extractors.md)
+ [

# 在路径提取器中使用搜索路径
](ion-serde-using-search-paths-in-path-extractors.md)
+ [

# 路径提取器示例
](ion-serde-examples.md)

# 使用 Athena 生成的路径提取器


默认情况下，Athena 会搜索与 Hive 列名称匹配的顶级 Amazon Ion 值，并根据这些匹配值在运行时创建路径提取器。如果您的 Amazon Ion 数据格式与 Hive 表架构匹配，则 Athena 会动态为您生成提取器，而且您无需添加任何其他路径提取器。这些默认路径提取器不存储于表元数据中。

以下示例演示了 Athena 如何根据列名称生成提取器。

```
-- 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 生成。第一个将 `identification` 字段提取到 `identification` 列，第二个将 `alias` 字段提取到 `alias` 列。

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

以下示例显示提取的表。

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

# 指定自己的路径提取器


如果您的 Amazon Ion 字段没有整齐地映射到 Hive 列，则您可以指定自己的路径提取器。在 `CREATE TABLE` 语句的 `WITH SERDEPROPERTIES` 子句中，请使用以下语法。

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

**注意**  
默认情况下，路径提取器不区分大小写。若要覆盖此设置，请将 [ion.path_extractor.case_sensitive](ion-serde-using-ion-serde-properties.md#ioncase) SerDe 属性设置为 `true`。

# 在路径提取器中使用搜索路径


路径提取器的 SerDe 属性语法包含 *<path\$1extractor\$1expression>*：

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

您可以使用 *<path\$1extractor\$1expression>* 以指定解析 Amazon Ion 文档并查找匹配数据的搜索路径。搜索路径用括号括起来，可以包含以下一个或多个以空格分隔的组件。
+ **通配符** – 匹配所有值。
+ **索引** – 匹配指定数字索引处的值。指数从零开始。
+ **文本** – 匹配字段名称与指定文本匹配的所有值。
+ **注释** – 匹配由具有指定注释的包装路径组件指定的值。

以下示例显示了 Amazon Ion 文档和一些示例搜索路径。

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

# 路径提取器示例


以下路径提取器示例演示如何扁平化和重命名字段或将数据提取为 Amazon Ion 文本。

## 扁平化并重命名字段


以下示例显示了用于拼合和重命名字段的搜索路径。此示例使用搜索路径来执行以下操作：
+ 将 `nickname` 列映射到 `alias` 字段
+ 将 `name` 列映射到位于 `identification` 结构中的 `name` 子字段。

以下是 Amazon Ion 文档示例。

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

以下是定义路径提取器的示例 `CREATE TABLE` 语句。

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

以下示例显示提取的数据。

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

有关搜索路径和其他搜索路径示例的更多信息，请参阅 GitHub 上的 [Ion Java 路径提取](https://github.com/amzn/ion-java-path-extraction)页面。

## 将航班数据提取为文本格式


以下示例 `CREATE TABLE` 查询使用 `WITH SERDEPROPERTIES` 添加路径提取器以提取航班数据，并将输出编码指定为 Amazon Ion 文本。此示例使用 `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/'
```