ingestユーティリティ - ibm...1.ingestユーティリティの概要...

© 2017 IBM Corporation

INGESTユーティリティ

© 2017 IBM Corporation2

注意事項

本資料掲載事項は、ある特定の環境・使用状況においての正確性がIBMによって確認されていますが、すべての環境において同様の結果が得られる保証はありません。これらの技術を自身の環境に適用する際には、自己の責任において十分な検証と確認を実施いただくことをお奨めいたします。


目次

1. INGESTユーティリティの概要

2. 各データ移動ユーティリティの機能比較

3. マルチパーティション環境（DPF）におけるINGESTの動き

4. 各データ移動ユーティリティの使い分け

5. INGEST利用時の流れ

6. 実行中のINGEST処理の確認－ INGEST LISTコマンド

7. 実行中のINGEST処理の確認－ INGEST GET STATSコマンド

8. 各種INGEST実行例

9. 区切りなしACSIIデータの位置指定

10. ダンプファイルと例外表へのエラーデータ出力

11. その他のINGEST実行例

12. INGEST中断時の表の状態と処理再実行

13. INGEST実行時の考慮点

14. 参考資料


ブランクページ


INGESTユーティリティの概要

§ マルチスレッドで動作し、複数のDB接続から並列にDMLを実行する高速ユーティリティ

- DML（Data Manipulation Language）：INSERT、UPDATE、MERGE、DELETE

- IMPORTよりも高速なデータ書き込みが可能

§ INGESTの実行中も、ターゲット表は他のアプリから読み書き可能

§ マルチパーティション環境（DPF）の場合、入力データを各パーティション向けに仕分け、該当パーティションへ直接接続して書き込むことができる

§ エラー箇所から再開することのできるリカバリー機能を提供

§ 入力データを加工してから書き込むことも可能

INGEST

DB2


Note:

§ INGESTユーティリティとは、DB2 10.1より利用可能になったデータ移動ユーティリティです。

§ IMPORTやLOADと同様、DEL形式（区切り文字のあるASCIIデータ）やASC形式（区切り文字のないASCIIデータ）のファイルから表にデータを投入することができます。

§ IMPORTと同様、内部でINSERTを実行することによるデータ書き込みが可能ですが、さらにUPDATEやMERGE、DELETEも実行することができます。

§ IMPORTが1プロセスからDBに1接続を確立し、そこからすべてのINSERT（またはUPDATE）を順番に実行するのに対し、INGESTは、マルチスレッドで動作し、複数の接続から並列にINSERT、DELETE、UPDATE、MERGEを実行することができます。

§ INGEST実行中は、対象表にIXロック、挿入/変更/削除された未コミット行にXロックが取得されます。他のアプリケーションはその他の行に対してロック待機することなく自由に読み書きが可能です。

§ マルチパーティション環境（DPF）の場合、効率の良い並列処理と、DBパーティション間のデータ転送の負荷を削減するためINGESTユーティリティから各パーティションにそれぞれ直接接続を確立します。そして、入力データのハッシュ処理をINGESTユーティリティの側で実施、宛先別にデータを分類しながら、各パーティションに直接データを書き込みます。

§ INGESTユーティリティは、途中で処理が中断された場合でも、その地点から再実行する機能を提供します（RESTARTオプションの指定）。

§ INGESTユーティリティは、入力データをそのまま表にINSERTするだけではなく、DMLで表現できる範囲のことであれば、簡単なデータ加工なども可能です。


各データ移動ユーティリティの機能比較

INGEST LOAD IMPORT

入力データタイプと数１つまたは複数のファイル注1、パイプ

ひとつまたは複数のファイル注1、パイプ、デバイス、および１つのカーソル

１つのファイル

入力データのフォーマット ASC、DEL ASC、DEL、IXF、CURSOR ASC、DEL、IXF

サポートされない

データ・タイプBLOB、CLOB、DBCLOB、XML、構造化タイプ

構造化タイプなし

バイナリ形式の整数型、浮動小数点数型データ注2

サポートサポート未サポート

PACKED DECIMAL、ZONED DECIMAL形式の10進数データ注2

サポートサポート未サポート

実行可能な表操作 INSERT、UPDATE、DELETE、MERGE、REPLACE

INSERT、REPLACE INSERT,REPLACE、INSERT_UPDATE注3

注1： INGEST、LOADでは、IBM SoftLayer Object StorageまたはAmazon Simple Storage Service (S3) 上のファイルを指定可能。注2： BINARY、PACKED/ZONE DECIMALを利用する場合には、入力データはASC型でなくてはならない。注3： INSERT_UPDATEオプションはターゲット表にプライマリーキー、またはユニーク索引が定義されている場合に利用する。

IMPORTからは、まずINSERTが実行され、キー重複のエラーが発生した行のデータについてUPDATEで反映される。


Note:

§ INGESTを他のデータ移動ユーティリティと比較します。

§ 入力データタイプと数

- INGESTは複数のファイルまたはパイプを入力とすることができます。

- LOADはさらにデバイスやカーソルを入力とすることができます。IMPORTはひとつのファイルのみを入力とすることができます。

§ 入力データのフォーマット

- INGESTはASC形式（位置固定のASCII）とDEL形式（列区切りつきのASCII）のみサポートしています。

§ サポートされないデータ・タイプ

- INGESTは、Large Objects（LOB）、XML、およびそれらをベースとした構造化タイプは利用できません。

§ バイナリー形式の整数型、浮動小数点型データ

- INGESTは、LOADと同様、バイナリー形式で提供された整数型（SMALLINT、INT、BIGINT）や浮動小数点型（REAL、DOUBLE、DECFLOAT）データをサポートしています。

§ PACKED DECIMAL、ZONED DECIMAL形式の10進数データ

- INGESTは、LOADと同様、PACKED DECIMALやZONE DECIMAL形式で提供された10進数（DECIMAL）データをサポートしています。

§ 実行可能な表操作

- INGESTは単純なINSERTやREPLACEだけではなく、UPDATE、DELETE、MERGEなど多様な処理が可能です。


各データ移動ユーティリティの機能比較（続き）

INGEST LOAD IMPORT

実行中の表データアクセス読み書き可能読み取りのみ注1 読み書き可能注2

処理性能（対IMPORT比) 速いとても速い同等

