Direct I/O Hive

この文書では、Direct I/Oを使って Apache Hive (以下「Hive」)が対応するカラムナフォーマットのファイルを読み書きする方法について説明します。

Experimental

Asakusa Framework バージョン 0.10.3 では、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のプロジェクト情報を再構成します。

Hiveのバージョンについて

Hive連携モジュールはHive実行ライブラリを使用します。 Asakusa Framework バージョン 0.10.3 の標準の設定では、以下のバージョンのHive実行ライブラリが含まれます。

  • org.apache.hive:hive-exec:1.2.2

実行環境のHiveとHive連携モジュールが利用するHive実行ライブラリのバージョンが異なる場合、データの互換性に対する注意が必要です。 また、実行環境のHadoopのバージョンによっては、利用可能なHive実行ライブラリのバージョンに制限が発生することがあります [1]

Hive連携モジュールのHive実行ライブラリのバージョンを変更するには、以下のように build.gradle を設定します。 以下はHive実行ライブラリに org.apache.hive:hive-exec:2.3.4 を使用する例です。

asakusafw {
    sdk.hive = ['org.apache.hive:hive-exec:2.3.4']
}

asakusafwOrganizer {
    hive.enabled true
    hive.libraries = ['org.apache.hive:hive-exec:2.3.4']
}

Note

Asakusa on Sparkが使用する実行環境のSparkにHive実行ライブラリが含まれる場合、Spark側のHive実行ライブラリが優先して使用されることがあります。 この場合、Asakusa Frameworkの実行環境に含まれるHive実行ライブラリは無視されます。

[1]一例として、実行環境がHadoop3系の場合、Hive1系の実行ライブラリは使用できないことを確認しています。

カラムナフォーマットファイルの入出力

Direct I/OのHive連携モジュールを利用することで、Direct I/OからHiveが対応するカラムナフォーマットファイルの入出力を行うことができます。

Asakusa Frameworkのバージョン 0.10.3 では、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 属性には、次のような要素を指定できます。

ORC File形式の設定
要素 既定値 内容
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_mappingon_missing_sourceon_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 と指定します。

以下は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 属性には、次のような要素を指定できます。

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_mappingon_missing_sourceon_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_sourceon_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つのマッピングを考慮する必要があります。

  1. モデルプロパティとHiveデータ型とのマッピング
  2. Hiveデータ型とカラムナフォーマットのデータ型とのマッピング

たとえばあるデータ型について、a.のマッピングは対応しているが、b.のマッピングは対応していない、という場合にはそのままではそのプロパティを扱うことはできません。

そのような場合に、異なるデータ型としてそのプロパティを扱うための マッピング型変換機能 を提供しています。 これは、a.のモデルプロパティとHiveデータ型とのマッピングにおいて、標準のデータ型のマッピングとは異なるデータ型へのマッピングを行う機能です。 これによりそのプロパティを取り扱うことを可能にしています。

モデルプロパティとHiveデータ型とのマッピング

モデルプロパティとHiveデータ型のマッピング定義は以下の通りです。

モデルプロパティとHiveデータ型のマッピング
DMDL [2] Hive (標準マッピング) [3] Hive (マッピング型変換) [4] 備考
INT INT -  
LONG BIGINT -  
FLOAT FLOAT -  
DOUBLE DOUBLE -  
TEXT STRING
  • VARCHAR
  • CHAR
 
DECIMAL DECIMAL
  • DECIMAL(精度とスケールの指定)
  • STRING
 
DATE DATE
  • TIMESTAMP
  • STRING
 
DATETIME TIMESTAMP
  • STRING
Hiveの TIMESTAMP 型が保持するミリ秒以下の情報はマッピング時に切り捨て
BOOLEAN BOOLEAN -  
BYTE TINYINT -  
SHORT SMALLINT -  

Attention

上表で記載が無いHiveデータ型( BINARY 、及び ARRAY などの Complex Types)には対応していません。

Attention

Hiveの TIMESTAMP 型はタイムゾーンを保持しません。 複数の異なるタイムゾーンを持つ環境間で TIMESTAMP 型を持つデータを扱う場合、タイムゾーンの差異によって異なる値が扱われる可能性があることに注意してください。

[2]DMDLで指定するプロパティの型です。詳しくは DMDLユーザーガイド を参照してください
[3]モデルプロパティの型に対して、標準で対応するHiveのデータ型です。 Hiveのデータ型について詳しくはHiveのドキュメント LanguageManual Types などを参照してください。
[4]モデルプロパティの型に対して、 マッピング型変換機能 が対応するHiveのデータ型です。
マッピング型変換機能

マッピング型変換機能は、Direct I/Oがカラムナフォーマットのファイルを入出力する際に、モデルプロパティの型に対して モデルプロパティとHiveデータ型とのマッピング 表で定義されている標準マッピング以外のHiveデータ型として取り扱う機能です。

モデルプロパティに対して、 モデルプロパティとHiveデータ型とのマッピング 表の「Hive (マッピング型変換)」に記載されているHiveデータ型に対するマッピングを行うことが可能です。

マッピング型変換を行うには、それぞれのモデルプロパティにマッピング型変換用の属性を指定します。 属性によっては、さらにその属性が持つ各要素でデータ型の詳細情報を指定します。

マッピング型変換で利用可能な属性は以下の通りです。

マッピング型変換
属性 要素 [5] 内容
@directio.hive.string -
  • DECIMAL
  • DATE
  • DATETIME
モデルプロパティをHiveの STRING 型にマッピング
@directio.hive.decimal
  • precision :精度(1 - 38)
  • scale :スケール(0 - 38)
  • DECIMAL
モデルプロパティを精度とスケールを持つHiveの DECIMAL 型にマッピング
@directio.hive.timestamp -
  • DATE
モデルプロパティをHiveの TIMESTAMP 型にマッピング ( DATE からのマッピングでは時刻は常に 00:00:00 )
@directio.hive.char
  • length :最大文字列長(1 - 255)
  • TEXT
モデルプロパティをHiveの CHAR 型にマッピング
@directio.hive.varchar
  • length :最大文字列長(1 - 65535)
  • TEXT
モデルプロパティをHiveの VARCHAR 型にマッピング
[5]この属性を指定することが可能な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ファイルの生成 を参照してください。