# パスエクストラクターを使用する
<a name="ion-serde-using-path-extractors"></a>

Amazon Ion はドキュメントスタイルのファイル形式ですが、Apache Hive はフラットな列指向形式です。`path extractors` という特別な Amazon Ion SerDe プロパティを使用して、この 2 つの形式をマッピングすることができます。パスエクストラクタは、階層的な 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 生成パスエクストラクターを使用する
<a name="ion-serde-generated-path-extractors"></a>

デフォルトでは、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" |
```

# 独自のパスエクストラクターを指定する
<a name="ion-serde-specifying-your-own-path-extractors"></a>

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` に設定します。

# パスエクストラクターで検索パスを使用する
<a name="ion-serde-using-search-paths-in-path-extractors"></a>

パスエクストラクタの SerDe プロパティの構文には *<path\$1extractor\$1expression>* が含まれています。

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

*<path\$1extractor\$1expression>* を使用し、Amazon Ion ドキュメントを解析して一致するデータを検索する検索パスを指定することができます。検索パスは括弧で囲み、次のコンポーネントをスペースで区切って 1 つ以上含めることができます。
+ **ワイルドカード** — すべての値と一致します。
+ **インデックス** — 指定された数値インデックスの値と一致します。インデックスは 0 から始まります。
+ **テキスト** – 指定したテキストと同等のフィールド名を持つすべての値と一致します。
+ **注釈** — 注釈が指定されているラップされたパスコンポーネントで指定された値と一致します。

次に示すのは、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"
```

# パスエクストラクターの例
<a name="ion-serde-examples"></a>

次のパスエクストラクターの例は、フィールドをフラット化して名前を変更する方法、またはデータを Amazon Ion テキストとして抽出する方法を示しています。

## フィールドをフラット化して、名前を変更する
<a name="ion-serde-flattening-and-renaming-fields"></a>

次の例は、フィールドをフラット化して名前を変更する検索パスのセットを示しています。この例では、検索パスを使用して次の処理を実行します。
+ `nickname` 列を `alias` フィールドにマッピングします。
+ `identification` 構造体にある `name` サブフィールドに `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-path-extraction](https://github.com/amzn/ion-java-path-extraction)」(Ion Java パス抽出) ページを参照してください。

## フライトデータをテキスト形式で抽出する
<a name="ion-serde-extracting-flight-data-to-text-format"></a>

次の例の `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/'
```