投入データのログ記録ありなしあり

前提バージョンと

エディションV10.1、V10.5のアドバンス版注3、V11.1以降の全エディション

全バージョンの

全エディション

全バージョンの

全エディション

途中キャンセル時の状態途中で実行された最後のコミット地点まで反映済み

表への読み書き不能

（SQL0668N）途中で実行された最後のコミット地点まで反映済み

途中で終了した場合の

再開方法

RESTARTオプションにて

再開

RESTARTオプションにて

再開、またはTERMINATEオプションにて開始前の状態に戻る

SKIPCOUNTオプションで

反映済みの行を読み飛ばして再実行

注1： ALLOW READ ACCESS指定で実行されたINSERTモードのLOADの場合には、LOAD開始時点で存在していた行を参照可能。

ただし当機能はV10.1以降非推奨。

注2： ALLOW WRITE ACCESS指定の場合のみ（デフォルトはALLOW NO ACCESS）

注3： V10.1、V10.5では、INGESTの利用には、Advanced Enterprise Server Edition、またはAdvanced Workgroup Server Editionが必要


Note:§ 各データ移動ユーティリティの比較の続きです。

§ 実行中のデータアクセス

- INGEST中のターゲットの表は自由に読み書きが可能です（コミット前のINSERT/DELETE/UPDATEデータには排他ロックが取られているため、分離レベルによってはロック競合の可能性があります。）。

§ 処理性能

- 複数セッションからの並列処理を行うINGESTは、LOADには及ばないものの、IMPORTよりも高速なデータ処理が可能です。

§ 投入データのログ記録

- INGESTは、内部ではSQLによるINSERT、DELETE、UPDATE、MERGEの実行によってデータの書き込みを行いますので、変更データはログに記録されます。

§ 前提バージョンとエディション

- INGESTは、V10.1、V10.5までは、Advanced Workgroup Server EditionまたはAdvanced Enterprise Server Editionのみで利用可能でした。 V11.1以降はすべてのエディションでINGESTをご利用頂けます。

§ 途中キャンセル時の状態

- INGESTを途中でキャンセルした場合、その時点までのコミット済みデータだけが反映された状態となっています。LOADのように表全体がアクセス不能になるようなことはありません。

§ 途中で終了した場合の再開方法

- INGESTは読み取り件数やコミットタイミングなどを再開ログ表と呼ばれるコントロール表に記録しています。INGESTが途中で中断され、入力ファイルの一部データだけがINSERT済み（COMMIT済み）の場合、RESTARTオプションを指定してINGESTを実行すれば、この再開ログ表に記録された情報を用いて、その続きから継続することができます。


マルチパーティション環境（DPF）におけるINGESTの動き

§ 各DBパーティションに複数の接続を行い、並列にデータを投入する

- INGEST実行中、ターゲット表のすべてのパーティションで並列にデータ処理が行われる

§ 入力データはINGESTユーティリティのFormatterスレッドでハッシュ分割され、格納先の各パーティションに直接送られて、Flusherスレッドにて書き込まれる。

- 同じ接続からのデータはすべて同じDBパーティションに格納される

- 一回ごとのSQLがDBパーティション間の通信を伴わないため、高いスループットが実現できる

- 大量データの処理をIMPORTよりも効率良く行うことができる

入力データ

入力データ

INGEST

Transporter

Transporter

Flusher[array insert]Formater

Formater

Formater

Formater

Flusher[array insert]

Flusher[array insert]

宛先がマルチパーティション環境の場合

SQL

DB2 DPF

SQL

SQL

上記スレッドはすべて単一のクライアントプロセス内で稼動


Note:§ マルチパーティション環境（DPF）の場合、効率の良い並列処理と、DBパーティション間のデータ転送負荷解消のため、INGESTユー

ティリティは、ターゲット表がどのDBパーティションを利用しているかを確認し、宛先となる各パーティションにそれぞれ直接複数の接続を行います。

§ INGESTユーティリティは、さらにターゲット表の分散キーに該当するデータのハッシュ処理を実施して、適切な接続に各行のデータを分配します。そのようにして各パーティション向けに仕分けられたデータは、適切な接続に直接書き込まれます。複数の接続を利用した並列処理が行われ、また一回一回のSQL実行が短時間で終了しますので、IMPORTに比べて高いスループットが実現されます。

§ INGESTユーティリティは、下記の3つの種類のスレッドにて動作します。それぞれ複数が並列に稼動します。

- Transporter：入力ファイル（またはパイプ）の読み取りを行います。

- Formatter： Transporterから受け取ったデータをINGESTコマンドの指定にそってフォーマットします。

マルチパーティション環境の場合には、データをハッシュして、適切なFlusherに振り分ける仕事も行います。

- Flusher： Array InsertにてDB2の表にデータを書き込みます。

指定された頻度でのCOMMIT発行など、トランザクションの制御も行います。


参考：マルチパーティション環境（DPF）における動き： IMPORT

§ 1プロセスからの１本のDB接続からデータが投入される

§ 接続先のパーティションで1行ずつハッシュ処理が行われ、格納先に届けられる。

§ 格納先のINSERT（またはUPDATE）成功の通知がIMPORTユーティリティに戻り、次の1行が送信される。

- この1行の処理の間、接続先のパーティション（コーディネーター）とデータ格納先のパーティション以外は待機状態となる。

- コミット時には複数パーティションを跨いだ2フェーズコミットが行われる

- ＩＮＧＥＳＴのような並列処理が行われないため大量データの投入には不向き

入力データ IMPORT

DB2 DPF

INSERT

INSERTHASH

HASH

INSERT

INSERT


Note:

§ マルチパーティション環境におけるIMPORTの例です。

§ INGESTと異なり、IMPORTからは1本のDB接続を経由して全てのデータが投入されます。

§ 接続先のDBパーティション（コーディネーター・パーティション）は、受け取ったデータがどのパーティションに格納されるべきかハッシュ処理によって決定し、宛先のパーティションに転送します。

§ 格納先で無事INSERT（またはUPDATE）が完了すると、成功通知がコーディネーター・パーティションを経由してIMPORTに戻され、IMPORTはその次のデータを送信します。

§ このような処理を1本の接続で順番に繰り返しますので、多くのDBパーティションでデータの受信を待機している時間が長くなります。INGESTのような高いスループットは期待できませんので、大量データの書き込みには適していません。

