Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

DeepSee クエリのプログラム実行

この章では、DeepSee 結果セット API の使用方法と、MDX ファイルが含まれているファイルの実行方法を説明します。以下のトピックについて説明します。

%ShowPlan() および %PrintStatistics() の詳細は、このドキュメントで後述する “DeepSee クエリ・エンジンの仕組み” を参照してください。

結果セット API の使用

%DeepSee.ResultSetOpens in a new tab クラスを使用すると、DeepSee キューブに対して MDX クエリを実行し、結果を表示して検証できます。このクラスを使用するには、以下の操作を実行します。

  1. %DeepSee.ResultSetOpens in a new tab のインスタンスを作成します。

    以下はその例です。

     set rset=##class(%DeepSee.ResultSet).%New()
  2. オプションで、キャッシュの使用を無効にします。そのためには、そのインスタンスの %UseCache プロパティを 0 に設定します。以下はその例です。

     set rset.%UseCache=0

    既定では、キャッシュは有効になっています。

  3. オプションで、トレースを有効にします。準備フェーズで詳細トレースを有効にするには、結果セット・インスタンスの %Trace プロパティを 1 に設定します。クエリのすべてのフェーズでトレースを有効にするには、%dstrace 変数を 1 に設定します。次に例を示します。

     set rset.%Trace=1
     set %dstrace=1

    既定では、トレースは無効になっています。

  4. MDX クエリを文字列として作成します。以下に例を示します。

     set query="SELECT MEASURES.[%COUNT] ON 0, diagd.MEMBERS ON 1 FROM patients"

    DeepSee でサポートされている MDX 構文および関数の詳細は、"DeepSee での MDX の使用法" および "DeepSee MDX リファレンス" を参照してください。

  5. クエリを準備して実行します。通常、以下の操作を行います。

    1. クエリ文字列を引数として使用し、インスタンスの %PrepareMDX() メソッドを呼び出します。

    2. %Execute() または %ExecuteAsynch() を呼び出します。

    これらの各メソッドはステータスを返します。処理を進める前に、このステータスを確認するコードを用意する必要があります。

    または、%ExecuteDirect() を呼び出すことで、クエリを準備して実行することもできます。

    あるいは、%DeepSee.ResultSetOpens in a new tab の下位レベルのメソッドを呼び出すこともできますが、ここではそれらのメソッドについては説明しません。

    Note:

    クエリでプラグインを使用する場合、保留中の結果がすべて完了するまで、%Execute()%ExecuteDirect() は値を返しません。具体的には、 DeepSee エンジンがクエリで使用されるプラグインの実行を終了するまで、これらは値を返しません。

  6. %ExecuteAsynch() を使用する場合、クエリが完了したかどうかを定期的に確認します。クエリでプラグインを使用する場合、保留中の結果が完了したことも確認してください。保留中の結果はプラグインからの結果で、クエリとは別に実行されます。

    クエリのステータスを判別するには、インスタンスの %GetStatus() メソッドを呼び出します。または、%DeepSee.ResultSetOpens in a new tab%GetQueryStatus() クラス・メソッドを呼び出します。これらのメソッドはクエリのステータスを返し、さらに保留中の結果のステータスも (別々に) 返します。詳細は、クラス・ドキュメントを参照してください。

    未完了のクエリをキャンセルするため、必要に応じて、%CancelQuery() クラス・メソッドを呼び出します。

  7. これで、%DeepSee.ResultSetOpens in a new tab のインスタンスにクエリ結果が含まれます。ここで、そのインスタンスのメソッドを使用して、以下のようなタスクを実行することができます。

    • 結果の出力。

    • セル値の取得、結果セット内のセル数または軸数の取得、およびその他の結果の検証。

    • クエリ・プラン、リストに使用される SQL、クエリ内のセル範囲に使用される MDX など、クエリ自体のメタデータの取得。

    • クエリ統計の取得。

基本的な例

以下の例では、クエリを作成して準備し、これを実行して結果セットを出力として返し、結果を表示します。

ClassMethod RunQuery1(Output result As %DeepSee.ResultSet) As %Status
{
 Set rset=##class(%DeepSee.ResultSet).%New()
 Set query="SELECT MEASURES.[%COUNT] ON 0, diagd.MEMBERS ON 1 FROM patients"
 Set status=rset.%PrepareMDX(query)
 If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit status}

 Set status=rset.%Execute()
 If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit status}
   
 Write !, "Full results are as follows ***************",!
 Do rset.%Print()
 Quit $$$OK
}

