Amazon Ion SerDe プロパティリファレンス

このトピックでは、Athena の CREATE TABLE ステートメントに使用できる SerDe プロパティについて説明します。Amazon Ion SerDe プロパティの使用方法の詳細と例については、GitHub にある Amazon Ion Hive SerDe ドキュメントの「SerDe properties」(SerDe プロパティ) を参照してください。

Amazon Ion SerDe プロパティを指定する方法

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 プロパティ

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

ion.encoding

オプションです。

デフォルト: BINARY

値: BINARY、TEXT

このプロパティは、追加された新しい値が Amazon Ion バイナリと Amazon Ion テキストのどちらの形式としてシリアル化されるかを宣言します。

次の SerDe プロパティの例では、Amazon Ion テキスト形式を指定しています。

'ion.encoding' = 'TEXT'

ion.fail_on_overflow

オプションです。

デフォルト: 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_extractor.case_sensitive

オプションです。

デフォルト: 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_extractor

オプションです。

デフォルト: NA

値: 検索パスを含む文字列

指定された列の指定された検索パスが含まれるパスエクストラクタを作成します。パスエクストラクタは、Amazon Ion フィールドを Hive 列にマッピングします。パスエクストラクタを指定しないと、Athena は列名に基づいて実行時に動的にパスエクストラクタを作成します。

次の例のパスエクストラクタは、example_ion_field を example_hive_column にマッピングしています。

'ion.example_hive_column.path_extractor' = '(example_ion_field)'

パスエクストラクタと検索パスの詳細については、「パスエクストラクターを使用する」を参照してください。

ion.timestamp.serialization_offset

オプションです。

デフォルト: 'Z'

値: OFFSET。OFFSET は <signal>hh:mm として表される。値の例: 01:00、+01:00、-09:30、Z (UTC、00:00 と同じ)

Apache Hive のタイムスタンプは、タイムゾーンが組み込まれておらず、UNIX エポックからのオフセットとして保存されます。一方、Amazon Ion のタイムスタンプにはオフセットがあります。このプロパティを使用して、Amazon Ion にシリアル化するときのオフセットを指定します。

次の例では、1 時間のオフセットを追加しています。

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

ion.serialize_null

オプションです。

デフォルト: OMIT

値: OMIT、UNTYPED、TYPED

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

次の例では、厳密に型指定された null を指定しています。

'ion.serialize_null'='TYPED'

ion.ignore_malformed

オプションです。

デフォルト: false

値: true、false

true の場合、SerDe で読み取れない誤った形式があれば、該当するエントリまたはファイル全体が無視されます。詳細については、GitHub にあるドキュメントの「Ignore malformed」(誤った形式を無視する) を参照してください。

ion.<column>.serialize_as

オプションです。

デフォルト: 列のデフォルトの型。

値: Amazon Ion の型を含む文字列

値をシリアル化する Amazon Ion データ型を決定します。Amazon Ion 型と Hive 型が必ずしも直接マッピングされるわけではないため、Hive 型の中にはシリアル化できる有効なデータ型を複数含むものもあります。データをデフォルト以外のデータ型としてシリアル化するには、このプロパティを使用します。マッピングの詳細については、GitHub にある Amazon Ion の「型マッピング」ページを参照してください。

バイナリ Hive 列は、デフォルトでは Amazon Ion BLOB としてシリアル化されますが、Amazon Ion CLOB (キャラクタラージオブジェクト) としてシリアル化することもできます。次の例では、example_hive_binary_column 列を CLOB としてシリアル化しています。

'ion.example_hive_binary_column.serialize_as' = 'clob'