§ 一方、少量のデータを書き込む場合には、INGESTのように複数スレッドを起動するような準備が必要ありませんので、IMPORTのほうが短時間で完了します。


各データ移動ユーティリティの使い分け

INGEST LOAD IMPORT

大量のデータをできるだけ

高速に表に書き込みたい

複数スレッドにて並列に

DMLを実行DMLを使わずに直接表ページをフォーマットして書き込むため他の方法よりも圧倒的に高速

1件1件DMLで投入するため、性能はLOADやINGESTに劣る

HADR環境の場合すべてのデータ変更がログに記録されるため、HADRにてスタンバイ側に変更反映可能

データ変更はログ無しとなるため、LOAD COPYイメージをNFS等で共有するなどの考慮必要

すべてのデータ変更がログに記録されるため、HADRにて

スタンバイ側に変更反映可能

レプリケーション（Q-ReplicationやCDCなど）のソースになっている

すべてのデータ変更がログに記録されるため、レプリケーション製品による差分更新可能

データ変更はログ無しとなるため、差分更新ができない（フル・リフレッシュ必要）

すべてのデータ変更がログに記録されるため、レプリケーション製品による差分更新可能

データ投入中も表の読み書きをしたい

INGEST実行中の表の読み書き可ＬＯＡＤ実行中は読み取りのみ IMPORT中の表の読み書き可（Allow Writeオプション）

単純なINSERT、REPLACE以外のこともしたい

UPDATE、DELETE、MERGE、

列加工など自在に可能INSERTとREPLACEのみ INSERT_UPDATEオプションの

ほか、IXFファイルからの表作成も可能

DB2 10.5以前の

非Advanced版での利用DB2 10.1、10.5では、AdvancedEnterprise/Workgroup Edition必要

特にバージョンやエディションの制約なし

特にバージョンやエディションの制約なし

･･･お勧め･･･利用可･･･非推奨、または利用不可


Note:§ 3つのデータ移動ユーティリティの選択基準をまとめました。緑セルがお勧め、黄色セルは、お勧めではないものの利用可、ピンク

セルは、利用不可またはお勧めしないものです。

§ まずは大量データをできるだけ高速に表に書き込みたい場合の選択肢を考えてみましょう。最初の候補となるのはLOADユーティリティです。DMLの実行ではなく、直接表ページの形式にフォーマットして表のうしろに追加してゆくLOADユーティリティは、大量データのINSERTにおいて最も優れた性能を発揮します。

§ LOADは大変高速ですが、INSERT行がログに記録されないため、HADRや各種レプリケーション製品（Q-ReplicationやCDC）のように、ログを媒体にしてレプリカDBとの同期をとる仕組みを利用している場合には注意が必要です。

§ HADRでLOADを利用した場合、LOADデータのフォワードリカバリーのためにLOAD時に取得するLOAD COPYイメージ（LOADのCOPY YESオプション）の出力先パスを、HADRスタンバイからもアクセス可能にしておく必要があります。具体的には、NFSやGPFSのような共有ファイルシステムを用意してLOAD COPYイメージを出力先とし、同じパスをHADRのスタンバイからもアクセス可能にしておくことになります。

§ Q-Replicationの環境の場合、LOADを実行すると、ReplicationのApplyプログラム側は差分更新ができなくなり、表全体のフル・リフレッシュを行うことになります。

§ INGESTやIMPORTであれば、書き込みデータはログに掛かれますので、このようなHADRやReplication環境において特別な考慮は必要なくなります。

§ 次にデータ投入中に他のアプリケーションからデータを読み書きしたい場合にはどうなるでしょうか？ LOADのターゲット表は、LOAD中は一切更新ができなくなります。読み書きを行うアプリが常に存在する環境では、LOADではなくてINGESTを検討すべきです。

§ INSERTとREPLACE以外の操作が充実しているのもINGESTの特徴です。入力データとキーもマッチした行をDELETE/UPDATEしたり、キーを基準にMERGE処理（キーマッチの行は更新、マッチしない行はINSERT）を実施することができます。また入力データを加工してからINSERTをするといったことも実現できます。（実例は後続ページにて紹介）

§ 最後に各ユーティリティの使えるバージョンについてです。IMPORTやLOADはどのバージョンのどのエディションでも利用頂けますが、INGESTだけは、V10.1、V10.5では、Advanced Enterprise Server EditionまたはAdvanced Workgroup Server Editionが前提です。V11.1以降はすべてのエディションでINGESTを利用することができます。


INGEST利用時の流れ

§ １．INGEST実行の準備

① 再開ログ表(SYSTOOLS.)の作成

② INGEST実行オプションの設定（例）

§ ２．INGESTの実行

§ ３．実行中のモニター

CALL SYSPROC.SYSINSTALLOBJECTS (ʻINGEST ,̓ ʻC ,̓ NULL, NULL)

INGEST SET commit_count 10000INGEST SET num_flushers_per_partition 4

INGEST FROM FILE file1.csv FORMAT delimited INSERT INTO table01

INGEST LISTINGEST GET STATS FOR JOBID


Note:§ INGESTを利用するときの流れを示しています。

§ INGESTを利用する前準備として、まずはINGESTの再開ログ表をデータベースにひとつ作成します。SYSINSTALLOBJECTSプロシージャーを利用し、引数として‘INGEST’,‘C’（作成）を指定、第3引数と第4引数にはNULLを指定すると、SYSTOOLS表スペースにINGESTの再開ログ表（SYSTOOLS.INGESTRESTART)が作成されます。 SYSTOOLS表スペース以外の場所に作成したい場合には、第3引数に表スペース名を指定します。

§ INGESTは各セッション（Flusher）からの書き込み件数をカウントし、コミットが発行されたポイントに関する情報をこの再開ログ表に記録します。 INGESTの処理が中断された場合、この再開ログ表の情報を使って、途中から再開することができます。 INGESTの処理を途中から開始する必要がない場合には、この表は不要です。（その場合、INGEST実行時にはRESTART OFFを指定して実行します。）

§ 次にINGESTの実行オプションの設定をします。この設定はINGEST実行の都度行います。