ターミナルでこのメソッドを実行すると、以下のような結果が表示されます。

SAMPLES>do ##class(DeepSee.APISamples).RunQuery1()
 
Full results are as follows ***************
                             Patient Count
1 None                                8,394
2 asthma                                671
3 CHD                                   357
4 diabetes                              563
5 osteoporosis                          212

クエリの準備と実行

クエリを準備して実行する場合、通常以下のメソッドを使用します。

%PrepareMDX()
method %PrepareMDX(pMDX As %String) as %Status

クエリを解析し、実行時クエリ・オブジェクトに変換し、実行に向けて準備します。

%Execute()
method %Execute(ByRef pParms) as %Status

クエリを同期的に実行します。pParms 引数については、このリストの後で説明します。これは、クエリの準備が完了した後にのみ使用します。

%ExecuteAsynch()
method %ExecuteAsynch(Output pQueryKey As %String, 
                      ByRef pParms, 
                      pWait As %Boolean = 0) as %Status

クエリを非同期的に (または、pWait の値に応じて同期的に) 実行します。引数については、このリストの後で説明します。これは、クエリの準備が完了した後にのみ使用します。

%ExecuteDirect()
classmethod %ExecuteDirect(pMDX As %String, 
                           ByRef pParms, 
                           Output pSC As %Status) as %DeepSee.ResultSet

クエリを準備して実行し、結果セットを返します。pSC はステータスであり、その内容をチェックする必要があります。その他の引数については、このリストの後の説明を参照してください。

以下はその説明です。

  • pParms — このクエリで使用する名前付きパラメータの値を指定します。これは、以下のように 1 つ以上のノードを持つ多次元配列です。

    ノード
    パラメータ名 (大文字と小文字の区別なし) このパラメータの値

    これらの値は、クエリ自体の本文内に指定されている同じパラメータの値をオーバーライドします。

  • pQueryKey — このクエリの一意のキーを返し、このクエリを後で (クエリのキャンセル、セル数の取得などの目的で) 参照する際に使用できるようにします。

  • pWait — クエリが完了するまで待ってから、このメソッド呼び出しから戻るかどうかを指定します。

    pWait が True の場合、%ExecuteAsynch() は同期的に実行されます。

以下のサンプルでは、名前付きパラメータを含むクエリが使用されています。これは、インターシステムズによる MDX への拡張機能です。

ClassMethod RunQuery2(city as %String = "Magnolia",Output result As %DeepSee.ResultSet) As %Status
{
 Set rset=##class(%DeepSee.ResultSet).%New()
 Set query="WITH %PARM c as 'value:Pine' "
             _"SELECT homed.[city].@c ON 0 FROM patients"
 Set status=rset.%PrepareMDX(query)
 If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit status}

 Set myparms("c")=city
 Set status=rset.%Execute(.myparms)
 If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit status}
   
 Write !, "Full results are as follows ***************",!
 Do rset.%Print()
 Quit $$$OK
}

ターミナル・セッションの例を以下に示します。

d ##class(DeepSee.APISamples).RunQuery2("Centerville")
 
Full results are as follows ***************
                               Centerville
                                      1,124

クエリ結果の出力

診断のためにクエリ結果を表示するには、以下のメソッドのいずれかを使用します。

%Print()

クエリ結果を出力し、ステータスを返します。使用例については、この章で前述した “基本的な例” および “クエリの準備と実行” を参照してください。

%PrintListing()

クエリで MDX DRILLTHROUGH 節が使用されている場合、このメソッドはクエリの最初のセルのドリルスルーを行い、結果を現在のデバイスに出力します。それ以外の場合は、エラーを出力します。

このメソッドは何も返しません。

Important:

どちらのメソッドでも、各データ行の先頭に (すなわち列見出しの後に) 行番号が付加されます。この行番号は結果の一部ではありません

以下は、%PrintListing() の例です。

ClassMethod RunQuery3() 
{
    Set rset=##class(%DeepSee.ResultSet).%New()
    
    Set query="DRILLTHROUGH SELECT gend.female ON 0,birthd.[1913] ON 1 "
             _"FROM patients RETURN PatientID,PrimaryCarePhysician->LastName"

    Set status=rset.%PrepareMDX(query)
    If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit}

    Set status=rset.%Execute()
    If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit}
    
    Write !, "Listing details for the first cell are as follows ***************",!
    Do rset.%PrintListing()
}

