MarkLogic World 2020 Live Keynote – Register Now

MarkLogic Data Hub Ingestion Stepのカスタマイズ

※本記事の内容は、Data Hub v5.2.1を前提としています。

今回のエントリでは、MarkLogic Data HubにおけるIngestion Step(読み込みステップ)のカスタマイズについて、掘り下げていきたいと思います。
既にMarkLogic Data Hubの概要および、フローやステップに関する基礎知識をお持ちの方を読者対象としておりますので、これからMarkLogic Data Hubについて学ばれるという方は、下記のドキュメントやチュートリアルを先にご参照ください。

・Data Hub QuickStart チュートリアル
https://jp.marklogic.com/blog/data-hub-quickstart-tutorial-jp/

・MarkLogic Data Hubドキュメンテーション
日本語版: https://developer.marklogic.com/learn/data-hub-quickstart-jp/
英語版(最新): https://docs.marklogic.com/datahub/

Ingestion Stepのおさらい

MarkLogic Data Hub上では、フローとステップという単位でデータ統合のための実装を行っていきます。
読み込みやマッピング等、処理に応じたステップの種別が提供されており、ステップを組み合わせてフローを構成していきます。
本エントリでは、ソースデータの読み込みを担うIngestion Stepのカスタマイズ方法について解説をしていきます。

前述のData Hub QuickStartチュートリアルに基本的な利用手順の解説がありますが、基本的な設定パラメータについて、まずはおさらいしていきたいと思います。
Ingestion Stepの作成時、以下の基本パラメータの設定が必要となっています。

フィールド名 説明
Step Type ステップの種類を選択します。
Ingestion Stepを作成したい場合は、一覧からIngestionを選択します。

Name

ステップの名前を定義します。
読み込まれたデータは、「ステップ名と同名」のコレクションが設定される点に留意します。

Description

処理に関する補足説明を追記します(任意)。

 

続いて、チュートリアルでは触れられていなかったAdvanced Settingsの設定可能な項目について、確認していきましょう。

 

Advanced Settingsについて

Advanced Settingsをクリック(展開)すると、追加設定可能なパラメータが下記のように表示されます。


Advanced Settingsの中で、設定可能なパラメータは以下のとおりです。赤枠に示す箇所にCustom Hook という更に展開可能なメニューがありますが、こちらについては後ほどご紹介していきます。
フィールド名 説明
Target Database Ingestion Stepで読み込むデータの格納先データベースを変更することが出来ます。
デフォルトではSTAGINGデータベースが選択されています。MarkLogic Data Hubでは、原則データをそのまま(As-Is)の状態で取り込むことが推奨とされています。ソースとなる元データはSTAGINGデータベースに格納し、その後MarkLogic内でモデリング・キュレーションしたデータをFINALデータベースに格納する方式をベストプラクティスとしています。
Additional Target Collections MarkLogicではコレクションという単位で、データ管理を行うことを推奨としています。デフォルトでは、ステップ名がコレクション名となりますが、更に追加でコレクションを設定したい場合は、ここから追加することが可能です。

”+”アイコンをクリックすることにより、複数のコレクションを追加することも可能です。
(※”-”アイコンをクリックすると、削除できます)

Batch Size

 

MarkLogic Data Hubでは、Batchという単位に分けて処理を実行していきますが、その際の処理あたりの最大ドキュメント数を指定します。
※デフォルトは100になっていますが、チューニングを実施する際は必要に応じて変更を行います。
Thread Count ステップ実行時に利用するスレッド数を指定します。
※デフォルトは4となっていますが、チューニングを実施する際は必要に応じて変更を行います。

 

Custom Hookについて

続いてCustom Hookについて、ご紹介していきたいと思います。Custom Hookを利用することにより、ステップ実行の前もしくは後に任意の処理(=モジュール)を実行させることが可能です。

Custom Hookを利用する場合、下記の特徴に留意して利用する必要があります。
・Custom Hook定義の処理は、ステップの処理とは異なるトランザクションとして実行される
・更新系クエリ(xdmp.documentInsert等)の利用が可能である

Advanced Settings下部のCustom Hookをクリック(展開)すると、Custom Hookに関するパラメータが表示されます。

Custom Hookの利用にあたり、設定が必要となるパラメータは以下のとおりです。