§ 例では、COMMIT_COUNT 10000と設定しています。10000行の処理ごとにCOMMITを実行せよ、という意味です。INGESTはDMLを繰り返し実行するCLIアプリケーションですので、定期的にCOMMITを発行しないと、アクティブ・ログ領域やロックメモリー（Lock List）が枯渇する可能性があります。適度な値を設定してください。

§ 例では、さらにNUM_FLUSHERS_PER_PARTITION（各DBパーティションごとに何本の接続を用意して並列処理するか）に４の値を設定しています。自動算出されるデフォルトの値（利用可能なサーバーCPUの半数をINGESTに割りあてるように調整）から設定を変えたい場合には、こちらの例のように明示指定します。

§ INGEST SETコマンドによる設定が完了しましたら、実際のINGESTの実行が可能になります。

§ この例では、現在のディレクトリー上にあるfile1.csvファイルのデータをtable01表に挿入しています。ファイルのフォーマットは、コンマ(,)で区切られたASCIIデータです。（IMPORTやLOADユーティリティで利用されるDEL形式のファイルと同様）

§ INGESTが開始しましたら、実行中のINGESTの状態（処理件数など）は、INGEST LISTコマンド、およびINGEST GET STATSコマンドによって確認することができます。


INGEST利用時の流れ（例）

db2 “call sysproc.sysinstallobjects('INGEST','C','SYSTOOLSPACE',null)”

Return Status = 0

db2 “ingest set commit_count 10000“

DB20000I The INGEST SET command completed successfully.

db2 “ingest from file file1.csv format delimited insert into table01“SQL2979I The ingest utility is starting at "12/15/2016 03:43:33.811736".SQL2914I The ingest utility has started the following ingest job:"DB21101:20161215.034333.811736:00007:00009".

Number of rows read = 10000000Number of rows inserted = 10000000Number of rows rejected = 0

SQL2980I The ingest utility completed successfully at timestamp "12/15/201603:44:46.211049“

再開表の作成（各DBに対して１つ）

10000件ごとのCOMMIT実行を指定

CSVファイルからTABLE01にINSERT

このINGESTのJOB ID


Note:

§ Ingestの実行例です。

§ まず、SYSTOOLSPACEという表スペースにINGEST再開ログ表を作成しています。

§ 次にCOMMIT_COUNT=10000を設定し、10000件処理するごとにCOMMITを発行するよう指示しています。

§ そして、実際のINGESTを実行しています。ここでINGESTのJOB IDとして、「DB21101:20161215.034333.811736:00007:00009」が割り当てられています。このIDはINGESTの実行状態をINGEST LISTコマンドで確認するときに必要になります。


INGESTの構成パラメーター（INGEST SETにて設定）

§ commit_count：

- コミットが発行される間隔（処理件数）

- デフォルト： 0（commit_periodの設定値を利用）

- 1000の倍数以外の値に設定された場合には、最も近い1000の倍数に丸められる

§ commit_period：

- コミットが発行される間隔（経過時間（秒））

- デフォルト：１（1秒ごとにコミットを実行）

- commit_countとの併用可能

§ num_formatters ：

- 起動されるFormatterの数

- デフォルト： MAX（１, クライアントの論理CPU数/2）

§ num_flushers_per_partition

- ターゲットのDBパーティションごとに起動されるFlusherの数

- デフォルト： MAX（１、サーバーの論理CPU数/2/DBパーティション数））

- 自動的に0または1に調整される場合あり（SQL2903W）


Note：

§ INGESTの実行前にINGEST SETコマンドで設定可能な構成パラメーターは以下のとおりです。

§ commit_count：

- 各Flusherからコミットが発行される間隔を、各コミット間の処理件数で指定します。デフォルトは0です。このとき、コミットの発行は、commit_periodの設定値によります。

- 1000の倍数以外の値に設定された場合には、最も近い1000の倍数に丸められます。

§ commit_period：

- 各Flusherからコミットが発行される間隔を、経過時間（秒）で指定します。デフォルトは1秒です。

- commit_countと併用可能です。すなわち、commit_countで設定した処理件数ごと、およびcommit_periodで設定した経過時間ごとの双方でCOMMITを発行することができます。

§ num_formatters ：

- 起動されるFormatterスレッドの数を指定します。デフォルトは、INGESTユーティリティが実行される環境（クライアント）にて利用可能な論理CPU数の1/2です。（計算値が1に満たないときには１）

§ num_flushers_per_partition

- ターゲットのDBパーティションごとに起動されるFlusherスレッドの数を指定します。デフォルトは、ターゲットのDBサーバーにおける論理CPU数/2/そのサーバーに配置されたDBパーティション数です（計産値が1に満たないときには1）。つまり、16論理CPUが利用可能なDBサーバーに4DBパーティションが配置されている場合、16/2/4=2つずつのFlusherが、4つのDBパーティションにそれぞれ並列に書き込みを行うことになります。

- NUM_FLUSHER_PER_PARTITION=0に設定された場合、ターゲットの表が複数のDBパーティションをまたがって定義されていた場合でも、ひとつだけのFlusher（DBへの接続数＝１）が起動されます。NUM_FLUSHERS_PER_PARTITON=1と設定すると、ターゲットの表が配置された各DBパーティションに、ひとつずつの接続が確立されます。

- INGESTの操作が、DELETE、UPDATE、MERGEのとき、デッドロック回避のために自動的に値を0や1に調整することがあります（例：ターゲットの表の探索条件に索引がない場合）。このとき、SQL2903Wの警告メッセージが出力されます。


INGESTの構成パラメーター（INGEST SETにて設定）

§ pipe_timeout ：

- パイプからの入力データをINGESTが待機する時間

- デフォルト： 600（10分）

§ retry_count：

- エラーの発生したトランザクションを再試行する回数

- デフォルト： 0（再試行なし）

§ retry_period

- エラーの発生したトランザクションを再試行する前の待機時間（秒）

- デフォルト： 0（待機なし）

§ shm_max_size：起動formatter数

- Ingestユーティリティが利用する共有メモリーの大きさ

- デフォルト： 1GB


Note：

§ pipe_timeout ：

- 入力データがパイプの場合に、パイプからの入力データをINGESTが待機する時間（秒）を指定します。

- デフォルトの値は600秒（10分）です。

§ retry_count：