これは、以下のようにターミナルで使用できます。

SAMPLES>d ##class(DeepSee.APISamples).RunQuery3()
 
Listing details for the first cell are as follows ***************
   #  PatientID      LastName
   1: SUBJ_101317    Xiang
   2: SUBJ_104971    North
   3: SUBJ_105093    Klausner
   4: SUBJ_109070    Quine

クエリ結果の検証

プログラムによってクエリ結果を操作するには、まずそれらの構成を理解する必要があります。結果セットは、一連の軸から成るセルのセットです。結果セットの構成が不明な場合は、%GetRowCount() および %GetColumnCount() を使用して行数と列数に関する情報を取得します。

次に、指定したセルの値にアクセスするには、%GetOrdinalValue() メソッドを使用します。または、列ヘッダと行ヘッダのラベルにアクセスするには、%GetOrdinalLabel() メソッドを使用します。または、セルで使用されているメンバに関する詳細情報を取得するには、%GetAxisMembers() メソッドを使用します。次のサブセクションで詳細を説明します。

Note:

DRILLTHROUGH クエリの結果を調べるための、さまざまなメソッドが用意されています。次のセクションを参照してください。

列数と行数の取得

結果セット内の列数を取得するには、%GetColumnCount() を使用します。

同様に、行数を取得するには %GetRowCount() を使用します。

例えば、以下のメソッドは特定の結果セットを出力し、前述のメソッドを使用して、この結果セットの軸について報告します。

ClassMethod ShowRowAndColInfo(rset As %DeepSee.ResultSet)
{
    //print query results
    write !, "Result set for comparison",!
    do rset.%Print()
    
    set colCount=rset.%GetColumnCount()
    set rowCount=rset.%GetRowCount()
    write !, "This result set has ",colCount, " column(s)"
    write !, "This result set has ",rowCount, " row(s)"
}

以下は、このメソッドの出力例です。

Result set for comparison
                             Patient Count
1 None                                  844
2 asthma                                 55
3 CHD                                    38
4 diabetes                               55
5 osteoporosis                           26
 
This result set has 1 column(s)
This result set has 5 row(s)

以下は、異なる結果セットに基づいた出力例です。

Result set for comparison
 
1 0 to 29->Female                       207
2 0 to 29->Male                         192
3 30 to 59->Female                      205
4 30 to 59->Male                        209
5 60+->Female                           115
6 60+->Male                              72
 
This result set has 1 column(s)
This result set has 6 row(s)

前述のとおり、%Print() によって各データ行の先頭に行番号が付加されますが、この行番号は結果の一部ではありません。

指定のセルの値の取得

指定したセルの値を取得するには、%GetOrdinalValue() を使用します。このメソッドには、以下のシグニチャがあります。

method %GetOrdinalValue(colNumber,rowNumber) as %String

ここで、colNumber は列番号です (1 は最初の列を表します)。同様に、rowNumber は行番号です (1 は最初の行を表します)。該当するセルが結果セット内にない場合は、このメソッドは NULL を返します。

列または行のラベルの取得

列または行で使用するラベルを取得するには、インスタンスの %GetOrdinalLabel() メソッドを呼び出します。このメソッドには、以下のシグニチャがあります。

method %GetOrdinalLabel(Output pLabel As %String, 
                        pAxis As %Integer, 
                        pPosition As %Integer, 
                        Output pFormat As %String) as %Integer

以下は、この指定の説明です。

  • pLabel は、以下のようにラベルごとに 1 つのノードを持つ多次元配列です。

    ノード
    ラベル番号を表す整数。最初のラベルが 1 で、以降同様です。 ラベル

    この配列では、最初のラベルは最も具体的な (最も内側の) ラベル、2 番目のラベルはその次に具体的なラベル (以降同様) です。例を参照してください。

    この配列は出力パラメータとして返されます。

  • pAxis は、検証する軸です。列のラベルを取得するには 1 を指定し、行のラベルを取得するには 2 を指定します。

  • pPosition は、検証する軸に沿った位置です。最初の位置は 1 です。

