キューブのコンパイルとビルド

リコンパイルおよび再構築のタイミング

キューブ・クラスまたはサブジェクト領域クラスに変更を加える場合、その変更を有効にするには、そのクラスをリコンパイルする必要があります。キューブに多数の変更がある場合、その変更を有効にするには、キューブも再構築する必要があります。

以下のテーブルは、変更の後に必要なアクションを示しています。

*現在のサーバ・ロケールによって時間ディメンジョンのメンバの名前が決まります。("ロケールを使用した時間メンバ名の制御" を参照してください。)ロケールを変更した場合は、キューブをリコンパイルおよび再構築する必要があります。

†ディメンジョンまたはレベルを削除してリコンパイルしても、関連付けられているレベル・テーブルおよびインデックスは削除されません。また、キューブの再構築によって、不要になったレベル・テーブルおよびインデックスが削除されることもありません。

キューブのコンパイル

アーキテクトでキューブ・クラスをコンパイルする手順は以下のとおりです。

1. [コンパイル] をクリックします。

   クラスのコンパイルが開始され、進捗状況を示すダイアログ・ボックスが表示されます。

   保存していない変更がある場合は、キューブをコンパイルする前に、システムによって変更が保存されます。

2. [OK] をクリックします。

または、スタジオでキューブ・クラスを開き、他のクラスのコンパイルと同じ方法でこれをコンパイルします。

キューブ・クラスをコンパイルする際には、必要に応じてファクト・テーブルとすべての関連クラスが自動的に生成されます。ファクト・テーブルが既に存在する場合、構造を変更する必要がある場合にのみ、システムによりファクト・テーブルが再生成されます。

このキューブにキャッシュされた結果が存在する場合、これらはシステムにより削除されます。

キューブの構築

キューブの構築という用語は、ファクト・テーブルおよびその他のテーブルへのデータの追加と、このデータへのアクセスに使用されるインデックスの構築の 2 つのタスクを指します。

アーキテクトでキューブの完全構築を実行する手順は以下のとおりです。

1. [ビルド] をクリックします。

   ダイアログ・ボックスが表示されます。

   [ビルド] オプションがグレー表示されていることがあります。その場合は、構築を実行する前にキューブをコンパイルする必要があります。

2. 必要に応じて、[構築する最大レコード数] の値を指定します。

   既定では、システムは、ソース・テーブル内のすべてのレコードの繰り返し処理を行い、同じ数のレコードをファクト・テーブルに構築します。キューブ作成時にこの動作をオーバーライドできます。[構築する最大レコード数] オプションを指定すると、システムはその数のレコードだけを繰り返し処理します。その結果、ファクト・テーブルは小さくなり、システムによる構築時間が短くなります。

   [構築する最大レコード数] フィールドがある数値で初期化されると、キューブ・クラスは既定の動作をオーバーライドします (詳細は、"キューブ・クラスのリファレンス情報" の "<cube>" で maxFacts 属性を参照してください)。この場合、キューブ・クラスで指定された値を使用するか、またはより小さい値を入力できます。

3. ダイアログ・ボックスの [構築オプション] セクションで [すべて構築] を選択します。

4. [ビルド] をクリックします。

   キューブの構築が開始され、その進捗状況が表示されます。構築中、[コンパイル] ボタンは無効になっています (グレー表示)。

   Note:

   構築プロセス中に [閉じる] ボタンをクリックしても、構築プロセスは中断されません。いつでも再度開いて、現在進行中のビルドの現在の状態を確認できます。ダイアログが閉じている間に構築が完了した場合、構築の完了を知らせるためにダイアログが再び表示されます。

5. [完了] をクリックします。

これで、"アナライザの使用法" で説明されているようにキューブの使用が可能になります。

選択的構築の使用

選択的構築機能を使用すると、キューブ全体を再構築することなく、また再構築に伴うダウンタイムが発生することなく、キューブ内の特定の要素を構築できます。例えば、最近、特定のディメンジョンに変更を加えた場合、または 1 つのディメンジョンにのみ影響するソース・データの変更がある場合、選択的ビルドを使用して、そのディメンジョン内の関連するレベルを構築できます。選択的構築を使用して、最近追加されたレベル、メジャー、またはリレーションシップを構築することもできます。