- INGEST ユーティリティーは、以下の理由のいずれかによって失敗するトランザクションを再試行することができます。そのときの再試行回数を指定します。

• 接続が失敗したが、再確立された。

• デッドロックまたはタイムアウトが生じて自動ロールバックが行われた。

• システム・エラーのため、作業単位がロールバックされた。

• 仮想記憶またはデータベース・リソースを使用できない。

- デフォルトの値は0（再試行なし）です。

§ retry_period

- retry_countの設定に応じてトランザクションを再試行する際の、再試行前の待機時間（秒）を指定します。

- デフォルトの値は、0（待機なしで即時再試行）です。

§ shm_max_size：起動formatter数

- IngestユーティリティがINGESTが起動されるクライアント機上で利用する共有メモリーの大きさです。

- デフォルトの値は１GBです。


実行中のINGEST処理の確認－ INGEST LISTコマンド

db2 ingest list

Ingest job ID = DB21101:0161215.034333.811736:00007:00009Ingest temp job ID = 1Database Name = SAMPLETarget table = DB2INST1.TABLE01Input type = FILEStart Time = 12/15/2016 03:43:33.811736Running Time = 00:00:12Number of records processed = 780000

DB20000I The INGEST LIST command completed successfully.

INGEST GET STATS（次ページ）にて利用

開始からの経過時間

処理済みの行数


Note:

§ INGEST LISTコマンドによって、現在走行中のINGESTの状況を確認しています。

§ INGEST LISTコマンドは、INGESTが実行されているマシン上で実行してください。CLIENT側でINGESTが実行されているのであれば、INGEST LISTコマンドもCLIENT側で実行します。

§ INGEST LISTの出力に前頁で出力されたJOB IDが示されていることに注目してください。

§ この例にあるようにINGESTの開始からの経過時間や処理済みの件数などの情報が得られます。

§ また、INGEST一時JOBID（Ingest temp job ID）という情報も出力されています。このIDは現在実行中のIngestに対して順番に割り当てられる数字で、次ページで示すINGEST GET STATSの実行時に利用します。


実行中のINGEST処理確認－ INGEST GET STATSコマンド

db2 ingest get stats for 1

Ingest job ID = DB21101:0161215.034333.811736:00007:00009Database Name = SAMPLETarget table = db2inst1.TABLE01

Overall Overall Current Currentingest rate write rate ingest rate write rate(records/second) (writes/second) (records/second) (writes/second) Total records----------------- ----------------- ----------------- ----------------- -----------------

404821 142977 247617 181222 3145500

DB20000I The INGEST GET STATS command completed successfully.


Note:

§ INGEST GET STATSコマンドによって、INGEST処理の統計情報を収集している例です。

§ 前頁のINGEST LISTの出力によって確認したINGEST一時JOBIDの番号を指定して実行しています。

§ INGEST GET STATSの出力からは、１秒あたりの処理件数を知ることができます。



$ db2 ingest get stats for 1 show totals

================================================================================================Ingest job ID = DB21005:20161215.181813.713016:00002:00011Database Name = SAMPLETarget table = db2inst1.TABLE01------------------------------------------------------------------------------------------------Totals for all transporters

Since last query Since command start------------------------- ----------------------------

Number of bytes read 799735802 1065713645Number of records read 32276514 43459955Bytes per second 3772338 4212306Records per second 152247 171778

------------------------------------------------------------------------------------------------

<< 以下次ページ >>


Note:

§ INGEST GET STATSコマンドにSHOW TOTALSオプションをつけると、INGESTを構成するTRANSPORTER、FORMATTER、Flusherの各レイヤーにおける稼動状況を知ることができます。

§ FormatterでRejectされた行（データタイプが異なるなど実行SQLを組み立てるところでエラーとなった行）、FlusherでRejectされた行（ユニーク制約違反など、実際に表に書き込むところでエラーになった行）など、より詳細な統計情報を得ることができます。



<< 前ページから続く >>

Totals for all formatters


Number of records formatted 32280973 43442980Records per second 152268 171711Number of records rejected 0 0

------------------------------------------------------------------------------------------------Totals for all flushers


Number of records flushed 32049150 38130450Records per second 151175 150713Number of records rejected 0 0Number of reconnects 0 0Number of retries 0 0

DB20000I The INGEST GET STATS command completed successfully.


各種INGEST実行例

§ １．CSVファイル（区切り文字のあるACSIIデータ）からのINSERT

§ ２．パイプ ( | )で区切られたCSVファイルからのINSERT

§ ３．パイプからのデータによる置き換え（REPLACE)

INGEST FROM FILE file1.csv FORMAT DELIMITED INSERT INTO table01

INGEST FROM FILE file1.csv FORMAT DELIMITED BY ʻ|ʼ INSERT INTO table01

INGEST FROM PIPE pipe1.csv FORMAT delimited MESSAGE ingest.msg REPLACE INTO table01

※ 大量データを保持する表に対してReplaceオプションのINGESTを実行する場合、TRUNCATE TABLEコマンドにて表を空にしてから実行するとよい。


Note:

§ 1. 最も単純なケースです。コンマを列の区切り文字（デフォルト）として利用した入力ファイルfile1.csvをTABLE01表にINSERTしています。

§ ２．列の区切り文字として、コンマ「,」の代わりにパイプ「|」を利用した例です

§ ３．この例では、入力データとしてパイプを指定し、REPLACEを指定しています。

§ REPLACEオプションを指定すると、一度ターゲット表の内容を全件DELETEしてから入力データのINSERTを始めるため、既存データが大量に存在する場合、LOCKLISTやログ領域が枯渇する可能性があります。（IMPORTやLOADのREPLACEオプションではそのようなことは起きません）

§ 巨大な表に対して、REPLACEモードのINGESTを実行する場合、LOCKLISTやログ領域を十分に拡大しておく、という対応も考えられますが、もしINGESTが途中で失敗した場合でもRollbackする（表をReplace前の状態に戻す）必要が無いのであれば、TRUNCATE TABLEコマンドにて表の内容を空にするような運用とすると良いでしょう。


入力データのフィールド定義

§ 各フィールドの名称やデータタイプ、形式を指定する

- INGESTから実行されるDMLの中でフィールド名を利用することができる。

INGEST FROM FILE file1.csv FORMAT delimited （