このメソッドは、指定された軸上の指定された位置にあるラベルの数を返します。以下に例を示します。この例では、(軸が複数のラベルを持つように) CROSSJOIN クエリを実行して、ラベルと比較できるように結果を表示してから、この軸上のメンバを繰り返し処理し、それぞれのラベルを出力します。

ClassMethod ShowRowLabels() As %Status
{
    Set rset=##class(%DeepSee.ResultSet).%New()
    Set query="SELECT CROSSJOIN(aged.[age group].MEMBERS,"
    Set query=query_"gend.gender.MEMBERS) ON 1 FROM patients"
    Set status=rset.%PrepareMDX(query)
    If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit status}

    Set status=rset.%Execute()
    If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit status}
    
    Write !, "Full results are as follows ***************",!
    Do rset.%Print()
    
    Write !, "Labels used on the rows are as follows ***************",!
    For j=1:1:rset.%GetRowCount() {
        Write !, "Row ",j
        Set labelcount=rset.%GetOrdinalLabel(.pLabel,2,j)
        For i=1:1:labelcount {
            Write !, "    label("_i_") is "_pLabel(i)
            }
       }
    
    Quit $$$OK
}

ターミナルで実行すると、このメソッドは以下のような出力を生成します。

SAMPLES>d ##class(DeepSee.APISamples).ShowRowLabels()
 
Full results are as follows ***************
 
1 0 to 29->Female                       207
2 0 to 29->Male                         192
3 30 to 59->Female                      205
4 30 to 59->Male                        209
5 60+->Female                           115
6 60+->Male                              72
  
Labels used on the rows are as follows ***************
 
Row 1
    label(1) is Female
    label(2) is 0 to 29
Row 2
    label(1) is Male
    label(2) is 0 to 29
Row 3
    label(1) is Female
    label(2) is 30 to 59
Row 4
    label(1) is Male
    label(2) is 30 to 59
Row 5
    label(1) is Female
    label(2) is 60 +
Row 6
    label(1) is Male
    label(2) is 60 +
SAMPLES>

セル・コンテンツの詳細の取得

ここまでは、この章ではラベルとセル値を取得する手順のみを紹介してきました。場合によっては、指定したセルのコンテンツに関するより具体的な情報が必要になることがあります。

まず、いくつかのサンプル・クエリを参考として挙げて、概念を検証することが有用です。例えば、DeepSee シェルに表示された次のクエリ結果について考えてみてください。

                             Patient Count
1 None                                  844
2 asthma                                 55
3 CHD                                    38
4 diabetes                               55
5 osteoporosis                           26

この例では、各行は診断ディメンジョンの 1 つのメンバに対応しています。列は、Measures ディメンジョンの 1 つのメンバ (Patient Count) に対応しています。以下にもう 1 つの例を示します。

                             Patient Count
1 0 to 29->Female                       207
2 0 to 29->Male                         192
3 30 to 59->Female                      205
4 30 to 59->Male                        209
5 60+->Female                           115
6 60+->Male                              72

この例では、各行は 1 つのタプルに対応しています。このタプルは、年齢グループ・ディメンジョンの 1 つのメンバと性別ディメンジョンの 1 つのメンバを組み合わせたものです。(タプルは複数のメンバの共通部分です。)

一般に MDX 結果セット内では、各行は 1 つのタプルに対応しており、各列も 1 つのタプルに対応しています。これらの各タプルは、最初の例のように単一のシンプルなメンバである場合も、2 つ目の例のように複数メンバの組み合わせである場合もあります。タプルには、メジャーが含まれる場合と含まれない場合があります。