選択的構築を使用して、キューブ内の特定のレベル、メジャー、またはリレーションシップを構築できます。すなわち、選択的構築を使用すると、ファクト・テーブル内の列 (それぞれがレベル、メジャー、またはリレーションシップに対応します) が構築されます。キューブで選択的構築を使用しても、そのキューブの従属キューブを更新する必要はありません。

キューブの定義の要素を他のキューブから継承することがあります。他のキューブから継承したキューブに対して選択的構築が有効になっている場合、継承するキューブはスーパーキューブ定義内の指定された factNumbers を読み取り、factNumbers をサブキューブ定義に適切に割り当てることができます。サブキューブは、スーパーキューブの factNumbers が同じままであるとは想定していないため、自身のすべての factNumbers を再生成します。スーパーキューブには、現在のキューブ内のコンパイル済みの factNumber と競合する factNumber が割り当てられている可能性がありますが、これにより、スーパーキューブでの変更から現在のキューブを保護できます。

プログラムによるキューブのビルド

キューブをプログラムでビルドするには、%DeepSee.UtilsOpens in a new tab クラスの %BuildCube()Opens in a new tab クラス・メソッドを実行します。このメソッドには、以下のシグニチャがあります。

classmethod %BuildCube(pCubeName As %String, pAsync As %Boolean = 1,  pVerbose As %Boolean = 1, 
                        pIndexOnly As %Boolean = 1, pMaxFacts As %Boolean = 0, pTracking As %Boolean = 0, 
                        ByRef pBuildStatistics As %String = "", pFactList As %String) as %Status

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

• pCubeName は、XData ブロックで指定されているキューブの論理名です。この名前は大文字と小文字が区別されません。

• pAsync は、システムが複数のバックグラウンド・プロセスでビルドを実行するかどうかを制御します。この引数が true の場合、システムは複数のプロセスを使用し、それらがすべて完了するまで戻りません。この引数が false の場合、システムは単一のプロセスを使用し、それが完了するまで戻りません。

  Note:

  キューブ・オプションの [初期ビルド順] を指定している場合、システムは pAsync の値を無視し、単一プロセスを使用してキューブをビルドします。これらのオプションについては、"キューブ・オプションの指定" で説明します。

  WARNING:

  

  ビルド・プロセスのカスタム・コードで HALT を呼び出すことはできません。DeepSee エージェントを終了すると、優先度が低いエージェントの終了の連鎖が発生し、新規タスクに使用できるエージェントの不足により、ビルドが停止することがあります。

• pVerbose は、メソッドがステータス情報を書き込むかどうかを制御します。この引数が 1 の場合は、コマンド行に状態の更新が書き込まれます。(この引数は、メソッドが構築エラーやその他のロギング情報を書き込むかどうかに影響しません。)

• pIndexOnly は、メソッドがインデックスのみを更新するかどうかを制御します。この引数が 1 の場合は、システムはファクト・テーブルのインデックスのみを更新します。

• pMaxFacts は、ファクト・テーブルの最大行数を指定します。これによって、キューブの構築時に使用されるベース・テーブルの行数が決まります。

  pMaxFacts が 0 の場合 (既定)、ベース・テーブルのすべての行が処理されます。

• pTracking は内部用です。

• pBuildStatistics は、キューブの構築に関する情報の配列を返します。この配列には以下のノードがあります。

  ノード	値
  pBuildStatistics(“elapsedTime”)	構築の経過時間 (秒単位)。
  pBuildStatistics(“errors”)	構築エラーの数。
  pBuildStatistics(“factCount”)	構築およびインデックス付けされたファクトの数。
  pBuildStatistics(“missingReferences”)	欠落している参照の数。
  pBuildStatistics(“expressionTime”)	キューブ要素を構築する sourceExpressions の処理にかかった時間。
  pBuildStatistics(“iKnowTime”)	NLP インデックスの構築にかかった時間。

