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の作成時、以下の基本パラメータの設定が必要となっています。

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

Advanced Settingsについて

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

Advanced Settingsの中で、設定可能なパラメータは以下のとおりです。赤枠に示す箇所にCustom Hook という更に展開可能なメニューがありますが、こちらについては後ほどご紹介していきます。

Custom Hookについて

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

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

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

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

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

下記のドキュメンテーション（※該当頁は現在英語版のみ）の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における開発の幅が更に広がると思いますので、是非ご活用ください。

The post MarkLogic Data Hub Ingestion Stepのカスタマイズ appeared first on MarkLogic.