任意の指定したセルについて、そのセルが属する列や行のタプルに関する情報が必要になることがあります。これらのタプルに関する情報を取得するには、以下の手順を実行します。

  1. 結果セットの %GetAxisMembers() メソッドを実行します。

    method %GetAxisMembers(pAxis As %Integer, 
                           Output pKey, 
                           pItemNo As %Integer = "") as %Status
    

    要求された軸 (およびその軸上の要求されたオプションの項目) の情報を検索し、それをプロセス・プライベート・グローバルに書き込み、参照によってそのグローバルから情報を取得するために使用できるキーを返します。(DeepSee は、この情報をプロセス・プライベート・グローバルに書き込みます。これは、この情報が大量の情報になる可能性があり、その構造を事前に特定することができないためです。)

    pAxis では、対象の軸を必要に応じて指定します。

    • 0 を使用すると、スライサ軸 (WHERE 節) に関する情報が返されます。

    • 1 を使用すると、列に関する情報が返されます (これは、MDX の軸 0 です)。

    • 2 を使用すると、行に関する情報が返されます。

    pKey は、出力パラメータとして返されます。これは、その情報に後でアクセスするために使用するキーです。

    pItemNo では、情報が必要な軸に対するタプルを必要に応じて指定します。この引数を指定すると、このメソッドは、指定されたタプルのみのデータを書き込みます。この引数を省略すると、このメソッドはすべてのタプルのデータを書き込みます。軸上の最初のタプルには 1 を使用します。

  2. pKey を使用して、プロセス・プライベート・グローバル ^||DeepSee.AxisMembers から適切なノードを取得します。%GetAxisMembers() メソッドは、データをノード ^||DeepSee.AxisMembers(pKey,pAxis,j,k) に書き込みます。以下はその説明です。

    • pKey は、%GetAxisMembers() メソッドから返されるキーです。

    • pAxis は、軸を指定する整数です。

    • j は、対象のタプルを指定する整数です。軸上の最初のタプルには 0 を使用します。

    • k は、対象のタプルのメンバを指定する整数です。タプルの最初のメンバには 1 を使用します。

  3. これらの各ノードから、適切なリスト項目を取得します。^||DeepSee.AxisMembers の各ノードは、以下の形式の値を保持します。

    $LB(nodeno,text,dimName,hierName,levelName,memberKey,dimNo,hierNo,levelNo)
    

    以下は、この指定の説明です。

    • nodeno は、軸のこの部分のノード番号です。

    • text は、軸のこの部分のテキストです。

    • dimNamehierName、および levelName は、軸のこの部分に使用されるディメンジョン、階層、およびレベルの名前です。

    • memberKey は、軸のこの部分に使用されるメンバのキーです。

    • dimNohierNo、および levelNo は、軸のこの部分に使用されるディメンジョン、階層、およびレベルの数です。

  4. プロセス・プライベート・グローバル ^||DeepSee.AxisMembers の生成されたノードを削除します。

    または、%GetAxisMembers() メソッドを使用している他のプロセスがないことが明らかな場合には、グローバル全体を削除します。

    このグローバルを DeepSee が自動的に削除することはありません。

次のサンプル・メソッドは、指定された結果セットとセル位置に基づいて、指定されたセルの列と行のタプルの情報を出力します。

ClassMethod ShowCellDetails(rset As %DeepSee.ResultSet, col As %Integer = 1, row As %Integer = 1)
{
    //print query results 
    write !, "Result set for comparison",!  
    do rset.%Print()

    //call %GetAxisMembers to build process-private global with info 
    //for given result set and axis; return key of node that has this info
    Set status=rset.%GetAxisMembers(1,.columnkey)
    If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit}
    Set status=rset.%GetAxisMembers(2,.rowkey)
    If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit}
    
    write !, "We are looking at the cell ("_col_","_row_")"
    write !, "The value in this cell is ", rset.%GetOrdinalValue(col,row)
    write !, "For this cell, the column is a tuple that combines the following member(s):"
    set i=0
    while (i '= "") {
        write !, "   Member ",i
        set infolist=^||DeepSee.AxisMembers(columnkey,1,col,i)
        write:$LI(infolist,3)'="" !, "      Dimension name: ",$LI(infolist,3)
        write:$LI(infolist,4)'="" !, "      Hierarchy name: ",$LI(infolist,4)
        write:$LI(infolist,5)'="" !, "      Level name: ",$LI(infolist,5)
        write:$LI(infolist,6)'="" !, "      Member key: ",$LI(infolist,6)
        set i=$ORDER( ^||DeepSee.AxisMembers(columnkey,1,col,i) )
    }

    write !, "For this cell, the row is a tuple that combines the following member(s):"
    set i=0
    while (i '= "") {
        write !, "   Member ",i
        set infolist=^||DeepSee.AxisMembers(rowkey,2,row,i)
        write:$LI(infolist,3)'="" !, "      Dimension name: ",$LI(infolist,3)
        write:$LI(infolist,4)'="" !, "      Hierarchy name: ",$LI(infolist,4)
        write:$LI(infolist,5)'="" !, "      Level name: ",$LI(infolist,5)
        write:$LI(infolist,6)'="" !, "      Member key: ",$LI(infolist,6)
        set i=$ORDER( ^||DeepSee.AxisMembers(rowkey,2,row,i) )
    }
    Kill ^||DeepSee.AxisMembers(columnkey)
    Kill ^||DeepSee.AxisMembers(rowkey)
}

