Direct I/O Hive¶
この文書では、Direct I/Oを使って Apache Hive （以下「Hive」）が対応するカラムナフォーマットのファイルを読み書きする方法について説明します。
Experimental
Asakusa Framework バージョン 0.10.2 では、Direct I/O のHive連携機能は試験的機能として提供しています。
See also
Hiveの操作も含めたアプリケーション開発の全体の流れについては、 Asakusa FrameworkとHiveを連携して利用する も参照にしてください。
Hive連携モジュールの利用方法¶
Hive 連携モジュールを使用する場合は build.gradle に対して以下の定義を追加します。
- Hive連携モジュール用のアプリケーションSDKライブラリを依存関係に追加する
asakusafwブロックにsdk.hive trueを追加
- デプロイ構成に対してDirect I/O Hive用の構成を有効化する
asakusafwOrganizerブロックにhive.enabled trueを追加
以下、 build.gradle の設定例です。
asakusafw {
sdk.hive true
}
asakusafwOrganizer {
hive.enabled true
}
上記の設定後、 installAsakusafw タスクを実行して開発環境のAsakusa Frameworkを再インストールします。
Eclipseを利用している場合は、 eclipse タスクを実行してEclipseのプロジェクト情報を再構成します。
カラムナフォーマットファイルの入出力¶
Direct I/OのHive連携モジュールを利用することで、Direct I/OからHiveが対応するカラムナフォーマットファイルの入出力を行うことができます。
Asakusa Frameworkのバージョン 0.10.2 では、Hiveが対応するカラムナフォーマットのうち、以下のフォーマットに対するファイルの入出力に対応しています。
データモデルクラスの生成¶
Direct I/O CSV と同様に、データモデルクラス、及びファイル形式をマッピングする DataFormat の実装クラスは、DMDLコンパイラの拡張を利用して自動的に生成できます。
これらの生成機能は、DMDLコンパイラのプラグイン asakusa-hive-dmdl によって提供されます。
このコンパイラプラグインは上述の Hive連携モジュールの利用方法 の設定を行うことで利用することができます。
ORC File形式のDataFormatの作成¶
ORC File形式に対応した DataFormat の実装クラスを自動的に生成するには、対象のデータモデルに対応するDMDLスクリプトに @directio.hive.orc を指定します。
@directio.hive.orc
document = {
"the name of this document"
name : TEXT;
"the content of this document"
content : TEXT;
};
上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.hive.orc.<データモデル名>OrcFileFormat というクラスが自動生成されます。
このクラスは DataFormat を実装し、データモデルに対応するORC Fileを取り扱えます。
また、 ファイルを入力に利用するDSL と ファイルを出力に利用するDSL の骨格も自動生成します。
前者は <出力先パッケージ>.hive.orc.Abstract<データモデル名>OrcFileInputDescription 、後者は <出力先パッケージ>.hive.orc.Abstract<データモデル名>OrcFileOutputDescription というクラス名で生成します。
必要に応じて継承して利用してください。
ORC File形式の設定¶
@directio.hive.orc 属性には、次のような要素を指定できます。
| 要素 | 型 | 既定値 | 内容 |
|---|---|---|---|
table_name |
文字列 | モデル名 |
Hiveメタストア上のテーブル名 |
field_mapping |
文字列 | position |
ファイル入力時の カラム名のマッピング 方式。 name : 名前マッピング, position : 位置マッピング |
on_missing_source |
文字列 | logging |
ファイル入力時に入力ファイル内にカラムがない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー |
on_missing_target |
文字列 | logging |
ファイル入力時にデータモデル内にカラムがない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー |
on_incompatible_type |
文字列 | fail |
ファイル入力時に入力ファイルとデータモデルでカラム型に互換性がない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー |
format_version |
文字列 | ライブラリが持つ規定値 |
ファイル出力時に使用するORC Fileのバージョン (後方互換性向け)。 0.11 | 0.12 |
compression |
文字列 | snappy |
ファイル出力時に使用する圧縮コーデック。 none | zlib | snappy | lzo |
stripe_size |
数値 | 67108864 |
ファイル出力時に使用するORC Fileのストライプサイズ(バイト数) |
table_name には、Hive上のテーブル名を指定します。指定しない場合はデータモデル上のモデル名をテーブル名として使用します。
field_mapping 、 on_missing_source 、 on_missing_target は、Direct I/Oがファイルを読み込む際に使用するデータモデルとのマッピング方式と、マッピングできないカラムが存在した場合の動作をそれぞれ指定します。
詳しくは後述の カラム名のマッピング を参照してください。
on_incompatible_type には、Direct I/Oがファイルを読み込む際にORC File上のカラムデータ型とデータモデルのプロパティの型が対応していない場合の動作を指定します。
データモデルとHive、及び各ファイルフォーマットとのデータ型の対応については、 データ型のマッピング を参照してください。
format_version はDirect I/Oで作成するORC Fileのバージョンを、ファイルを読み込むHiveのバージョンに合わせて指定します。
例えば、作成したファイルを Hive 0.11 で読む場合は、フォーマットバージョンに 0.11 と指定します。
Hiveのバージョンについては 後述の Hiveのバージョンに関して も合わせて参照してください。
以下はDMDLスクリプトの記述例です。
@directio.hive.orc(
table_name = "tb_lineitem",
field_mapping = "name",
on_missing_source = "fail",
on_missing_target = "fail",
on_incompatible_type = "fail",
format_version = "0.11",
compression = "none",
stripe_size = 67108864,
)
document = {
...
};
Parquet形式のDataFormatの作成¶
Parquet形式に対応した DataFormat の実装クラスを自動的に生成するには、対象のデータモデルに対応するDMDLスクリプトに @directio.hive.parquet を指定します。
@directio.hive.parquet
document = {
"the name of this document"
name : TEXT;
"the content of this document"
content : TEXT;
};
上記のように記述してデータモデルクラスを生成すると、 <出力先パッケージ>.hive.parquet.<データモデル名>ParquetFileFormat というクラスが自動生成されます。
このクラスは DataFormat を実装し、データモデルに対応するParquetを取り扱えます。
また、 ファイルを入力に利用するDSL と ファイルを出力に利用するDSL の骨格も自動生成します。
前者は <出力先パッケージ>.hive.parquet.Abstract<データモデル名>ParquetFileInputDescription 、後者は <出力先パッケージ>.hive.parquet.Abstract<データモデル名>ParquetFileOutputDescription というクラス名で生成します。
必要に応じて継承して利用してください。
Parquet形式の設定¶
@directio.hive.parquet 属性には、次のような要素を指定できます。
| 要素 | 型 | 既定値 | 内容 |
|---|---|---|---|
table_name |
文字列 | モデル名 |
Hiveメタストア上のテーブル名 |
field_mapping |
文字列 | position |
ファイル入力時の カラム名のマッピング 方式。 name : 名前マッピング, position : 位置マッピング |
on_missing_source |
文字列 | logging |
ファイル入力時に入力ファイル内にカラムがない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー |
on_missing_target |
文字列 | logging |
ファイル入力時にデータモデル内にカラムがない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー |
on_incompatible_type |
文字列 | fail |
ファイル入力時に入力ファイルとデータモデルでカラム型に互換性がない場合の動作。 ignore : 無視, logging : 警告ログの出力, fail : エラー |
format_version |
文字列 | v1 |
ファイル出力時に使用するParquetのバージョン。 v1 | v2 |
compression |
文字列 | snappy |
ファイル出力時に使用する圧縮コーデック。 uncompressed | gzip | snappy | lzo |
block_size |
数値 | 134217728 |
ファイル出力時に使用するParquetのブロックサイズ(バイト数) |
data_page_size |
数値 | 1048576 |
ファイル出力時に使用するParquetのページサイズ(バイト数) |
dictionary_page_size |
数値 | 1048576 |
ファイル出力時に使用するParquetのディクショナリページサイズ(バイト数) |
enable_dictionary |
論理値 | TRUE |
ファイル出力時にParquetのディクショナリエンコーディングを使用するか。 TRUE :使用する, FALSE :使用しない |
enable_validation |
論理値 | FALSE |
ファイル出力時にParquetのデータスキーマの検査を行うか。 TRUE :検査する, FALSE :検査しない |
table_name には、Hive上のテーブル名を指定します。
指定しない場合はデータモデル上のモデル名をテーブル名として使用します。
field_mapping 、 on_missing_source 、 on_missing_target は、Direct I/Oがファイルを読み込む際に使用するデータモデルとのマッピング方式と、マッピングできないカラムが存在した場合の動作をそれぞれ指定します。
詳しくは後述の カラム名のマッピング を参照してください。
on_incompatible_type には、Direct I/Oがファイルを読み込む際にParquet上のカラムデータ型とデータモデルのプロパティの型が対応していない場合の動作を指定します。
データモデルとHive、及び各ファイルフォーマットとのデータ型の対応については、 データ型のマッピング を参照してください。
以下はDMDLスクリプトの記述例です。
@directio.hive.parquet(
table_name = "tb_lineitem",
field_mapping = "name",
on_missing_source = "fail",
on_missing_target = "fail",
on_incompatible_type = "fail",
format_version = "v2",
compression = "uncompressed",
block_size = 134217728,
data_page_size = 1048576,
dictionary_page_size = 1048576,
enable_dictionary = TRUE,
enable_validation = FALSE
)
document = {
...
};
モデルプロパティとカラムのマッピング¶
データモデルのプロパティと各カラムナフォーマットのカラムとの対応付けについては、データモデルの要素やモデルプロパティの属性を指定することで様々な対応方法を設定することができます。
カラム名のマッピング¶
データモデルのプロパティとカラムナフォーマットのカラムとのマッピングには 位置マッピング と 名前マッピング の2種類のマッピング方法があります。
位置マッピング¶
位置マッピングはデータモデル内のプロパティ定義の順番でカラムナフォーマットのカラムとの対応を行います。 位置マッピングは Direct I/O CSV のマッピング方法と同様の方法です。
位置マッピングを行うには、データモデルの要素 field_mapping の値に position を指定します。
名前マッピング¶
名前マッピングはデータモデルのプロパティ名とカラムナフォーマットが保持するカラム名で対応を行います。
名前マッピングを行うには、データモデルの要素 field_mapping の値に name を 指定します。
データモデルのプロパティ名と異なる名前でカラムナフォーマットと名前マッピングを行いたい場合は、それぞれのモデルプロパティに @directio.hive.field 属性を指定し、さらに name 要素でフィールド名を指定します。
以下は名前マッピングの定義を付加したDMDLスクリプトの記述例です。
@directio.hive.orc
document = {
"the name of this document"
@directio.hive.field(name = "doc_name")
name : TEXT;
"the content of this document"
@directio.hive.field(name = "doc_content")
content : TEXT;
};
マッピング失敗時の動作¶
ファイル入力時にデータモデルのモデルプロパティとカラムナフォーマットファイルのカラム間の対応付けができなかった場合の動作は、データモデルの要素 on_missing_source と on_missing_target で指定します。
on_missing_source はデータモデルのプロパティ名に対して、入力ファイル内にカラムがない場合の動作を指定します。
on_missing_target は反対に、入力ファイル内のカラムに対して、データモデルのプロパティがない場合の動作を指定します。
各要素の値にはそれぞれ以下の値を設定することができます。
ignore: マッピングの失敗を無視して処理を続行logging: マッピングが失敗したことを示す警告ログを出力して処理を続行fail: エラーとしてバッチ処理を異常終了
Attention
ORC FileをHiveで生成する際に、利用するHiveのバージョンによってはファイルにカラム名の情報が出力されないようです。 この場合、名前マッピングは利用できないため、位置マッピングの機能を利用する必要があります。
Hint
ORC Fileにカラム情報が出力されているかどうかを確認する方法として、ORC File Dump Utility を利用することができます。 このツールはHive CLIが利用できる環境で以下のコマンドを実行します。
hive --orcfiledump <hdfs-location-of-orc-file>
データ型のマッピング¶
モデルプロパティのデータ型とカラムナフォーマットのデータ型との対応については、以下の2つのマッピングを考慮する必要があります。
- モデルプロパティとHiveデータ型とのマッピング
- Hiveデータ型とカラムナフォーマットのデータ型とのマッピング
たとえばあるデータ型について、a.のマッピングは対応しているが、b.のマッピングは対応していない、という場合にはそのままではそのプロパティを扱うことはできません。
そのような場合に、異なるデータ型としてそのプロパティを扱うための マッピング型変換機能 を提供しています。 これは、a.のモデルプロパティとHiveデータ型とのマッピングにおいて、標準のデータ型のマッピングとは異なるデータ型へのマッピングを行う機能です。 これによりそのプロパティを取り扱うことを可能にしています。
モデルプロパティとHiveデータ型とのマッピング¶
モデルプロパティとHiveデータ型のマッピング定義は以下の通りです。
| DMDL [1] | Hive (標準マッピング) [2] | Hive (マッピング型変換) [3] | 備考 |
|---|---|---|---|
INT |
INT |
- |
|
LONG |
BIGINT |
- |
|
FLOAT |
FLOAT |
- |
|
DOUBLE |
DOUBLE |
- |
|
TEXT |
STRING |
|
|
DECIMAL |
DECIMAL |
|
|
DATE |
DATE |
|
|
DATETIME |
TIMESTAMP |
|
Hiveの TIMESTAMP 型が保持するミリ秒以下の情報はマッピング時に切り捨て |
BOOLEAN |
BOOLEAN |
- |
|
BYTE |
TINYINT |
- |
|
SHORT |
SMALLINT |
- |
Attention
上表で記載が無いHiveデータ型( BINARY 、及び ARRAY などの Complex Types）には対応していません。
Attention
Hiveの TIMESTAMP 型はタイムゾーンを保持しません。
複数の異なるタイムゾーンを持つ環境間で TIMESTAMP 型を持つデータを扱う場合、タイムゾーンの差異によって異なる値が扱われる可能性があることに注意してください。
| [1] | DMDLで指定するプロパティの型です。詳しくは DMDLユーザーガイド を参照してください |
| [2] | モデルプロパティの型に対して、標準で対応するHiveのデータ型です。 Hiveのデータ型について詳しくはHiveのドキュメント LanguageManual Types などを参照してください。 |
| [3] | モデルプロパティの型に対して、 マッピング型変換機能 が対応するHiveのデータ型です。 |
Hiveのバージョンに関して¶
Asakusa Framework バージョン 0.10.2 では、Direct I/O の Hive連携モジュールにはHiveのバージョン 1.2.2 を使用しています。
実行環境のHiveとAsakusa Frameworkが利用するHiveのバージョンが異なる場合、データの互換性に対する注意が必要です。
マッピング型変換機能¶
マッピング型変換機能は、Direct I/Oがカラムナフォーマットのファイルを入出力する際に、モデルプロパティの型に対して モデルプロパティとHiveデータ型とのマッピング 表で定義されている標準マッピング以外のHiveデータ型として取り扱う機能です。
モデルプロパティに対して、 モデルプロパティとHiveデータ型とのマッピング 表の「Hive (マッピング型変換)」に記載されているHiveデータ型に対するマッピングを行うことが可能です。
マッピング型変換を行うには、それぞれのモデルプロパティにマッピング型変換用の属性を指定します。 属性によっては、さらにその属性が持つ各要素でデータ型の詳細情報を指定します。
マッピング型変換で利用可能な属性は以下の通りです。
| 属性 | 要素 | 型 [4] | 内容 |
|---|---|---|---|
@directio.hive.string |
- |
|
モデルプロパティをHiveの STRING 型にマッピング |
@directio.hive.decimal |
|
|
モデルプロパティを精度とスケールを持つHiveの DECIMAL 型にマッピング |
@directio.hive.timestamp |
- |
|
モデルプロパティをHiveの TIMESTAMP 型にマッピング ( DATE からのマッピングでは時刻は常に 00:00:00 ) |
@directio.hive.char |
|
|
モデルプロパティをHiveの CHAR 型にマッピング |
@directio.hive.varchar |
|
|
モデルプロパティをHiveの VARCHAR 型にマッピング |
| [4] | この属性を指定することが可能なDMDLのプロパティの型です。 |
以下はマッピング変換機能の定義を付加したDMDLスクリプトの記述例です。
item = {
@directio.hive.char(length = 2)
item_no : TEXT;
@directio.hive.decimal(precision = 20, scale = 4)
unit_selling_price : DECIMAL;
@directio.hive.string
extended_price : DECIMAL;
@directio.hive.timestamp
order_date : DATE;
@directio.hive.varchar(length = 1024)
memo : TEXT;
};
Hiveデータ型とカラムナフォーマットのデータ型とのマッピング¶
Hiveデータ型とカラムナフォーマットのデータ型とのマッピングにおける制約ついては、Hiveの以下のカラムナフォーマットのドキュメントを参照してください。
カラムナフォーマットファイルから除外するプロパティ¶
特定のプロパティをカラムナフォーマットファイルのカラムとして取り扱いたくない場合、プロパティに @directio.hive.ignore を指定します。
関連機能¶
Hive DDLの生成¶
アプリケーションの開発にGradleプロジェクトを利用している場合、Hive連携モジュールを利用するDMDLスクリプトからHiveのDDLを生成する generateHiveDDL タスクを利用することができます。
./gradlew generateHiveDDL
generateHiveDDL タスクを実行すると、プロジェクトの build/hive-ddl ディレクトリ配下にHiveのDDL文を含むSQLファイルが生成されます。
詳しくは、 Asakusa Gradle Plugin ユーザーガイド - Hive用DDLファイルの生成 を参照してください。