Hive UDF の使用

Hive UDF の各ジョブを実行する場合は、Hive クライアントでの以下のステップの個別実行を 1 つのセッションの範囲内で行うことも、必要なすべてのステップをまとめた HQL ファイルを作成してそれを一度に実行することもできます。

Hive クライアントで、必要な Hive データベースにログインします。
必要なデータ品質 Hive UDF が属する特定の Spectrum™ Data & Address Quality for Big Data SDK モジュールの JAR ファイルを登録します。

Validate Address の UDF の場合、COBOL ライブラリのパスを設定するには、環境変数 LD_LIBRARY_PATH を次のように設定します。

set mapreduce.admin.user.env = LD_LIBRARY_PATH=/home/hduser/~/runtime/lib:
/home/hduser/~/runtime/bin:/home/hduser/~/server/modules/universaladdress/lib, ACU_RUNCBL_JNI_ONLOAD_DISABLE=1, G1RTS=/home/hduser/~/ ;

Validate Address Global の UDF の場合は、libAddressDoctor5.so ファイルも追加します。
Validate Address Loqate の UDF の場合は、以下の必須ファイルを分散キャッシュに追加します。
- loqate-core.car
- LoqateVerificationLevel.csv
- Loqate.csv
- countryTables.csv
- countryNameTables.csv

実行するデータ品質ジョブの Hive UDF のエイリアスを作成します。

例:

CREATE TEMPORARY FUNCTION matchkeygenerator as 'com.pb.bdq.amm.process.hive.matchkeygenerator.MatchKeyGeneratorUDF';

リファレンスデータのパスを指定します。
- リファレンスデータを HDFS で使用する場合は、以下に示すように、リファレンスデータを追加し、リファレンスディレクトリを設定します。
  リファレンスデータが、ファイル形式の場合:
```
hdfs://<HOST>:<PORT>/home/hduser/Refdata/;
set hivevar:refdir='./Refdata';
```
  リファレンスデータが、アーカイブ形式の場合:
```
hdfs://<HOST>:<PORT>/home/hduser/ref.zip;
set hivevar:refdir='./ref.zip';
```
- リファレンスデータをローカルパスで使用する場合は、クラスタの各ノードで、同じパスに保存する必要があります。
  リファレンスディレクトリを以下のように設定します:
```
set hivevar:refdir='/home/hadoop/reference/';
```
ジョブの環境設定 (マッチルール、ソートフィールド、Express マッチ列、その他の詳細) を対応する変数や設定プロパティで指定します。
注: ルールは JSON 形式である必要があります。
例を次に示します。
```
set rule='{"matchKeys":[{"expressMatchKey":false, "matchKeyField":"MatchKey1",
"rules":[{"algorithm":"Soundex"," field":"businessname", "startPosition":1, "length":0,"active":true, "sortInput":null, "removeNoiseCharacters":false}]}, 
{"expressMatchKey":false, "matchKeyField":"MatchKey2", "rules":[{"algorithm":"Koeln", "field":"businessname", "startPosition":1, "length":0, "active":true, "sortInput":null, "removeNoiseCharacters":false}]}]}';
```
注: それぞれのジョブ環境設定の設定プロパティを使用してください。例えば、それぞれのサンプル HQL ファイルの随所に記載されている pb.bdq.match.rule、pb.bdq.match.express.column、pb.bdq.consolidation.sort.field などです。
入力テーブルのヘッダーフィールドをカンマ区切り形式で指定し、変数または設定プロパティに割り当てます。
```
set pb.bdq.match.header='businessname,recordid';
```
注: HQL ファイルに記載されている設定プロパティを使用します。例えば、pb.bdq.match.header、pb.bdq.consolidation.header などです。
次の例に示すように、Hive.Map.Aggr 環境変数の設定を false にして、Reducer と Mapper の間でのデータの集約をオフにします。
```
set hive.map.aggr = false;
```
注: この設定はすべての UDF で必要です。
ジョブを実行するための全般的な設定を次の例に示すように設定します。
```
set pb.bdq.uam.universaladdress.general.configuration = {"dFileType":"SPLIT", "dMemoryModel":"MEDIUM", "lacsLinkMemoryModel":"MEDIUM", "suiteLinkMemoryModel":"MEDIUM"};
```
注: この設定は Universal Addressing モジュールの Hive UDAF でのみ必要です。