$col01 INTEGER EXTERNAL ,$col02 DECIMAL(5,2) EXTERNAL ,$col03 CHAR(5) ,$col04 DATE ʻyyyy-mm-ddʼ

）UPDATE table01

SET（col03,col04) = ($col03,$col04) WHERE col01=$col01 and col02=$col02;

入力データがASCII文字データであることを示す。

DATE列のフォーマットを指定

指定したフィールド名を実行DMLの中で指定

100, 123.45，”ABCDE”,2017-01-01200, 234.56，”FG”,2017-01-02300, 345.67，”KLM”,2017-01-03

COL01 INTCOL02 DECIMAL(5,2)COL03 VARCHAR(5)COL04 DATE


Note:

§ INGESTでは、入力データの各フィールドに名称を指定し、それらのデータタイプや形式を指定することができます。

§ この例のように、INGESTの中で実行されるUPDATE/DELETE/MERGEの中でそれらのフィールド名を利用します。

§ ここでは、$col01～$col04がフィールド名です。それぞれにデータタイプが指定されています。

§ $col01と$col02にEXTERNALというキーワードが指定されていることに注目してください。これは、これらINTEGERやDECIMALといった数値列のデータが文字データとして提供されていることを示します。

§ $col03は文字列ですので、EXTERNAL指定不要です。ターゲットがVARCHAR列だった場合でも、入力データのフィールド定義ではCHARを指定します。

§ $col04は、DATE列であることを指定しています。また、入力データのフォーマットが「yyyy-mm-dd」の形式になっていることを指定しています。

§ フィールド定義のうしろに記述されたUPDATE文が実際にINGESTユーティリティから並列実行されるUPDATE文です。入力データの$col01+$col02と一致するcol01+col02の行を特定し、col03とcol04の値を$col03と$col04で更新します。


入力データのフィールド定義 (続き）

§ INGESTからは、DELETEやMERGEも実行可能

INGEST FROM FILE file1.csv FORMAT delimited （ $col01 INTEGER EXTERNAL,

$col02 DECIMAL(5,2) EXTERNAL ）DELETE FROM table01

WHERE col01=$col01 and col02=$col02;

INGEST FROM FILE file1.csv FORMAT delimited （ $col01 INTEGER EXTERNAL ,

$col02 DECIMAL(5,2) EXTERNAL ,$col03 CHAR(5) ,$col04 DATE ʻyyyy-mm-ddʼ）

MERGE INTO table01ON (col01=$col01) AND (col02=$col02)WHEN MATCHED THEN

UPDATE SET（col03,col04) = ($col03,$col04) WHEN NOT MATCHED THEN

INSERT VALUES（$col01,$col02,$col03,$col04)


Note:

§ 入力データのフィールドを定義しておけば、INGESTからDELETEやMERGEを実行することもできます。

§ 1番目の例では、入力データから提供される$col01+$col02のペアにマッチする行を削除しています。

§ 2番目の例では、入力データをMERGE、すなわち$col01+$col02のペアがマッチした場合にはUPDATEを使い、マッチしなかった場合には、INSERTを使ってTABLE01表に反映させています。

§ IMPORTのINSERT_UPDATEオプションによる大量データの反映を行っている場合、是非MERGEオプションのINGESTも利用検討してみてください。 IMPORTのINSERT_UPDATEオプションで実行される「最初にINSERTを実行し、キー重複のエラーが発生したらUPDATEで再実行」といった非効率的な処理は行いませんので、大幅な性能向上が期待できます。


区切りなしACSIIデータの位置指定

§ 各フィールドの位置情報を指定する

INGEST FROM FILE file1.csv FORMAT POSITIONAL （ $col01 POSITION(1:4) INTEGER LITTLE ENDIAN ,

$col02 POSITION(6:8) DECIMAL(5,2) PACKED ,$col03 POSITION(10:14) CHAR(5) RTRIM,$col04 POSITION((16:25) DATE ʻyyyy-mm-ddʼ ）

INSERT table01 VALUES（$col01,$col02,$col03,$col04)

INGEST FROM FILE file1.csv FORMAT POSITIONAL （ $col01 POSITION(1:8) INTEGER EXTERNAL,

$col02 POSITION(10:14) DECIMAL(5,2) EXTERNAL ,$col03 POSITION(16:20) CHAR(5) RTRIM,$col04 POSITION(22:31) DATEʻyyyy-mm-ddʼ ）

INSERT table01 VALUES（$col01,$col02,$col03,$col04)

各フィールドの開始位置と終了位置を指定

右側の空白文字を切り捨てる

Little Endianの整数、PackedDecimal形式の10進数など、ASCII文字以外の数値データをサポート

1234567890123456789012345678901-------------------------------

100 12345 ABCDE 2017-01-01200 23456 FG 2017-01-02300 34567 KLM 2017-01-03

COL01 INTCOL02 DECIMAL(5,2)

COL03 VARCHAR(5)COL04 DATE


Note:

§ ここで紹介するのは、ASC形式の入力データ、すなわち区切り文字によってフィールドの切れ目を示すのではなく、各フィールドの位置が決まっているようなデータの利用です。

§ FORMATパラメーターにはPOSITIONALが指定され、各フィールド定義の中で開始位置と終了位置を指定します。

§ フィールド定義の中でデータタイプを指定し、数値列のデータが数字キャラクターで提供される場合にEXTERNALと指定する点は、DEL形式のデータの場合と同様です。

§ $col03フィールドでRTRIMオプションが指定されているところに注目してください。ここでは16バイト目から20バイト目が$col03のデータであることを示していますが、右側の空白文字はすべて切り捨てることを指定しています。（ターゲット表の該当列はVARCHARであることを想定）

§ 2番目の例では、$col01と$col02にEXTERNALの指定がなく、代わりに$col01はLITTLE ENDIAN型のバイナリーデータ、$col02はPacked Decimal形式で表現された10進数であることを示しています。（Binary Integerであるcol01は4バイト、5桁の10進数がPacked Decimal形式で提供されているcol02は、3バイトの長さとなっています）


ダンプファイルと例外表へのエラーデータ出力

§ エラーデータをダンプファイルまたは例外表に書き出すことができる

- ダンプファイル： Formatterが拒否したデータ（例：データが指定タイプと不一致）を書き出す。