• pFactList は、キューブのファクト・クラスの特定のプロパティ名のリストです。pFactList が提供される場合、ビルドではそのファクト・リストに表示されている列のみが更新されます。このリストは、コンマ区切りまたは $LB 形式です。更新中の特定のファクトは、クエリに利用不可と個別にマークされ、これらのファクトに基づいてディメンジョンを参照するクエリを準備すると、エラーが返されます。

このメソッドはステータスを返します。キューブの構築中にエラーが発生した場合は、ステータス・コードにより構築エラーの数が示されます。

以下はその例です。

 set status = ##class(%DeepSee.Utils).%BuildCube("patients")

このメソッドは、以下の情報を示す出力を記述します。

• 使用されるプロセッサの数。

• 構築プロセスに要する経過時間の合計。

• ソース式を評価するために費やした時間の合計 (すべてのプロセッサの総合計)。

以下はその例です。

 
Building cube [patients]
Existing cube deleted.
Fact table built:        1,000 fact(s) (2 core(s) used)
Fact indices built:      1,000 fact(s) (2 core(s) used)
Complete
Elapsed time:                  1.791514s
Source expression time:        0.798949s

Source expression time が大きすぎると考えられる場合は、ソース式ができる限り効率的であることを再検査する必要があります。特に、その式で SQL クエリを使用している場合は、そのクエリが使用するテーブルに適切なインデックスがあることを再度確認してください。

キューブ構築ステータス

進行中の構築がある場合、%BuildStatus()Opens in a new tab メソッドを使用してその進行状況を監視できます。ターミナルで、次のように呼び出します。

  DO ##class(%DeepSee.Utils).%BuildStatus("cubeName")

構築の開始にプログラムを使用した場合でも、アーキテクトを使用した場合でも、%BuildStatus() から構築の進行状況がレポートされます。進行中の構築がない場合、%BuildStatus() は最近の構築のタイムスタンプを表示します ： 進行中の構築はありません。最後の構築は 06/23/2020 11:31:07 に終了しました。

プログラムで開始された構築の進行状況は、アーキテクトの構築ダイアログからもレポートされます。

開発におけるキューブ・サイズの最小化

キューブの開発時は、一般にリコンパイルと再構築を頻繁に行います。大量のデータ・セットを使用している場合は、キューブをより迅速に再構築するため、ファクト・テーブル内のファクト数を制限することがあります。これを行うには、以下のいずれかを実行します。

• アーキテクトでキューブを構築する場合は、[構築する最大レコード数] の値を指定します。

• スタジオでキューブ・クラスを編集して、maxFacts 属性を <cube> 要素に追加します。"キューブ・クラスのリファレンス情報" を参照してください。

  これを実行する場合は、この属性を導入前に確実に削除してください。

• ターミナルでキューブを構築して、pMaxFacts 引数を指定します。このページで前述の "プログラムによるキューブのビルド" を参照してください。

選択的構築時は、これらのオプションはすべて無視されます。

キューブの構築時の並行処理の使用法

以下のすべての項目が該当する場合、システムはビルドの実行に複数のコアを使用します。

• キューブの構築時に pAsync を 1 に指定している ("プログラムによるキューブのビルド" を参照)。

• キューブのソースが永続クラスである (データ・コネクタではない)。データ・コネクタについては、"InterSystems Business Intelligence の実装" で説明しています。

• 永続クラスがビットマットに適している。

• キューブの [初期ビルド順] オプションが設定されていない。これらのオプションについては、"キューブ・オプションの指定" で説明します。

キューブを非同期的に構築するときに、並列処理が使用できる場合、その作業を実行するために、システムによって %SYSTEM.WorkMgrOpens in a new tab エージェントが設定されます。

まれに、これらのエージェントのリセットが必要になることがあります。この操作には、%DeepSee.UtilsOpens in a new tab の %Reset()Opens in a new tab メソッドを使用します。また、このメソッドは、保留中のタスクを消去して、現在のネームスペースの結果キャッシュを消去します。これらは、すべてのユーザに直ちに影響を与えます。このメソッドは、開発時にのみ使用するように意図されています。

構築エラー