ジョブを実行するための入力設定を次の例に示すように設定します。

set pb.bdq.uam.universaladdress.input.configuration = 
{"outputStandardAddress":true, "outputPostalData":false, "outputParsedInput":false,
 "outputAddressBlocks":true, "performUSProcessing":true, "performCanadianProcessing":
false, "performInternationalProcessing":false, "outputFormattedOnFail":false, 
"outputCasing":"MIXED", "outputPostalCodeSeparator":true, "outputMultinationalCharacters":
false, "performDPV":false, "performRDI":false, "performESM":false, "performASM":false, 
"performEWS":false, "performLACSLink":false, "performLOT":false, "failOnCMRAMatch":false,
 "extractFirm":false, "extractUrb":false, "outputReport3553":false, "outputReportSERP":false,
 "outputReportSummary":true, "outputCASSDetail":false, "outputFieldLevelReturnCodes":false,
 "keepMultimatch":false, "maximumResults":10, "standardAddressFormat":
"STANDARD_ADDRESS_FORMAT_COMBINED_UNIT", "standardAddressPMBLine":
"STANDARD_ADDRESS_PMB_LINE_NONE", "cityNameFormat":"CITY_FORMAT_STANDARD",
 "vanityCityFormatLong":true, "outputCountryFormat":"ENGLISH", "homeCountry":
"United States", "streetMatchingStrictness":"MATCHING_STRICTNESS_MEDIUM", 
"firmMatchingStrictness":"MATCHING_STRICTNESS_MEDIUM", "directionalMatchingStrictness":
"MATCHING_STRICTNESS_MEDIUM", "dualAddressLogic":"DUAL_NORMAL", 
"dpvSuccessfulStatusCondition":"A", "reportListFileName":"", "reportlistProcessorName":"",
 "reportlistNumber":1, "reportMailerAddress":"", "reportMailerName":"", 
"reportMailerCityLine":"", "canReportMailerCPCNumber":"", "canReportMailerAddress":"",
 "canReportMailerName":"", "canReportMailerCityLine":"", "internationalCityStreetSearching"
:100, "addressLineSearchOnFail":true, "outputStreetAlias":true, "outputVeriMoveBlock":false,
 "dpvDetermineNoStat":false, "dpvDetermineVacancy":false, "outputAbbreviatedAlias":false,
 "outputPreferredAlias":false, "outputPreferredCity":"CITY_OVERRIDE_NAME_ZIP4", 
"performSuiteLink":false, "suppressZplusPhantomCarrierR777":false, "canStandardAddressFormat"
:"D", "canEnglishApartmentLabel":"APT", "canFrenchApartmentLabel":"APP", "canFrenchFormat":
"C", "canOutputCityFormat":"D", "canOutputCityAlias":true, "canDualAddressLogic":"D", 
"canPreferHouseNum":false, "canSSLVRFLG":false, "canRuralRouteFormat":"A", 
"canNonCivicFormat":"A", "canDeliveryOfficeFormat":"I", "canEnableSERP":false, 
"canSwitchManagedPostalCodeConfidence":false, "stats":null, "counts":null, "z3seg":null,
 "serpStats":null, "dpvSeedList":null, "lacsSeedList":null, "zipInputSet":null, "reportName"
:null, "currentUser":null, "jobName":null, "jobId":null, "jobRequest":false, "properties":
{"DPVDetermineVacancy":"N", "DualAddressLogic":"N", "ExtractUrb":"N", "CanFrenchFormat"
:"C", "AddressLineSearchOnFail":"Y", "OutputFieldLevelReturnCodes":"N", 
"OutputFormattedOnFail":"N", "OutputStreetNameAlias":"Y", "OutputReportSERP":"N",
 "OutputAddressBlocks":"Y", "ExtractFirm":"N", "CanEnglishApartmentLabel":"APT", 
"OutputPreferredCity":"Z", "FirmMatchingStrictness":"M", "CanFrenchApartmentLabel":"APP",
 "KeepMultimatch":"N", "StandardAddressPMBLine":"N", "PerformSuiteLink":"N", 
"CanStandardAddressFormat":"D", "DPVSuccessfulStatusCondition":"A", "PerformLACSLink":"N",
 "PerformUSProcessing":"Y", "PerformEWS":"N", "StandardAddressFormat":"C", 
"SuppressZplusPhantomCarrierR777":"N", "HomeCountry":"United States", 
"ReportMailerAddress":"", "OutputReport3553":"N", "OutputVeriMoveDataBlock":"N",
 "CanDeliveryOfficeFormat":"I", "OutputAbbreviatedAlias":"N", "PerformCanadianProcessing":
"N", "PerformDPV":"N", "PerformInternationalProcessing":"N", "CanSSLVRFlg":"N", 
"StreetMatchingStrictness":"M", "InternationalCityStreetSearching":"100", 
"canSwitchManagedPostalCodeConfidence":"N", "CanDualAddressLogic":"D", "PerformASM":
"N", "OutputCasing":"M", "ReportListFileName":"", "CanReportMailerAddress":"", 
"ReportMailerCityLine":"", "CanReportMailerCPCNumber":"", "ReportListProcessorName":"",
 "CanOutputCityAlias":"Y", "DirectionalMatchingStrictness":"M", "CanRuralRouteFormat":
"A", "CanOutputCityFormat":"D", "ReportListNumber":"1", "CanReportMailerCityLine":"",
 "OutputMultinationalCharacters":"N", "EnableSERP":"N", "CanNonCivicFormat":"A", 
"OutputShortCityName":"S", "OutputPostalCodeSeparator":"Y", "FailOnCMRAMatch":"N", 
"PerformLOT":"N", "OutputCountryFormat":"E", "CanPreferHouseNum":"N", 
"CanReportMailerName":"", "PerformRDI":"N", "ReportMailerName":"", "PerformESM":"N",
 "OutputReportSummary":"Y", "OutputVanityCityFormatLong":"Y", "OutputPreferredAlias":"N",
 "DPVDetermineNoStat":"N", "MaximumResults":"10"}}};

