Method %OnCompute(pSQLRS As %SQL.StatementResult, pFactCount As %Integer) As %Status
以下は、この指定の説明です。
このメソッドの実装では、以下の手順を実行します。
-
文の結果を繰り返し処理します。この操作には、このインスタンスの %Next() メソッドを使用します。
-
必要に応じて、各行の値を取得します。文の結果のインスタンス (pSQLRS) には、リスト・クエリの 1 つのフィールドにつき 1 つのプロパティがあり、プロパティの名前はフィールド名と同じです。
例えば、前のセクションで %OnGetListingFields() は 1 つのフィールド MxTextScore を取得しています。この場合、pSQLRS には MxTextScore という名前のプロパティが存在します。
-
必要な計算を実行します。
-
"高度な KPI の定義" の説明に従って、プラグイン・インスタンスのプロパティを設定します。少なくとも以下のプロパティを設定します。
-
%seriesCount — このプラグインの系列 (行) 数を指定します。
プラグインの系列は 1 つにすることをお勧めします (PLUGINTYPE が "Pivot" に設定されているプラグインの場合、ユーザがプラグイン・プロパティをドラッグ・アンド・ドロップすると、アナライザは最初の系列のみを使用します)。
-
%seriesNames(n) — 系列 n の名前を指定します。n は整数値です。
-
%data(n,propname) — 系列 n に対して、特定のプロパティ (propname) の値を指定します。
プロパティ名は、XData ブロックの <property> の名前と正確に一致する必要があります。
以下はその例です。
// place answer in KPI output
set ..%seriesCount = 1
set ..%seriesNames(1) = "PluginDemo"
//set Count property of KPI -- just use received pFactCount
set ..%data(1,"PatientCount") = pFactCount
// iterate through result set to get HighScoreCount
set n = 0
set highcount = 0
while (pSQLRS.%Next()) {
set n = n + 1
set testscore = pSQLRS.MxTestScore
if (testscore>95) {
Set highcount = highcount + 1
}
if (pSQLRS.%SQLCODE < 0) {write "%Next failed:", !, "SQLCODE ", pSQLRS.%SQLCODE, ": ", pSQLRS.%Message quit}
}
set ..%data(1,"HighScoreCount") = highcount
これはサンプル・クラス BI.Model.KPIs.PluginDemo からの抜粋であり、アナライザで Patients キューブと共に使用できます。
完了状態の通知
プラグインは非同期的に実行されます。プラグインを含むクエリが実行された場合、プラグインの実行が完了する前にクエリが完了する可能性があります。この場合、結果が保留中になるセルが存在します。これらのセルに、プラグインの現在の状態を (文字列 n% complete として) 表示できます。そのためには、%OnCompute() 内で定期的に %SetPercentComplete() インスタンス・メソッドを起動します。引数は 0 ~ 100 の整数です。例えば、文の結果を繰り返し処理する間に以下の処理を実行できます。
// update pct complete
If (n#100 = 0) {
Do ..%SetPercentComplete(100*(n/pFactCount))
}
適切な手法は、%OnCompute() 内のロジックによって異なります。場合によっては、計算時間の大部分がこの繰り返しの外部で発生する可能性があります。
ピボット・テーブルは、結果が生成されると、自動的に更新されます。
複数のキューブで使用するプラグインの作成
これまでのセクションでは、1 つのキューブまたはサブジェクト領域で使用可能なプラグインを作成する方法について説明しました。一方、複数のキューブで使用可能なプラグインを作成することもできます。通常はプログラムによってクエリするフィールドを決定する必要があるので、実際には作成は困難です。
複数のキューブで使用可能なプラグインを作成するには、以下の追加手順を使用します。
-
BASECUBE クラス・パラメータとして以下のどちらかを指定します。
このオプションにより、プラグインを使用できるキューブおよびサブジェクト領域が決まります。
-
XData ブロック内に以下のフィルタ定義を追加します。
<filter name="%cube" displayName="Subject Area" />
名前は %cube にする必要がありますが、表示名には任意の値を使用できます。
アナライザ内でこのプラグインを使用する場合 (妥当な場合)、現在のキューブまたはサブジェクト領域の名前がこのフィルタに渡されます。同様に、MDX クエリ内でこのプラグインを使用する場合、クエリの FROM 節によってこのフィルタの値が決定します。
-
%cube フィルタの値を使用するように %OnGetMDX() メソッドを実装します。以下はその例です。
Method %OnGetMDX(ByRef pMDX As %String) As %Status
{
Set tBaseCube = ""
// Use %cube filter to find the base cube
If $IsObject(..%filterValues) {
If (..%filterValues.%cube'="") {
Set tBaseCube = ..%filterValues.%cube
}
}
If (tBaseCube'="") {
Set pMDX = "SELECT FROM "_tBaseCube
}
Quit $$$OK
}
-
リスト・クエリが、必要なすべてのキューブおよびサブジェクト領域で使用できることを保証します。以下のどちらかの方法を使用します。
例は、%DeepSee.PlugIn.MedianOpens in a new tab および %DeepSee.PlugIn.PercentileOpens in a new tab を参照してください。
プログラムによるリスト・フィールドの決定
プラグインで使用するクエリで LISTINGSOURCE が "FactTable" として指定されている場合、%OnGetListingSQL() で使用するフィールドをプログラムにより決定できるようにする追加のツールがあります。以下を実行できます。
-
XData ブロック内に以下のフィルタ定義を追加します。
<filter name="%measure" displayName="Measure" />
名前は %measure にする必要がありますが、表示名には任意の値を使用できます。このフィルタから、適用可能なキューブまたはサブジェクト領域で定義されているすべてのメジャーのリストが出力されます。
-
以下の手順に従って、%OnGetListingSQL() メソッドを実装します。
-
%measure フィルタの値を調べます。
-
%DeepSee.Utils クラスの %GetDimensionInfo() メソッドを使用して、選択したメジャーに関する情報を参照によって取得します。
この情報は、次の手順の入力として使用します。
-
%DeepSee.Utils クラスの %GetDimensionFact() メソッドを使用して、選択したメジャーが格納されているフィールドの名前を取得します。
-
必要に応じて、%OnGetListingOrderBy() コールバックと %OnGetListingMaxRows() コールバックを実装します。詳細は、%DeepSee.KPIPlugInOpens in a new tab のクラスリファレンスを参照してください。
例は、%DeepSee.PlugIn.MedianOpens in a new tab および %DeepSee.PlugIn.PercentileOpens in a new tab を参照してください。%DeepSee.Utils クラスのクラスリファレンスも参照してください。
リストのフィルタ処理
プラグインは、他のシナリオでは使用できない機能を提供します。すなわち、詳細リストが表示されるときに使用するレコードを指定する機能です。既定では、ユーザが結果内の 1 つまたは複数の指定したセルの詳細リストを要求すると、それらのセルに関連付けられたすべてのレコードを示すリストが表示されます。ただし場合によっては、それらのサブセットを表示することが望ましいことがあります。例えば、サンプル・クラス BI.Model.KPIs.PluginDemo には HighScoreCount というプラグイン・プロパティがあります。以下では、このプラグイン・プロパティをメジャーとして使用する MDX クエリの例を示しています。
SELECT NON EMPTY {[Measures].[%COUNT],%KPI("PluginDemo","HighScoreCount",,"%CONTEXT")} ON 0,
NON EMPTY [AllerSevD].[H1].[Allergy Severities].Members ON 1 FROM [PATIENTS]
Patient Count HighScoreCount
1 Nil known allergi 158 12
2 Minor 113 7
3 Moderate 103 5
4 Life-threatening 133 9
5 Inactive 122 8
6 Unable to determi 119 6
7 No Data Available 385 29
Nil known allergies の行について考えてみてください。どちらかのセルのリストを表示すると、既定では、158 件のレコードからなるリストが表示されます。既知のアレルギーがない 158 人の患者が存在するからです。しかし、HighScoreCount メジャーの目的は指定されたしきい値を上回るスコアの患者をカウントすることであるため、この行の HighScoreCount セルの詳細リストを表示する際は、このしきい値を上回るスコアの患者のみを表示することが望ましい場合があります。
この種類のフィルタ処理をプラグインに適用するには、リストに表示する必要のある任意のソース・クラス ID について、%OnCompute() の実装に以下のロジックを組み込んでください。
set ..%data("IDLIST",pluginProperty,sourceClassID) = ""
pluginProperty はこのフィルタ処理を使用する必要のあるプラグイン・プロパティの名前、sourceClassID はソース・クラス内の ID です (プラグインでファクト・クラスが別の形で使用される場合でも、この ID はソース・クラス ID である必要があります。このソース・クラス ID をプラグインで使用できるようにするには、%sourceId をフィールド・リストに追加します)。
指定されたプラグイン・プロパティについて、%data("IDLIST",pluginProperty) が定義されていない場合は、リストには、指定された 1 つまたは複数のセルに関連付けられたすべてのレコードが表示されます。
例
例を確認するには、以下に示すように、サンプル・クラス BI.Model.KPIs.PluginDemo を編集します。
-
以下のように、LISTINGFIELDS を変更します。
Parameter LISTINGFIELDS As STRING = "%sourceId,MxTestScore";
-
%OnCompute() の highcount 変数を設定している部分を見つけて、以下のように変更します。
if (testscore>95) {
Set highcount = highcount + 1
Set tHighScoreId = pSQLRS.sourceId
Set ..%data("IDLIST","HighScoreCount",tHighScoreId)=""
}
-
クラスを保存し、リコンパイルします。
その後、アナライザで、このプラグインの両方のプロパティを使用するピボット・テーブルを作成します (比較するため)。HighScoreCount プロパティを表示するセルを選択して、リストを表示します。スコアの高い患者のみが表示されている点に注目してください。比較のために、PatientCount プロパティを表示するセルを選択して、そのリストを表示します。この場合は、すべてのスコアの患者が表示されます。
使用可能なエラーのログ作成
プラグインでエラーが発生した場合、マネージャのディレクトリにあるエラー・ログ・ファイルに書き込まれます。このファイルの名前は、DeepSeeTasks_namespace.log です。
プラグインを使用する計算メンバの定義
任意のプラグイン (および他の任意の KPI) について、そこから値を取得する計算メンバを作成できます。このメンバは、アナライザ内でドラッグ・アンド・ドロップできます。このような計算メンバを作成する手順は以下のとおりです。
-
"InterSystems Business Intelligence のモデルの定義" の "計算メジャーの定義" の説明に従って、計算メジャーを定義します。
-
[式] で、以下の形式の MDX 式を指定します。
%KPI(pluginname,propertyname,seriesname,"%CONTEXT")
pluginname はプラグインの名前、propertyname はプロパティの名前、seriesname は系列の名前です。seriesname は省略できます。省略した場合、この関数はプラグインの最初の系列にアクセスします。
"%CONTEXT" は、プラグインに行、列、およびフィルタのコンテキストを渡す特別なパラメータです。この情報は、プラグインで使用されるベース MDX クエリに渡されます。
例 (系列が 1 つだけのプラグインの場合) :
%KPI("PluginDemo2","Count",,"%CONTEXT")
PLUGINTYPE が "Pivot" に設定されているプラグインの場合、ユーザがプラグイン・プロパティをドラッグ・アンド・ドロップすると、アナライザは、自身が生成する基になる MDX クエリで上記のような構文を自動的に使用します。
他のオプションの詳細は、"InterSystems MDX リファレンス" の "%KPI" 関数を参照してください。