キューブの構築の際は、表示されるエラー・メッセージ、および構築されるファクトとインデックスの数に注意してください。このセクションでは、以下の項目について説明します。

• 構築エラーを確認できる場所

• ファクト数 (全シナリオの構築に関する問題の役立つインジケータ)

• 考えられる構築エラーの原因

• 構築エラーから回復する方法

トラブルシューティング・オプションの詳細は、InterSystems Developer CommunityOpens in a new tab を参照してください。

考えられる構築エラーの原因

構築エラーやファクト数の原因不明の不一致が存在する場合は、以下の手順を実行します。

1. 範囲式を使用するすべてのレベルを調べ、これらのレベルでレコードが削除されていないことを検証します。"レベルの検証" を参照してください。

   この種のエラーは、インデックス数に影響しますが、ファクト数には影響しません。

2. 選択したディメンジョンまたはメジャーを無効にします。その後、リコンパイルおよび再構築を行い、問題が発生するディメンジョンまたはメジャーを隔離します。

<STORE> エラー

構築ログに、以下のようなエラーが記載される場合があります。

ERROR #5002: ObjectScript error: <STORE>%ConstructIndices+44^Cube.cube_name.Fact.1

このエラーは、レベルに非常に大量のメンバが存在する場合に発生します。既定では、システムはインデックスを構築する際、ローカル・メモリを使用してインデックスをチャンクで格納し、その後それらをディスクに書き込みます。レベルに非常に大量のメンバが含まれる場合は、ローカル・メモリが不足し、<STORE> エラーが発生することがあります。

このようなエラーを回避するには、以下のいずれかの操作を実行します。

• キューブを単一のプロセスで構築する。そのためには、ターミナルで %BuildCube() を使用し、2 番目の引数に 0 を使用します。

• <cube> 要素で、bitmapChunkInMemory="false" (既定) を指定する。バックグラウンド・プロセスを使用してこのキューブを構築すると、ローカル変数ではなくプロセス・プライベート・グローバルが使用されます (ローカル・メモリによる制限がなくなります)。

参照の欠落エラー

キューブが他のキューブへのリレーションシップを持つ場合、構築ログに、以下のようなエラーが記載される場合があります。

ERROR #5001: Missing relationship reference in RelatedCubes/Patients: source ID 1 missing reference to RxHomeCity 4

このエラーは、キューブが間違った順序で構築されていることを示す可能性があります。"InterSystems Business Intelligence の上級モデリング" の "リレーションシップを持つキューブの構築" を参照してください。キューブ・マネージャを使用する場合、キューブ・マネージャが適切な構築順序を決定することに注意してください。

missing relationship reference エラーは、キューブの構築プロセス中に新しいソース・データが使用可能になる場合、つまり既にキューブのいくつかが構築された後にも発生する可能性があります。例えば、サンプル・キューブ RelatedCubes/Cities と RelatedCubes/Patients について考えてみましょう (これらは SAMPLES ネームスペースで使用可能です)。キューブ RelatedCubes/Cities を構築した後、RelatedCubes/Patients のソース・テーブルが、新しい都市を使用するレコードを受け取るとします。この場合、キューブ RelatedCubes/Patients を構築すると、missing relationship reference エラーが発生します。

キューブを正しい順序で構築したことが確実である場合、エラーからの回復の詳細について、次のセクションを参照してください。

Business Intelligence タスク・ログ

システムは、(前述した構築ログ以外に) 他のログ・ファイルも生成します。キューブの構築後またはキューブの構築を試行後、DeepSeeTasks_NAMESPACE.log ファイルもディレクトリ install-dir/mgr に書き込まれます。%DeepSee.WorkMgrOpens in a new tab クラスの %SetLoggingOptions メソッドを使用して、構築プロセス中にシステムが使用したバックグラウンド・エージェントのログを有効にすることができます。それには、以下のような呼び出しを行います。

do ##class(%DeepSee.WorkMgr).%SetLoggingOptions(,,1)

このファイルを管理ポータルから参照するには、[Analytics] > [管理] > [ログ] の順に選択します。

このファイルのタイム・スタンプではローカルの日時を使用します (サマータイムは考慮されます)。