プラグインの定義

はじめに

プラグインは、アナライザおよびクエリで使用する 1 つ以上の計算を定義するクラスです。プラグインには、以下の特徴があります。

• プラグイン・インスタンスは、指定されたコンテキストで最下位レベルのデータにアクセスできます。

• パラメータを使用できます。

• 実行は非同期に行われます。プラグインをピボット・テーブルで使用している場合、保留中のセルでプラグインの現在の状態を (文字列 n% complete として) 表示できます。

  ピボット・テーブルは、結果が生成されると、自動的に更新されます。

• プラグインが返す値はキャッシュされます。

プラグインは、複雑な計算または時間がかかる計算に特に適しています。例えば、ソース・レコードの複数の異なる部分や外部情報を使用する計算をする場合に、プラグインは適しています。

単純なプラグインの要件

単純なプラグインを定義するには、以下のようにクラスを作成します。

• %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" を指定します (ファクト・テーブルの詳細は、"DeepSee モデルの定義" の “ファクト・テーブルおよびディメンジョン・テーブルの詳細” を参照してください)。

    このパラメータを省略した場合や "SourceTable" を指定した場合、プラグインは指定されたキューブのソース・テーブルを照会します。

  • フィールド名のハードコードされたリストを使用する場合は、LISTINGFIELDS クラス・パラメータを指定します。使用するフィールドのコンマ区切りリストを指定します。

    以下に例を示します。

    Parameter LISTINGFIELDS = "Field1, Field2, Field3";

    

    フィールドにはエイリアスを指定できます。以下に例を示します。

    Parameter LISTINGFIELDS = "Field1, Field2 as FieldAlias, Field3";

    

    他のリストと同様に、Caché 矢印構文および SQL 関数も使用できます。

    Caché 矢印構文を使用する場合、必ずフィールドにエイリアスを指定してください。

  • フィールドのリストをプログラムで定義する場合は、%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 のリストの定義” を参照してください。

  Note:

  プラグインの場合、LISTINGFIELDS パラメータと %OnGetListingFields() では、詳細リストまたはリスト・フィールドが定義されません。これらのオプションは、%OnCompute() メソッドで使用できるフィールドのみを定義します。

• %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 のインスタンスです。

  このクラスの使用法の詳細は、"Caché SQL の使用法" の “ダイナミック SQL の使用法” を参照してください。

• pFactCount は、指定されたコンテキストでのファクトの合計数です。

このメソッドの実装では、以下の手順を実行します。

1. 文の結果を繰り返し処理します。この操作には、このインスタンスの %Next() メソッドを使用します。

2. 必要に応じて、各行の値を取得します。文の結果のインスタンス (pSQLRS) には、リスト・クエリの 1 つのフィールドにつき 1 つのプロパティがあり、プロパティの名前はフィールド名と同じです。

   例えば、前のセクションで %OnGetListingFields() は 1 つのフィールド MxTextScore を取得しています。この場合、pSQLRS には MxTextScore という名前のプロパティが存在します。

3. 必要な計算を実行します。

4. 前の章の説明に従って、プラグイン・インスタンスのプロパティを設定します。少なくとも以下のプロパティを設定します。

   • %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(.tSC)) {
   If $$$ISERR(tSC) Quit
   set n = n + 1

   Set testscore = pSQLRS.MxTestScore
   if (testscore>95) {
     Set highcount = highcount + 1
  }

 }
 Set ..%data(1,"HighScoreCount") = highcount

これは SAMPLES の DeepSee.Model.KPIs.PluginDemoOpens in a new tab からの抜粋であり、アナライザで 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 を参照してください。

リストのフィルタ処理

プラグインは、他のシナリオでは使用できない機能を提供します。すなわち、詳細リストが表示されるときに使用するレコードを指定する機能です。既定では、ユーザが結果内の 1 つまたは複数の指定したセルの詳細リストを要求すると、DeepSee ではそれらのセルに関連付けられたすべてのレコードを示すリストが表示されます。ただし場合によっては、それらのサブセットを表示することが望ましいことがあります。例えば、サンプルの DeepSee.Model.KPIs.PluginDemoOpens in a new tab には 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 の行について考えてみてください。どちらかのセルのリストを表示した場合は、既定では、DeepSee では 158 件のレコードからなるリストが表示されます。既知のアレルギーがない 158 人の患者が存在するからです。しかし、HighScoreCount メジャーの目的は指定されたしきい値を上回るスコアの患者をカウントすることであるため、この行の HighScoreCount セルの詳細リストを表示する際は、このしきい値を上回るスコアの患者のみを表示することが望ましい場合があります。

この種類のフィルタ処理をプラグインに適用するには、リストに表示する必要のある任意のソース・クラス ID について、%OnCompute() の実装に以下のロジックを組み込んでください。

   set ..%data("IDLIST",pluginProperty,sourceClassID) = ""

ここで、pluginProperty はこのフィルタ処理を使用する必要のあるプラグイン・プロパティの名前であり、sourceClassID はソース・クラス内の ID です。(プラグインでファクト・クラスが別の形で使用される場合でも、この ID はソース・クラス ID である必要があります。このソース・クラス ID をプラグインで使用できるようにするには、%sourceId をフィールド・リストに追加します。)

指定されたプラグイン・プロパティについて、%data("IDLIST",pluginProperty) が定義されていない場合は、リストには、指定された 1 つまたは複数のセルに関連付けられたすべてのレコードが表示されます。

使用可能なエラーのログ作成

プラグインでエラーが発生した場合、マネージャのディレクトリにあるエラー・ログ・ファイルに書き込みます。このファイルの名前は、DeepSeeTasks_namespace.log です。

プラグインを使用する計算メンバの定義

任意のプラグイン (および他の任意の KPI) について、そこから値を取得する計算メンバを作成できます。このメンバは、アナライザ内でドラッグ・アンド・ドロップできます。このような計算メンバを作成する手順は以下のとおりです。

• "DeepSee モデルの定義" の “計算メジャーの定義” の説明に従って、計算メジャーを定義します。

• [式] で、以下の形式の MDX 式を指定します。

  %KPI(pluginname,propertyname,seriesname,"%CONTEXT")
  

  

  pluginname はプラグインの名前、propertyname はプロパティの名前、seriesname は系列の名前です。seriesname は省略できます。省略した場合、この関数はプラグインの最初の系列にアクセスします。

  "%CONTEXT" は、プラグインに行、列、およびフィルタのコンテキストを渡す特別なパラメータです。この情報は、プラグインで使用されるベース MDX クエリに渡されます。

  例 (系列が 1 つだけのプラグインの場合) ：

  %KPI("PluginDemo2","Count",,"%CONTEXT")
  

  

  PLUGINTYPE が "Pivot" に設定されているプラグインの場合、プラグイン・プロパティをドラッグ・アンド・ドロップすると、アナライザは自動的に上記のような構文を、自身が生成する基になる MDX クエリで使用します。

  他のオプションの詳細は、"DeepSee MDX リファレンス" の "%KPI" 関数を参照してください。