以下は、このメソッドの出力例です。

 
Result set for comparison
                           0 to 29           30 to 59                60+
 1 Female->None                 189                184                 62
 2 Female->asthma                18                  7                  7
 3 Female->CHD                    *                  4                 14
 4 Female->diabetes               *                 11                 23
 5 Female->osteopor               *                  *                 23
 6 Male->None                   178                186                 45
 7 Male->asthma                  14                  7                  2
 8 Male->CHD                      *                  5                 15
 9 Male->diabetes                 *                 11                 10
10 Male->osteoporos               *                  *                  3
 
We are looking at the cell (2,6)
The value in this cell is 186
For this cell, the column is a tuple that combines the following member(s):
   Member 0
      Dimension name: AgeD
      Hierarchy name: H1
      Level name: Age Group
      Member key: 30 to 59
For this cell, the row is a tuple that combines the following member(s):
   Member 0
      Dimension name: GenD
      Hierarchy name: H1
      Level name: Gender
      Member key: Male
   Member 1
      Dimension name: DiagD
      Hierarchy name: H1
      Level name: Diagnoses
      Member key: <null>

DRILLTHROUGH クエリのクエリ結果の検証

クエリで MDX DRILLTHROUGH 文を使用する場合は、別の方法を使用して結果を検証します。

この場合、%DeepSee.ResultSetOpens in a new tab のインスタンスの以下のメソッドを使用します。

method %GetListingResultSet(Output pRS As %SQL.StatementResult, Output pFieldList As %List) as %Status

このメソッドは、以下の出力パラメータを返します。

  • pRS は、DRILLTHROUGH クエリからの結果を含む %SQL.StatementResultOpens in a new tab のインスタンスです。

  • pFieldList は、この結果セット内のフィールドの ($LIST 形式の) 一覧です。

pRS は、%SQL.StatementResultOpens in a new tab の他のインスタンスを使用する場合と同じ方法で使用します。詳細は、クラスリファレンスを参照してください。

クエリ・メタデータの検証

%DeepSee.ResultSetOpens in a new tab のインスタンスのキューブ名やクエリ・テキストなどのメタデータを取得するには、以下のメソッドを使用します (クエリ・プランへのアクセスの詳細は、次のセクションを参照してください)。

%GetCubeName()
method %GetCubeName() as %String

クエリで使用するキューブの名前を返します。このメソッドを使用する前に、クエリを準備する必要があります。

%GetListingSQL()
method %GetListingSQL() as %String

クエリが DRILLTHROUGH クエリである場合は、ソース・データの表示に使用される SQL 文を返します。

%GetParameterInfo()
method %GetParameterInfo(Output pParms) as %Status

クエリで使用されるパラメータを含む多次元配列を、パラメータに使用される値と共に返します。この配列は、この章で前述した構造を持ちます。

%GetQueryText()
method %GetQueryText() as %String

結果セットの作成時に使用された MDX クエリを含む文字列を返します。

%GetSlicerForCellRange()
method %GetSlicerForCellRange(Output pSlicer As %String, 
                              pStartRow As %Integer, pStartCol As %Integer, 
                              pEndRow As %Integer, pEndCol As %Integer) 
                              as %Status

指定されたセルの範囲の MDX スライサ文を含む文字列を、参照によって返します。セルの範囲を指定するには、開始の行と列および終了の行と列から成る矩形を指定します。いずれの軸でも、最初のセルの位置は 1 です。

%IsDrillThrough()
method %IsDrillThrough() as %Boolean

クエリが DRILLTHROUGH クエリである場合は True を、それ以外の場合は False を返します。

例えば、以下のメソッドは基本のメタデータに関するレポートを生成します。