フィールド名 説明
Module Custom Hookで実行したいモジュールのパスを指定します。モジュールは下記のData Hubプロジェクトディレクトリ内のロケーションに配置するようにすることによって、mlDeployコマンドによるデプロイ対象となります。(自動的に、MODULESデータベースにデプロイされる)
/プロジェクトルート/src/main/ml-modules/root/custom-modules/
Parameters Custom Hookモジュール側でパラメータを受け取れるようにしてある場合、Key-valueの形で指定します。
User モジュールの実行者となるユーザー名を指定します。
(デフォルトは、flow-operatorロール)
RunBefore FalseかTrueを選択します。
ステップ実行前にCustom Hookを実行したい場合はTrueを選択、ステップ実行後に処理を実行したい場合はFalseを選択します。

 

Custom Hookで利用するモジュール(コード)ですが、下記の変数をコード内に定義することにより、Data Hubの処理内の情報を取得し、プログラム内で利用することが可能となっています。

変数名 変数にストアされる情報
uris 対象ドキュメント(群)URIの配列
content 対象ドキュメントのオブジェクト配列
options ステップに対して渡されるOptionsオブジェクト
flowName 実行中のフロー名
stepNumber 各ステップに付与されるインデックス番号
(例:最初に実行されるstepのstepNumberは1)
step ステップ定義オブジェクト
database ターゲットのデータベース名

 

下記のドキュメンテーション(※該当頁は現在英語版のみ)のExampleセクションに、Custom Hookのモジュールのコードサンプルがありますので、参考にしてみてください。
参考: https://docs.marklogic.com/datahub/modules/creating-custom-hook-module.html

サンプルコードに関してポイントだけ補足すると、下記のような処理をCustom Hookを用いて実現しています。

①処理対象のドキュメントデータの取得
・はじめにcontent変数を定義し、処理対象ドキュメントのオブジェクト配列を取得

②注文データを読み込む際の前処理として、ステージングDB上に同一の注文データが存在しないかチェック
・ctsクエリを利用し、新規に読み込むデータと同一の注文ID、顧客名、注文日時、商品IDを持つデータがないか判定

③既に存在していた場合は既存のデータをアーカイブし、削除処理を実行
・アーカイブ用のURIを生成し、documentInsert()を実行
・アーカイブ後、documentDelete()を実行して既存データ

このようにCustom Hookは大変小回りの効く機能である反面、あまり処理を埋め込んでしまうとCustom Hookモジュール内のコードに隠れてしまうというトレードオフがあります。また前述のとおり、Custom Hook 内の処理が別トランザクションとして実行される点にも注意が必要です。要件に応じてCustom Stepとして処理を切り出すなど、メンテナンス性等も考慮した上でご活用頂ければと思います。

 

Custom Ingestion Stepについて

最後に、Custom Ingestion Stepについて少しご紹介させていただきます。MarkLogic Data Hubには、標準のIngestion Step以外に、Custom StepのType種別として、Custom Ingestion Stepというものが提供されています。

通常のIngest Stepとは異なり、Custom Ingestion Stepでは、下記のようにカスタムモジュールのURI指定が行えるフィールドが追加されているのが確認できます。

前述のCustom Hookは、あくまでStepに対する前・後処理を追加するための位置付けでした。
Custom Ingestion Stepを利用することによって、Ingest Stepの実行処理そのものをオーバライドし、カスタマイズすることが可能となっています。

Custom Ingestion Stepを作成すると、Data Hubプロジェクトの下記ディレクトリ配下にCustom Ingestion Stepのmain.sjsの雛形が自動生成されます。

/プロジェクトルート/src/main/ml-modules/root/custom-modules/ingestion/Custom Ingestion Step名/main.sjs

本エントリの中では詳細について割愛させていただきますが、後はCustom Stepと同じ要領で、必要なカスタム処理を記述していくことが出来るようになっています。
一点注意点として、Ingestion StepではURIの動的変更は行えない仕様となっています。データに含まれるIDに基づいて動的にURIを生成したい等の要件がある場合は、mlcp等別の読み込み手段をご検討ください。

今回は、MarkLogic Data HubにおけるIngestion Stepのカスタマイズに関する情報を取りまとめました。
中でもCustom Hookは、その他のマッピングやマスタリングなど全てのステップ種別で利用可能な機能となっています。
今回ご紹介した追加パラメータやCustom Hookを駆使することにより、Data Hubにおける開発の幅が更に広がると思いますので、是非ご活用ください。

 

 

 

 

当ウェブサイトではクッキーを使用しています。

当Webサイトを継続利用することにより、お客様はMarkLogicのプライバシーステートメントに従ってクッキーの使用に同意するものとします。