注: この設定は Universal Addressing モジュールの Hive UDAF でのみ必要です。

ジョブを実行するためのエンジン設定を次の例のように設定します。

set pb.bdq.uam.universaladdress.engine.configurations = { "referenceData":{ "dataDir":"/home/hduser/resources/uam/universaladdress/UAM_universaladdress4.0_Feb15/", "referenceDataPathLocation":"LocaltoDataNodes"}, "cobolRuntimePath":"/home/hduser/addressquality/", "modulesDir":"/home/hduser/tapan/addressquality/modules", "dpvDbPath":null, "suiteLinkDBPath":null, "ewsDBPath":null, "rdiDBPath":null, "lacsDBPath":null};

注: この設定は Universal Addressing モジュールの Hive UDAF でのみ必要です。

適切な検証レベルを示すようにプロセスタイプを設定します。現時点では住所検証のみがサポートされています。
例えば、Validate Address ジョブでは、プロセスタイプを次のように設定します。
```
set pb.bdq.uam.universaladdress.process.type=VALIDATE; 
```
注: この設定は、Validate Address および Validate Address Loqate の Hive UDAF でのみ必要です。

ジョブを実行してジョブ出力をコンソールに表示するには、次の例に示すようにクエリを記述します。

SELECT businessname, recordid, bar.ret["MatchKey1"] AS MatchKey1, bar.ret["MatchKey2"] AS MatchKey2 FROM (
SELECT *, matchkeygenerator (${hiveconf:rule}, ${hiveconf:header}, businessname, recordid) AS ret FROM cust ) bar;

ジョブを実行してジョブ出力を指定されたファイルに書き出すには、以下の例に示すようにクエリを記述します。

INSERT OVERWRITE LOCAL DIRECTORY '/home/hadoop/MatchKey/' row format delimited FIELDS TERMINATED BY ',' MAP FIELDS TERMINATED BY ':' COLLECTION ITEMS TERMINATED BY '|' LINES TERMINATED BY '\n' STORED AS TEXTFILE 
SELECT businessname, recordid, bar.ret["MatchKey1"] AS MatchKey1, bar.ret["MatchKey2"] AS MatchKey2 FROM (
SELECT *, matchkeygenerator (${hiveconf:rule}, ${hiveconf:header}, businessname, recordid) AS ret FROM cust ) bar;

注: 先ほど UDF に対して定義したエイリアスを必ず使用してください。

重要: すべての UDAF ジョブで、それぞれの設定プロパティを変数として使用するとともに、該当するサンプル HQL ファイルに示されている入力パラメータを定義します。

例えば、pb.bdq.match.rule、pb.bdq.match.express.column、pb.bdq.consolidation.sort.field などです。