ClassMethod ShowQueryMetadata(rset As %DeepSee.ResultSet) As %Status
{
    Set cubename=rset.%GetCubeName()
    Write !, "This result set comes from the following cube: ",cubename,!
    
    Set status=rset.%GetParameterInfo(.pParms)
    If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit status}
    If $DATA(pParms) {
        Write "The query uses the following parameters:",!
        Set p = $ORDER(pParms(""))
            While (p '= "") {
                Write $$$UPPER(p), " = " ,$GET(pParms(p,"VALUE")),!
                Set p = $ORDER(pParms(p))
        }
    }
    Set query=rset.%GetQueryText()
    Write "The query is as follows:",!, query,!

    Set isdrill=rset.%IsDrillThrough()
    If isdrill {
        Set listingsql=rset.%GetListingSQL()
        Write !!, "It uses the following SQL to drill into the source table:"
        Write !, listingsql
        }
}

以下の例は、いくつかの結果セットのサンプルを使用して、このメソッドからの出力を示しています (見やすくするために改行が追加されています)。最初の例では、DeepSee.APISamplesOpens in a new tabGetResultSet1() を使用します。

SAMPLES>set rs1=##class(DeepSee.APISamples).GetResultSet1()
 
SAMPLES>d ##class(DeepSee.APISamples).ShowQueryMetadata(rs1)
 
This result set comes from the following cube: patients
The query is as follows:
SELECT {[MEASURES].[AVG TEST SCORE],[MEASURES].[%COUNT]} ON 0,
[DIAGD].[H1].[DIAGNOSES].MEMBERS ON 1 FROM [PATIENTS]

次の例では、名前付きパラメータを含むクエリを使用する GetResultSet2() を使用します。

SAMPLES>set rs2=##class(DeepSee.APISamples).GetResultSet2()
 
SAMPLES>d ##class(DeepSee.APISamples).ShowQueryMetadata(rs2)
 
This result set comes from the following cube: patients
The query uses the following parameters:
C = Magnolia
The query is as follows:
SELECT [HOMED].[H1].[CITY].MAGNOLIA ON 0,%SEARCH ON 1 FROM [PATIENTS]

次の例では、ドリルスルーを行うクエリを使用する GetResultSet3() を使用します。

SAMPLES>set rs3=##class(DeepSee.APISamples).GetResultSet3()
 
SAMPLES>d ##class(DeepSee.APISamples).ShowQueryMetadata(rs3)
 
This result set comes from the following cube: patients
The query is as follows:
DRILLTHROUGH SELECT [GEND].[H1].[GENDER].[FEMALE] ON 0,[BIRTHD].[H1].[YEAR].[1913] ON 1 
FROM [PATIENTS] RETURN  PatientID, PrimaryCarePhysician-> LastName
 
 
It uses the following SQL to drill into the source table:
SELECT TOP 1000 PatientID,PrimaryCarePhysician-> LastName FROM 
DeepSee_Study.Patient source WHERE source.%ID IN (SELECT _DSsourceId FROM 
DeepSee_Model_PatientsCube.Listing WHERE _DSqueryKey = '1858160995')

以下のメソッドの例は、指定の結果セット内で指定のセルの範囲の MDX スライサを示すレポートを生成します。

ClassMethod ShowSlicerStatement(rset As %DeepSee.ResultSet, Row1 As %Integer = 1, 
Col1 As %Integer = 1, Row2 As %Integer, Col2 As %Integer) As %Status
{
    If '$DATA(Row2) {Set Row2=Row1}
    If '$DATA(Col2) {Set Col2=Col1}

    Set status=rset.%GetSlicerForCellRange(.slicer,Row1,Col1,Row2,Col2)
    If $$$ISERR(status) {Do $System.Status.DisplayError(status) Quit status}
    
    Write !, "The requested cell range:"
    Write !, "   Columns ",Col1, " through ", Col2
    Write !, "   Rows    ",Row1, " through ", Row2

    Write !, "The slicer statement for the given cell range is as follows:"
    Write !, slicer
    
    If 'rset.%IsDrillThrough(){
        Write !!, "For comparison, the query results are as follows:",!
        Do rset.%Print()
    }
    Else {
           Write !!, "This is a drillthrough query and %Print "
            _"does not provide a useful basis of comparison"
           }
}

このメソッドを試すには、DeepSee.APISamplesOpens in a new tabGetResultSet4() を使用します。このメソッドでは、以下のように行と列に異なるレベルを持つクエリを使用します。

SAMPLES>d ##class(DeepSee.APISamples).ShowSlicerStatement(rs4)
 
The requested cell range:
   Columns 1 through 1
   Rows    1 through 1
The slicer statement for the given cell range is as follows:
CROSSJOIN({[AgeD].[H1].[Age Bucket].&[0 to 9]},{[GenD].[H1].[Gender].&[Female]})
 
