# Amazon Ion SerDe プロパティリファレンス
<a name="ion-serde-using-ion-serde-properties"></a>

このトピックでは、Athena の `CREATE TABLE` ステートメントに使用できる SerDe プロパティについて説明します。Amazon Ion SerDe プロパティの使用方法の詳細と例については、[GitHub](https://github.com/amzn/ion-hive-serde/tree/master/docs) にある Amazon Ion Hive SerDe ドキュメントの「[SerDe properties](https://github.com/amzn/ion-hive-serde/blob/master/docs/serde-properties.md)」(SerDe プロパティ) を参照してください。

## Amazon Ion SerDe プロパティを指定する方法
<a name="ion-serde-specifying-ion-serde-properties"></a>

`CREATE TABLE` ステートメントで Amazon Ion Hive SerDe のプロパティを指定するには、`WITH SERDEPROPERTIES` 句を使用します。`WITH SERDEPROPERTIES` が `ROW FORMAT SERDE` 句のサブフィールドであるため、次の構文に示すように、まず `ROW FORMAT SERDE` と Amazon Ion Hive SerDe クラスパスを指定する必要があります。

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

ただし、`WITH SERDEPROPERTIES` を使用する場合には `ROW FORMAT SERDE` 句が必須ですが、`STORED AS ION` か、または長めの `INPUTFORMAT` と `OUTPUTFORMAT` Amazon Ion 構文を使用して Amazon Ion 形式を指定できます。

## Amazon Ion SerDe プロパティ
<a name="ion-serde-ion-serde-properties"></a>

Athena の `CREATE TABLE` ステートメントに使用できる Amazon Ion SerDe プロパティは次のとおりです。

**ion.encoding**  
オプションです。  
デフォルト: `BINARY`  
値: `BINARY`、`TEXT`  
このプロパティは、追加された新しい値が [Amazon Ion バイナリ](https://amzn.github.io/ion-docs/docs/binary.html)と Amazon Ion テキストのどちらの形式としてシリアル化されるかを宣言します。  
次の SerDe プロパティの例では、Amazon Ion テキスト形式を指定しています。  

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

**ion.fail\$1on\$1overflow**  
オプションです。  
デフォルト: `true`  
値: `true`、`false`  
Amazon Ion では任意の大きな数値型が許可されますが、Hive では許可されません。デフォルトでは、Amazon Ion の値が Hive 列に収まらないと SerDe が失敗しますが、`fail_on_overflow` 設定オプションを使用すると、失敗ではなく値をオーバーフローさせることができます。  
このプロパティは、テーブルレベルまたは列レベルで設定できます。テーブルレベルで指定するには、以下の例のように `ion.fail_on_overflow` を指定します。これにより、すべての列にデフォルトの動作が設定されます。  

```
'ion.fail_on_overflow' = 'true'
```
特定の列を制御するには、次の例のように、`ion` と `fail_on_overflow` の間に列名をピリオドで区切って指定します。  

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

**ion.path\$1extractor.case\$1sensitive**  
オプションです。  
デフォルト: `false`  
値: `true`、`false`  
Amazon Ion フィールド名の大文字と小文字を区別するかどうかを指定します。`false` の場合、SerDe は Amazon Ion フィールド名を解析するときに大文字と小文字を区別しません。  
例えば、Hive テーブルスキーマに `alias` フィールドを小文字で定義し、Amazon Ion ドキュメントに `alias` フィールドと `ALIAS` フィールドの両方を設定できます。以下に例を示します。  

```
-- Hive Table Schema
alias: STRING

-- Amazon Ion Document
{ 'ALIAS': 'value1'} 
{ 'alias': 'value2'}
```
次の例は、大文字と小文字の区別が `false` に設定されている場合に抽出されるテーブルと、SerDe プロパティを示しています。  

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

--Extracted Table
| alias    |
|----------|
| "value1" |
| "value2" |
```
次の例は、大文字と小文字の区別が `true` に設定されている場合に抽出されるテーブルと、SerDe プロパティを示しています。  

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

--Extracted Table
| alias    |
|----------|
| "value2" |
```
2 番目のケースでは、大文字と小文字の区別が `true` に設定され、パスエクストラクタが `alias` に指定されている場合、`ALIAS` フィールドの `value1` は無視されます。

**ion.*<column>*.path\$1extractor**  
オプションです。  
デフォルト: NA  
値: 検索パスを含む文字列  
指定された列の指定された検索パスが含まれるパスエクストラクタを作成します。パスエクストラクタは、Amazon Ion フィールドを Hive 列にマッピングします。パスエクストラクタを指定しないと、Athena は列名に基づいて実行時に動的にパスエクストラクタを作成します。  
次の例のパスエクストラクタは、`example_ion_field` を `example_hive_column` にマッピングしています。  

```
'ion.example_hive_column.path_extractor' = '(example_ion_field)'
```
パスエクストラクタと検索パスの詳細については、「[パスエクストラクターを使用する](ion-serde-using-path-extractors.md)」を参照してください。

**ion.timestamp.serialization\$1offset**  
オプションです。  
デフォルト: `'Z'`  
値: `OFFSET`。`OFFSET ` は `<signal>hh:mm` として表される。値の例: `01:00`、`+01:00`、`-09:30`、`Z` (UTC、00:00 と同じ)  
Apache Hive の[タイムスタンプ](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-timestamp)は、タイムゾーンが組み込まれておらず、UNIX エポックからのオフセットとして保存されます。一方、Amazon Ion のタイムスタンプにはオフセットがあります。このプロパティを使用して、Amazon Ion にシリアル化するときのオフセットを指定します。  
次の例では、1 時間のオフセットを追加しています。  

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

**ion.serialize\$1null**  
オプションです。  
デフォルト: `OMIT`  
値: `OMIT`、`UNTYPED`、`TYPED`  
Amazon Ion SerDe は、Null 値が含まれる列をシリアル化または省略するように設定できます。厳密に型指定された null (`TYPED`) を書き出すことも、型指定されていない null (`UNTYPED`) を書き出すこともできます。厳密に型指定された null は、デフォルトの Amazon Ion から Hive への型マッピングに基づいて決定されます。  
次の例では、厳密に型指定された null を指定しています。  

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

**ion.ignore\$1malformed**  
オプションです。  
デフォルト: `false`  
値: `true`、`false`  
`true` の場合、SerDe で読み取れない誤った形式があれば、該当するエントリまたはファイル全体が無視されます。詳細については、GitHub にあるドキュメントの「[Ignore malformed](https://github.com/amzn/ion-hive-serde/blob/master/docs/serde-properties.md#ignore-malformed)」(誤った形式を無視する) を参照してください。

**ion.*<column>*.serialize\$1as**  
オプションです。  
デフォルト: 列のデフォルトの型。  
値: Amazon Ion の型を含む文字列  
値をシリアル化する Amazon Ion データ型を決定します。Amazon Ion 型と Hive 型が必ずしも直接マッピングされるわけではないため、Hive 型の中にはシリアル化できる有効なデータ型を複数含むものもあります。データをデフォルト以外のデータ型としてシリアル化するには、このプロパティを使用します。マッピングの詳細については、GitHub にある Amazon Ion の「[型マッピング](https://github.com/amzn/ion-hive-serde/blob/master/docs/type-mapping.md)」ページを参照してください。  
バイナリ Hive 列は、デフォルトでは Amazon Ion BLOB としてシリアル化されますが、[Amazon Ion CLOB](https://amzn.github.io/ion-docs/docs/stringclob.html#ion-clob) (キャラクタラージオブジェクト) としてシリアル化することもできます。次の例では、`example_hive_binary_column` 列を CLOB としてシリアル化しています。  

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