プラグインの定義
ここでは、プラグインを定義する方法を説明します。プラグインは、特殊な形式の Business Intelligence KPI です。
プラグインとその他の種類のモデル要素との比較については、"モデル・オプションの概要" を参照してください。
"BI サンプルのアクセス方法" も参照してください。
はじめに
プラグインは、アナライザおよびクエリで使用する 1 つ以上の計算を定義するクラスです。プラグインには、以下の特徴があります。
-
プラグイン・インスタンスは、指定されたコンテキストで最下位レベルのデータにアクセスできます。
-
パラメータを使用できます。
-
実行は非同期に行われます。プラグインをピボット・テーブルで使用している場合は、保留中のセルでプラグインの現在の状態を (文字列 n% complete として) 表示できます。
ピボット・テーブルは、結果が生成されると、自動的に更新されます。
-
プラグインが返す値はキャッシュされます。
プラグインは、複雑な計算または時間がかかる計算に特に適しています。例えば、ソース・レコードの複数の異なる部分や外部情報を使用する計算をする場合に、プラグインは適しています。
プラグインの使用方法
プラグイン・クラスに応じて、以下の方法のいずれかまたはすべてでプラグインを使用できます。
-
MDX %KPI 関数で使用します (この場合は、パラメータに値を指定することもできます)。これは、どのような場合でも可能です。
つまり、どのような場合でも、プラグインを使用する計算メンバを定義できます (計算メンバの定義の詳細は、"計算メンバの定義" を参照してください)。
-
アナライザおよびウィジェットで直接使用する。これは、PLUGINTYPE クラス・パラメータが "Pivot" で、PUBLIC クラス・パラメータが 1 (既定値) である場合に可能です。
アナライザまたはウィジェットで直接使用できないプラグインを作成するには、PLUGINTYPE を "Aggregate" と指定します。または、PUBLIC を 0 と指定します。
使用可能なプラグイン・クラス
%DeepSee.PlugIn パッケージには、計算メジャーで使用できるいくつかのプラグイン・クラスが用意されています。これらのクラスは以下のとおりです。
-
%DeepSee.PlugIn.DistinctOpens in a new tab — 指定されたセルの指定されたレベルの個別値の数を取得します。
%DeepSee.PlugIn.MedianOpens in a new tab — セルで使用される最下位レベルのすべてのレコード間で、指定されたメジャーの中央値を取得します。
-
%DeepSee.PlugIn.PercentileOpens in a new tab — セルで使用される最下位レベルのすべてのレコード間で、指定されたメジャーのパーセント値を取得します。
これらのプラグイン・クラスは、PLUGINTYPE が "Aggregate" と定義されているため、アナライザまたはウィジェットで直接使用することはできません。これらの詳細は、リファレンス "MDX 関数" に記載の "%KPI" を参照してください。
-
その他のクラス — Text Analytics で使用するためのより高度なプラグイン。これらのプラグインは、アナライザの [ピボット分析] 画面で使用されます。
もう 1 つのサンプル・プラグイン・クラスは BI.Model.KPIs.PluginDemo です。このプラグイン・クラスは、PLUGINTYPE が "Pivot" と定義されているため、直接使用できます。
プラグインを例示するサンプル
BI サンプルで、KPIs & Plug-ins フォルダ内のダッシュボードを参照してください。
-
HoleFoods Plug-ins ダッシュボードでは、HoleFoods キューブに定義されている計算メジャー Median Revenue および 90th Percentile Revenue を使用します。これらのメジャーは、%KPI 関数を使用してサンプル・プラグイン・クラス %DeepSee.PlugIn.MedianOpens in a new tab および %DeepSee.PlugIn.PercentileOpens in a new tab から値を取得します。
-
Patients Plug-ins ダッシュボードには、計算メジャー Median Test Score および 90th Percentile Test Score を使用するピボット・テーブルがあります。これらの計算メンバは、前の箇条書きのメンバと同様に Patients キューブに定義されています。
このダッシュボードには、もう 1 つのピボット・テーブルが含まれています。このピボット・テーブルは、サンプル・クラス BI.Model.KPIs.PluginDemo で定義されているプラグインを直接使用します。
単純なプラグインの要件
単純なプラグインを定義するには、以下のようにクラスを作成します。
-
%DeepSee.KPIPlugInOpens in a new tab をスーパークラスとして使用します。
-
少なくとも 1 つのプロパティを指定する KPI という名前の XData ブロックを定義します。以下に例を示します。
XData KPI [ XMLNamespace = "http://www.intersystems.com/deepsee/kpi" ] { <kpi name="PluginDemo" displayName="PluginDemo" caption="PluginDemo" > <property name="PatientCount" displayName="PatientCount" /> <property name="HighScoreCount" displayName="HighScoreCount" /> </kpi> }
他の KPI と同様に、フィルタも追加できます。
詳細は、"KPI クラスおよびプラグイン・クラスのリファレンス情報" を参照してください。
-
BASECUBE クラス・パラメータを指定します。単純なプラグインの場合、1 つのキューブまたはサブジェクト領域の論理名を指定します (ただし、このページで後述する "複数のキューブで使用するプラグインの作成" も参照してください)。
-
使用するベース MDX クエリを指定します。<kpi> の mdx 属性を指定するか、または %OnGetMDX() メソッドを以下に示す一般的な方法で実装します。
Method %OnGetMDX(ByRef pMDX As %String) As %Status { Set pMDX = "SELECT FROM "_..#BASECUBE Quit $$$OK }
コンテキスト情報 (行、列、およびフィルタ) が自動的にこのベース・クエリに適用されます。
-
%OnCompute メソッドで使用できるようにする必要があるフィールドを指定します。キューブのソース・テーブルに含まれるフィールドか、ファクト・テーブルに含まれるフィールドを指定できます。ハードコードされたリストを指定することも、フィールドのリストを定義するコールバックを使用することもできます。
これらのフィールドを指定するには、以下の操作を実行します。
-
使用するフィールドがファクト・テーブルにある場合は、LISTINGSOURCE クラス・パラメータに "FactTable" を指定します (ファクト・テーブルの詳細は、"ファクト・テーブルおよびディメンジョン・テーブルの詳細" を参照してください)。
このパラメータを省略した場合や "SourceTable" を指定した場合、プラグインは指定されたキューブのソース・テーブルを照会します。
-
フィールド名のハードコードされたリストを使用する場合は、LISTINGFIELDS クラス・パラメータを指定します。使用するフィールドのコンマ区切りリストを指定します。
以下に例を示します。
Parameter LISTINGFIELDS = "Field1, Field2, Field3";
フィールドにはエイリアスを指定できます。以下に例を示します。
Parameter LISTINGFIELDS = "Field1, Field2 as FieldAlias, Field3";
他のリストと同様に、矢印構文および SQL 関数も使用できます。
矢印構文を使用する場合は、フィールドのエイリアスを必ず指定してください。
-
フィールドのリストをプログラムで定義する場合は、%OnGetListingFields() メソッドを実装します。例えば、以下のメソッドにより、プラグインは 1 つのフィールドを取得します。
Method %OnGetListingFields() As %String { //could use an API to get the field name, but in this case factName is set //so the field name is known Set tListingFields = "MxTestScore" Quit tListingFields }
詳細は、"KPI のリストの定義" を参照してください。
-
-
%OnCompute() メソッドを実装します。このタスクの詳細は、この後のセクションを参照してください。
-
必要に応じて、PLUGINTYPE と PUBLIC の各クラス・パラメータを指定します。"プラグインの使用方法" を参照してください。
%OnCompute() の実装
プラグインで使用するピボット・テーブルのセルごとに、プラグインは LISTINGSOURCE の値に応じて DRILLTHROUGH クエリまたは DRILLFACTS クエリのどちらかを実行して、LISTINGFIELDS または %OnGetListingFields() (該当する場合) で指定されているフィールドを返します。その後で、このフィールド値を %OnCompute() メソッドに渡します。このメソッドには、以下のシグニチャがあります。
Method %OnCompute(pSQLRS As %SQL.StatementResult, pFactCount As %Integer) As %Status
以下は、この指定の説明です。
-
pSQLRS は、LISTINGFIELDS または %OnGetListingFields() で指定したフィールドを格納している %SQL.StatementResultOpens in a new tab のインスタンスです。
このクラスの使用法の詳細は、"ダイナミック SQL の使用" を参照してください。
-
pFactCount は、指定されたコンテキストでのファクトの合計数です。
このメソッドの実装では、以下の手順を実行します。
-
文の結果を繰り返し処理します。この操作には、このインスタンスの %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) について、そこから値を取得する計算メンバを作成できます。このメンバは、アナライザ内でドラッグ・アンド・ドロップできます。このような計算メンバを作成する手順は以下のとおりです。
-
"計算メジャーの定義" の説明に従って、計算メジャーを定義します。
-
[式] で、以下の形式の MDX 式を指定します。
%KPI(pluginname,propertyname,seriesname,"%CONTEXT")
pluginname はプラグインの名前、propertyname はプロパティの名前、seriesname は系列の名前です。seriesname は省略できます。省略した場合、この関数はプラグインの最初の系列にアクセスします。
"%CONTEXT" は、プラグインに行、列、およびフィルタのコンテキストを渡す特別なパラメータです。この情報は、プラグインで使用されるベース MDX クエリに渡されます。
例 (系列が 1 つだけのプラグインの場合) :
%KPI("PluginDemo2","Count",,"%CONTEXT")
PLUGINTYPE が "Pivot" に設定されているプラグインの場合、ユーザがプラグイン・プロパティをドラッグ・アンド・ドロップすると、アナライザは、自身が生成する基になる MDX クエリで上記のような構文を自動的に使用します。
追加のオプションの詳細は、"%KPI" を参照してください。