- 例外表： Flusherがターゲット表に反映しようとしたところでエラーとなったデータ（例：キー重複などの制約違反、文字列の切捨て発生）を書き出す。

INGEST FROM FILE file1.csv FORMAT delimited DUMPFILE dump1.txtEXCEPTION TABLE excepttab01 INSERT INTO table01

INGEST

DEL

DELDELà

àà

ààà

DB2

excepttab01

table01

dump1.txt

Discarded (DEFAULT)Rejected rows

Inserted rows

Rejected rows

Rejected rows


Note:

§ LOADユーティリティにも同様の機能がありますが、INGESTにおいてもエラーデータを別のファイル（ダンプファイル）や例外表に書き出すことができます。

§ INGEST実行後、これらのファイルや例外表を確認することによって、エラーの原因を分析し、必要な修正対応をして再度INGESTの入力とすることができます。

§ ダンプファイルと例外表の役割は、LOADユーティリティと同様です。

§ ダンプファイルには、例えば、数値列なのに0-9以外の文字が提供されていたり、ターゲットの列数とフィールドの数が合致しないなど、INGESTユーティリティのFormatterによってエラーとみなされて拒否されたデータを書き出すことができます。

§ 例外表には、例えば、ユニーク索引のキー重複や文字列の切捨て（列定義よりもデータが長かった）など、INGESTユーティリティのFlusherがDMLによるデータ反映をしようとした際にエラーとなったデータが書き出されます。

§ 例外表の詳細については以下マニュアルページをご参照ください。 https://ibm.biz/BdsGav


その他のINGEST実行例

§ １．特定フィールドのみをINSERT

§ ２．入力データを加工してから投入

§ ３．文字区切り文字を変更

INGEST FROM FILE file1.csv FORMAT delimited （ $data01 INTEGER EXTERNAL ,

$data02 INTEGER EXTERNAL ,$data03 INTEGER EXTERNAL ）

INSERT INTO table01 (COL01) VALUES （$data01+$data02+$data03)


$filter1 CHAR,$data02 INTEGER EXTERNAL ）

INSERT INTO table01 VALUES （$data01,$data02)


$data02 CHAR(10) OPTIONALLY ENCLOSED BY ʻ=ʻ ）INSERT INTO table01 VALUES （$data01, $data02)


Note:

§ その他の各種INGEST実行例です。

§ フィールド定義にて指定したフィールド名を利用することで、用途に応じた柔軟なデータ反映が可能になります。

§ 最初の例は、入力データの1番目と3番目のフィールドだけを使ってINSERTを実行する例です。

§ 次の例では、入力データのINTEGERフィールドを足しあわせてから、ターゲットのCOL01列にINSERTしています。