For comparison, the query results are as follows:
                              Female                 Male
1 0 to 9                          689                  724
2 10 to 19                        672                  722
3 20 to 29                        654                  699
4 30 to 39                        837                  778
5 40 to 49                        742                  788
6 50 to 59                        551                  515
7 60 to 69                        384                  322
8 70 to 79                        338                  268
9 80+                             204                  113

その他のメソッド

%DeepSee.ResultSetOpens in a new tab クラスでは、以下のような追加のメソッドも提供されています。

  • %GetCellCount()

  • %FormatNumber()

  • %GetOrdinalLabel()

  • %GetOrdinalKey()

  • %GetQueryKey()

  • %GetRowTotal()

  • %GetColumnTotal()

  • %GetGrandTotal()

全リストと詳細については、クラスリファレンスを参照してください。

クエリ・ファイルの実行

DeepSee には、ファイルに保存されている MDX クエリを実行するためのツールが用意されています。出力は、現在のデバイスに書き込むことも、ファイルに書き込むこともできます。出力結果には、クエリの実行に関する統計が含まれます。

このツールは簡単なテストで役立ちます。

クエリ・ファイルについて

クエリ・ファイルは、以下のような ASCII ファイルである必要があります。

  • ファイル内の改行は無視されます。

  • 行内の 2 つ以上の空白は、1 つの空白として処理されます。

  • ファイルには、任意の数 (0 個以上) の MDX クエリを含めることができます。

  • クエリにはコメントを含めることができますが、コメントを入れ子にすることはできません。MDX コメントの形式は以下のとおりです。

    /* comment here */
    

    コメントは独自の行に配置される場合とそうでない場合があります。

  • 行で GO コマンドを単独で使用して、クエリを実行します。クエリは、前の GO コマンド (またはファイルの先頭) から指定した GO コマンドまで (ただし、この GO コマンドを除く) のすべてのテキストで構成されます。

    その行の GO コマンドの前にスペースを入れないでください。

以下はその例です。

/* First query in this file*/
SELECT MEASURES.%COUNT ON 0, 
homed.[home zip].[34577].CHILDREN 
ON 1 FROM patients
GO


/* Second query in the file*/
SELECT MEASURES.%COUNT ON 0, 
homed.[home city].MEMBERS ON 1 /*ignore this comment*/FROM patients
GO




クエリ・ファイルの実行

クエリ・ファイルを実行するには、%DeepSee.ShellOpens in a new tab の以下のクラス・メソッドを使用します。

ClassMethod %RunQueryFile(pQueryFile As %String, pResultFile As %String = "") As %Status

以下は、この指定の説明です。

  • pQueryFile は、クエリ・ファイルの名前です。

  • pResultFile は、クエリ統計の書き込み先のファイルの名前です。

    この引数が NULL の場合、メソッドは現在のデバイスにクエリ統計を書き込みます。

いずれの場合でも、メソッドは現在のデバイスにクエリ結果を書き込みます。

以下はその例です。

d ##class(%DeepSee.Shell).%RunQueryFile("c:\mdxtest.txt")
------------------------------------------------------
Query 1:
/* First query in this file*/SELECT MEASURES.%COUNT ON 0, homed.[home zip].[34577].CHILDREN ON 1 FROM patients
                                     Count
1 Cypress                             1,091
2 Magnolia                            1,087
3 Pine                                1,121
Query Statistics:
 Results Cache:                        1
 Computations:                         0
 Cache Hits:                           0
 Cells:                                0
 Expressions:                          0
 
 Prepare:                          0.261 ms
 Execute Axes:                     0.026 ms
 Execute Cells:                    0.000 ms
 Consolidate:                      0.000 ms
 Total Time:                       0.287 ms
 
ResultSet Statistics:
 Cells:                                3
 Parse:                            3.553 ms
 Display:                          0.361 ms
 Total Time:                       3.914 ms
------------------------------------------------------
Query 2:
/* Query 2*/SELECT MEASURES.%COUNT ON 0, homed.[home city].MEMBERS ON 1 /*ignore this comment*/FROM patients
                                     Count
1 Cedar Falls                         1,119
...

クエリ統計の詳細は、このドキュメントで後述する “DeepSee クエリ・エンジンの仕組み” を参照してください。

FeedbackOpens in a new tab