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 引数を指定します。このページで前述の "プログラムによるキューブのビルド" を参照してください。
選択的構築時は、これらのオプションはすべて無視されます。
構築エラー
キューブの構築の際は、表示されるエラー・メッセージ、および構築されるファクトとインデックスの数に注意してください。このセクションでは、以下の項目について説明します。
トラブルシューティング・オプションの詳細は、InterSystems Developer CommunityOpens in a new tab を参照してください。
構築エラーの確認
アーキテクトまたはターミナルでキューブを構築する際、構築エラーがあるかどうかが示されますが、それらのすべてが表示されるわけではありません。記録された構築エラーをすべて確認するには、以下のいずれかを実行します。
-
ログ・ファイル install-dir/mgr/DeepSeeUpdate_cube_name_NAMESPACE.log を探します。cube_name はキューブ名で、NAMESPACE はこのキューブが定義されているネームスペースです。
このファイルのタイム・スタンプでは $NOW を使用してローカルの日時が記録されます。サマータイムは無視されます。
-
以下のように、%DeepSee.UtilsOpens in a new tab の %PrintBuildErrors()Opens in a new tab メソッドを使用します。
do ##class(%DeepSee.Utils).%PrintBuildErrors(cubename)
cubename はキューブの論理名で、引用符で囲みます。
このメソッドはすべての構築エラーに関する情報を表示します。以下に例を示します (改行が追加されています)。
SAMPLES>do ##class(%DeepSee.Utils).%PrintBuildErrors("holefoods")
1 Source ID: 100000
Time: 05/09/2019 14:12:52
ERROR #5002: ObjectScript error: <DIVIDE>%UpdateFacts+106^HoleFoods.Cube.Fact.1
2 Source ID: 200000
Time: 05/09/2019 14:12:41
ERROR #5002: ObjectScript error: <DIVIDE>%UpdateFacts+106^HoleFoods.Cube.Fact.1
3 Source ID: 300000
Time: 05/09/2019 14:13:13
ERROR #5002: ObjectScript error: <DIVIDE>%UpdateFacts+106^HoleFoods.Cube.Fact.1
...
10 build error(s) for 'holefoods'
Important:
システムによりエラーが生成されない場合もあるため、ファクト数の確認も重要です (次のセクションを参照)。
ファクト数の確認
キューブの構築の際は、構築されるファクトとインデックスの数が報告されます。
各ファクトは、ファクト・テーブル内のレコードです。以下の場合を除き、ファクト・テーブルには、ベース・テーブルと同じ数のレコードが存在します。
また、システムでインデックスが構築されるときには、インデックス数がファクト・テーブルのレコード数と同じになります。例えば、アーキテクトでは [ファクトの構築中] と [インデックス構築中] に同じ数が示されます。これらの数に不一致がある場合は、ログ・ファイルを確認してください。
考えられる構築エラーの原因
構築エラーやファクト数の原因不明の不一致が存在する場合は、以下の手順を実行します。
-
範囲式を使用するすべてのレベルを調べ、これらのレベルでレコードが削除されていないことを検証します。"レベルの検証" を参照してください。
この種のエラーは、インデックス数に影響しますが、ファクト数には影響しません。
-
選択したディメンジョンまたはメジャーを無効にします。その後、リコンパイルおよび再構築を行い、問題が発生するディメンジョンまたはメジャーを隔離します。
<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 エラーが発生します。
キューブを正しい順序で構築したことが確実である場合、エラーからの回復の詳細について、次のセクションを参照してください。
構築エラーからの回復
キューブ全体を再構築するのではなく、以前に構築エラーを生成したレコードのみ再構築する方法が用意されています。以下はその方法です。
-
これらのエラーの原因となる問題を修正します。
-
以下のように、%DeepSee.UtilsOpens in a new tab の %FixBuildErrors()Opens in a new tab メソッドを使用します。
set sc=##class(%DeepSee.Utils).%FixBuildErrors(cubename)
cubename はキューブの論理名で、引用符で囲みます。このメソッドは、進捗状況メッセージを表示するかどうかを指定する 2 番目の引数を受け入れます。この引数の既定値は True です。
例えば以下のように出力されます。
Fact '100' corrected
Fact '500' corrected
Fact '700' corrected
3 fact(s) corrected for 'patients'
0 error(s) remaining for 'patients'
または、キューブ全体を再構築します。
Business Intelligence タスク・ログ
システムは、(前述した構築ログ以外に) 他のログ・ファイルも生成します。キューブの構築後またはキューブの構築を試行後、DeepSeeTasks_NAMESPACE.log ファイルもディレクトリ install-dir/mgr に書き込まれます。%DeepSee.WorkMgrOpens in a new tab クラスの %SetLoggingOptions メソッドを使用して、構築プロセス中にシステムが使用したバックグラウンド・エージェントのログを有効にすることができます。それには、以下のような呼び出しを行います。
do ##class(%DeepSee.WorkMgr).%SetLoggingOptions(,,1)
このファイルを管理ポータルから参照するには、[Analytics] > [管理] > [ログ] の順に選択します。
Tip:
このファイルには、リストのエラーや KPI エラーなど、さまざまな種類の実行時エラーに関する情報も含まれます。
このファイルのタイム・スタンプではローカルの日時を使用します (サマータイムは考慮されます)。