§ 3番目の例では、$data02フィールドの文字区切り文字（デフォルトではシングルクォート(')）としてイコール(=)を指定しています。


INGEST中断時の表の状態と処理再実行

§ INGESTが中断されたとき、途中までのコミット済みデータは反映された状態となる

- 途中までのコミット済みデータが反映された状態で、表の読み書きが可能

- LOADのTERMINATEオプションのようにユーティリティ開始前まで戻るオプションはない

§ RESTART CONTINUE オプションによって中断したINGESTを再開

- 中断されたINGESTのJOB IDをRESTART CONTINUEオプションで指定することで、

最後のCOMMIT地点からINGESTを継続することができる。

INGEST FROM FILE file.csv FORMAT DELIMITED RESTART NEW ʻJOB01ʼ INSERT INTO tab01

<<完了前に中断>>

INGEST FROM FILE file.csv FORMAT DELIMITED RESTART CONTINUE ʻJOB01ʼINSERT INTO table01

§ INGESTのRESTARTオプション

- RESTART NEW job-id：途中で中断したINGESTを再開するための情報を再開ログ表に記録RESTART CONTINUE job-id：中断したINGESTを再開

- RESTART TERMINATE job-id：中断したIngestの再開情報を再開ログ表から消去

- RESTART OFF：再開ログ表に情報を書き込まない


Note:

§ エラーの発生などの理由により、INGESTが中断してしまった場合の表の状態や、そこからの再開のための操作の説明です。

§ IMPORT処理の中断時と同様、INGESTの処理が中断した場合には、ターゲットの表には途中までのコミット済みデータが反映された状態となります。INGESTが中断された時点の未コミット変更はすべてロールバックされ、取得されていたロックも開放されますので、ターゲット表は自由に読み書きが可能な状態となります。反映されたコミット済みのデータをキャンセルしてINGEST開始前の状態に戻ることはできません。（ここもIMPORTと同様です）

§ 中断された処理を再開する場合、IMPORTでは自分で明示的に開始点の行数を指定しなくてはいけませんが、INGESTでは再開ログ表に途中経過を記録していますので、DB2は特に行数の指定をされなくてもこの情報を使って、INGESTを再開することができます。

§ このときに利用するのが各INGEST処理ごとに決定されるJOB IDです。 JOB IDは、INGESTの新規開始時に指定するRESTART NEWオプションで指定することができます。（明示的に指定しない場合には、自動的にJOB IDが割り当てられます。）

§ 中断されたINGESTを再開するためには、RESTART CONTINUEオプションにてJOB IDを指定します。

§ RESTARTオプションは、新規のINGEST JOB開始と中断からの再開時に使う、RESTART NEWとRESTART CONTINUEのほか、中断したINGEST処理の再開が不要なときに使うRESTART TERMINATE（再開ログ表から指定JOB IDの情報を消去）、RESTART OFF（再開ログ表に情報を書き込まない）などあります。

§ 中断されたINGESTの再開をそもそも必要としないのであれば、再開ログ表は用意せず、INGEST実行時も常にRESTART OFFを指定するようにしてください。


INGEST中断地点からの再始動例

db2 “ingest from file data.txt format delimited restart new ʻJOB01ʼ insert into tab01”SQL2979I The ingest utility is starting at "12/26/2016 19:53:26.357763".SQL2914I The ingest utility has started the following ingest job: "JOB01".SQL0952N Processing was cancelled due to an interrupt. SQLSTATE=57014SQL2977I Because of the previous error, the ingest utility will exit.SQL0952N Processing was cancelled due to an interrupt. SQLSTATE=57014


SQL2902I The ingest utility completed at timestamp "12/26/201619:53:43.195956". Number of errors: "2". Number of warnings: "0".

$ db2 "select count(*) from tab01"

1-----------

34000

1 record(s) selected.

JOB01とJob IDを指定してINGEST開始

Ctrl+Cにて処理中断

入力データ10万件のうち34000件が反映

コミット済みデータへのアクセス可能


Note:§ 途中で中断されたINGESTの再始動をする例です。

§ この例では、JOB IDとして「JOB01」が指定されてINGESTを起動し、途中でCtrl+C操作によりINGESTが中断されています。

§ 中断された時点でコミット済みであった34000件はINSERT済みであり、後続のSelectによって参照可能である点に注目してください。


INGEST中断地点からの再始動例（続き）

$ db2 "ingest from file data.txt format delimited restart continue 'JOB01' insert into tab01”SQL2979I The ingest utility is starting at "12/26/2016 19:54:13.751048".SQL2914I The ingest utility has started the following ingest job: "JOB01".


SQL2980I The ingest utility completed successfully at timestamp "12/26/201619:54:36.195348“

$ db2 "select count(*) from t"

1-----------

100000

1 record(s) selected.

JOB01を指定して再開

残りの66000件を反映


Note:

§ 前頁にて中断されたJOBID=JOB01のINGESTをRESTART CONTINUEオプションによって再開しています。

§ 先ほどINSERTできなかった66000件がINSERTされ、無事100000件全件をINSERTすることができました。


INGEST利用時の考慮点

§ 入力データはINGEST起動場所（クライアント）に配置

§ 入力データの順番どおりにデータを投入したい場合には、

num_flushers_per_partitionを0に設定（接続数を1にする）

§ 適切な頻度でコミットを実行し、LOCKLISTやログ領域の枯渇を防止する

- INGEST SET COMMIT_COUNT xxxx にてコミットの頻度を設定する

§ 巨大な表に対するREPLACEモードのINGESTに注意

- 最初に全件DELETEが実行されるため、LOCKLISTやログ領域枯渇の恐れあり

- TRUNCATE TABLE 表名 IMMEDIATEを実行してからINGEST実行するようにする

§ ユーティリティの負荷調整機能は、INGESTには効かない

- SET UTIL_IMPACT_PRIORITY コマンドやutil_impact_limデータベース・マネージャー構成パラメータの調整は INGEST コマンドに影響なし

§ シェルスクリプトから実行するINGESTがフィールド定義を持つ場合、フィールド名（$+文字列）を引用符で括るか、$の前にエスケープ文字(¥)を入れる。

db2 “INGEST ・・・ FORMAT DELIMITED （¥$col01 INT EXTERNAL, ¥$col02 INT EXTERNAL）・・・”


Note：

§ INGESTの考慮点については、KnowledgeCenterの「INGESTコマンド」のページに詳しい記載がありますので、ここでは代表的なものだけをいくつか上げておきます。

§ ⼊⼒データは、INGEST起動場所（クライアント）に配置- LOADの場合、LOADコマンドの起動がクライアント側であっても、⼊⼒データはサーバー側に配置する必要がありました。INGESTでは

、IMPORTと同様、クライアント側にデータファイル（またはパイプ）を配置します。§ ⼊⼒データの順番どおりにデータを投⼊してい場合には、num_flushers_per_partitionを０に設定する。

- NUM_FLUSHERS_PER_PARTITIONを0に設定することによって、⼊⼒データは、その⾏順に1件1件単⼀接続から投⼊されます。処理性能は低下しますが、⼊⼒データの順序通りにデータを投⼊したい場合には、明⽰的にFlusher数の調整を⾏ってください。

§ 適切な頻度でコミットを実⾏し、LOCKLISTやログ領域の枯渇を防⽌- INGESTにて⼤量にデータを投⼊する場合、LOCKLISTやログ領域の枯渇を防⽌するため、INGEST SET COMMIT_COUNT

xxxx にて適度な頻度でのコミット実⾏を⾏うようにしてください。§ 巨⼤な表に対するREPLACEモードのINGESTに注意

- 最初に全件DELETEが実⾏されるため、既に⼤量のデータが⼊っている場合には、LOCKLISTやログ領域枯渇の恐れがあります。このようなケースでは、⼀旦TRUNCATE TABLE 表名 IMMEDIATEを実⾏してターゲット表を空にしてからINGEST実⾏するようにすると良いでしょう。

§ ユーティリティの負荷調整機能は、INGESTには効かない- LOAD等の他のユーティリティの場合、SET UTIL_IMPACT_PRIORITY コマンドやutil_impact_limデータベース・マネージャー構

成パラメータの調整によって、ユーティリティ実⾏がシステムに与える負荷を低減することができません。これらの調整はINGESTコマンドには全く影響がありませんので、もし少しでも負荷を低減させたい場合には、Flusherの数を少なくする（INGEST SETにてNUM_FLUSHERS_PER_PARTITIONを調整）などの対応を⾏って草際。

§ 直接シェルスクリプトの中でINGESTコマンドを「 db2 “INGEST…”」のような形式で実⾏する場合の考慮点を紹介します。シェルスクリプトの中で「$col01」のようなフィールド名を使⽤すると、これをシェルスクリプト内の変数であると誤認識してしまいます。これを避けるため、フィールド名（$+⽂字列）を引⽤符で括るか、$の前にエスケープ⽂字(¥)を⼊れるようにしてください。ここで紹介している例では、$col01、$col02のフィールド名にそれぞれエスケープ⽂字をつけています。


参考資料

§ IBM Knowledge Center

- 「INGESTユーティリティ」 https://ibm.biz/BdsGAs- 「INGESTユーティリティの制約事項および制限事項」 https://ibm.biz/BdsGAj- 「INGESTコマンド」 https://ibm.biz/BdsGA2- 「INGEST SETコマンド」 https://ibm.biz/BdsGAL- 「INGEST, インポート、ロードの各ユーティリティの比較」https://ibm.biz/BdsGAS

§ ホワイトペーパー

- 「Introduction to the DB2 Continuous Data Ingest feature」https://ibm.biz/BdsGAa

- 「DB2 for LUW Best Practice: Ingesting data into an IBM Smart Analytics System」https://ibm.biz/BdsGAG

ingestユーティリティ - ibm...1.ingestユーティリティの概要...

Documents