InterSystems IRIS Data Platform 2019.2  /  Defining Models for InterSystems IRIS Business Intelligence

Defining Models for InterSystems IRIS Business Intelligence
Compiling and Building Cubes
Previous section           Next section
InterSystems: The power behind what matters   

This chapter describes how to compile and build cubes. It includes the following topics:
During the build process, users cannot execute queries. (However, if a query is currently running, you can build the cube.)
See Implementing InterSystems Business Intelligence for the following related topics:
Also see “Accessing the Samples Shown in This Book,” in the first chapter.
When to Recompile and Rebuild
If you make any change to a cube class or a subject area class, you must recompile that class before those changes take effect. For many changes to a cube, you must also rebuild the cube before those changes take effect.
The following table lists the required actions after changes:
Element Type Type of Change Required Actions
Cube (root element) Edits to Name or Source class Recompile and rebuild
Other changes that apply to the cube but not to specific elements in the cube Recompile
Measure Edits to the following options of an existing measure (many other elements have some or all of these common options).
  • Disabled
  • Hidden
  • Display name
  • Description
  • Format string
All other changes, including adding and deleting measures Recompile and rebuild
Dimension (not a computed dimension) Edits to the following options of an existing dimension: Recompile
All other changes, including adding and deleting dimensions Recompile and rebuild
Computed dimension All changes Recompile
NLP dimension All changes Recompile
Hierarchy Edits to the common options of an existing hierarchy (as listed in “Measure”) Recompile
All other changes, including adding and deleting hierarchies Recompile and rebuild
Level Edits to the following options of an existing level: Recompile
All other changes, including adding and deleting levels* Recompile and rebuild
Property Edits to the following options of an existing property: Recompile
All other changes, including adding and deleting properties Recompile and rebuild
Listing All changes Recompile
Calculated member All changes Recompile
Named set All changes Recompile
Subject area All changes Recompile
Compound cube (a kind of subject area) All changes Recompile (after recompiling all cubes used in the compound cube)
Quality measure All changes Recompile the quality measure class
KPI or plug-in All changes Recompile the KPI or plug-in class
*The current server locale determines the names of members of a time dimension. (See “Using the Locale to Control the Names of Time Members,” later in this book.) If you change the locale, it is necessary to recompile and rebuild the cube.
Compiling a Cube
To compile a cube class in the Architect:
  1. Click Compile.
    The system starts to compile the class and displays a dialog box that shows progress.
    If you have made changes that you have not yet saved, the system saves them before compiling the cube.
  2. Click OK.
Or open the cube class in Studio and compile it in the same way that you compile other classes.
When you compile a cube class, the system automatically generates the fact table and all related classes if needed. If the fact table already exists, the system regenerates it only if it is necessary to make a structural change.
If there are any cached results for this cube, the system purges them.
Building a Cube
The phrase building a cube refers to two tasks: adding data to the fact table and other tables and building the indices used to access this data.
To build a cube in the Architect:
  1. Click Build.
    The system displays a dialog box.
  2. Optionally specify a value for Maximum Number of Records to Build.
    By default, the system iterates through all records in the source table and builds the same number of records to the fact table. You can override this behavior when you build the cube. If you specify the Maximum Number of Records to Build option, the system iterates through only that number of records. The result is a smaller fact table that the system builds more quickly.
    If the Maximum Number of Records to Build field is initialized with a number, that means that the cube class overrides the default behavior. (For details, see the maxFacts attribute for <cube> in the appendix “Reference Information for Cube Classes.”) In this case, you can either use the value provided by the cube class or enter a smaller value.
  3. Click Build.
    The system starts to build the cube and displays progress as it does so.
  4. Click Done.
The cube is then available for use as described in Using the Analyzer.
Building the Cube Programmatically
To build the cube programmatically, execute the %BuildCube() class method of the %DeepSee.Utils class. This method has the following signature:
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 = "") as %Status
This method returns a status. If errors occur during the cube build, the status code indicates the number of build errors.
For example:
 set status = ##class(%DeepSee.Utils).%BuildCube("patients")
This method writes output that indicates the following information:
For example:
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)
Elapsed time:                  1.791514s
Source expression time:        0.798949s
If Source expression time seems too high, you should re-examine your source expressions to be sure that they are as efficient as possible; in particular, if the expressions use SQL queries, double-check that you have the appropriate indices on the tables that the queries use.
Minimizing Cube Size During Development
While you are developing a cube, you typically recompile and rebuild it frequently. If you are using a large data set, you might want to limit the number of facts in the fact table, in order to force the cube to be rebuilt more quickly. To do this, do one of the following:
Using Parallel Processing During a Cube Build
If all the following items are true, the system uses multiple cores to perform the build:
When you build a cube asynchronously, the system sets up %SYSTEM.WorkMgr agents to do the work, if it is possible to use parallel processing.
These agents are also used to execute queries.
On rare occasions, you might need to reset these agents. To do so, use the %Reset() method of %DeepSee.Utils. This method also clears any pending tasks and clears the result cache for the current namespace, which would have an immediate impact on any users. This method is intended for use only during development.
Build Errors
When you build a cube, pay attention to any error messages and to the number of facts that it builds and indexes. This section discusses the following topics:
For more information on troubleshooting options, see the InterSystems Developer Community.
Seeing Build Errors
When you build a cube in the Architect or in the Terminal, the system indicates if there are any build errors but does not show all of them. To see all the recorded build errors, do either of the following:
In some cases, the system might not generate an error, so it is important to also check the fact count as discussed in the next section.
Checking the Fact Count
When you build a cube, the system reports the number of facts that it builds and indexes.
Each fact is a record in the fact table. The fact table should have the same as the number of records in the base table, except in the following cases:
Also, when the system builds the indices, the index count should equal the number of records in the fact table. For example, the Architect should show the same number for Building facts and for Building indices. If there is a discrepancy between these numbers, check the log files.
Possible Causes of Build Errors
If you see build errors or unexplained discrepancies in the fact count, do the following:
  1. Examine any levels that use range expressions, and verify that these levels do not drop records. See “Validating Your Levels,” later in this book.
    An error of this kind affects the index count but not the fact count.
  2. Try disabling selected dimensions or measures. Then recompile and rebuild to isolate the dimension or measure that is causing the problem.
<STORE> Errors
In some cases, the build log might include errors like the following:
ERROR #5002: ObjectScript error: <STORE>%ConstructIndices+44^Cube.cube_name.Fact.1
This error can occur when a level has a very large number of members. By default, when the system builds the indices, it uses local memory to store the indices in chunks and then write these to disk. If a level has a very large number of members, it is possible to run out of local memory, which causes the <STORE> errors.
To avoid such errors, try either of the following:
Missing Reference Errors
If your cubes have relationships to other cubes, the build log might include errors like the following:
ERROR #5001: Missing relationship reference in RelatedCubes/Patients: source ID 1 missing reference to RxHomeCity 4
This error can mean that you have built the cubes in the wrong order. See “Building Cubes That Have Relationships” in Advanced Modeling for InterSystems Business Intelligence. Note that if you use the Cube Manager, the Cube Manager determines an appropriate build order.
The missing relationship reference error can also occur when new source data becomes available during the cube build process — that is, after only some of the cubes have been built. For example, consider the sample cubes RelatedCubes/Cities and RelatedCubes/Patients (which are available in the SAMPLES namespace). Suppose that you build the cube RelatedCubes/Cities, and after that, the source table for RelatedCubes/Patients receives a record that uses a new city. When you build the cube RelatedCubes/Patients, there will be a missing relationship reference error.
If you are certain that you have built the cubes in the correct order, see the next section for information on recovering from the errors.
Recovering from Build Errors
The system provides a way to rebuild only the records that previously generated build errors, rather than rebuilding the entire cube. To do this:
  1. Correct the issues that cause these errors.
  2. Use the %FixBuildErrors() methods of %DeepSee.Utils, as follows:
    set sc=##class(%DeepSee.Utils).%FixBuildErrors(cubename)
    Where cubename is the logical name of the cube, in quotes. This method accepts a second argument, which specifies whether to display progress messages; for this argument, the default is true.
    For example:
    Fact '100' corrected
    Fact '500' corrected
    Fact '700' corrected
    3 fact(s) corrected for 'patients'
    0 error(s) remaining for 'patients'
    Or rebuild the entire cube.
Business Intelligence Task Log
The system creates an additional log file (apart from the previously described build logs). After it builds the cube or tries to build the cube, the system also writes the DeepSeeTasks_NAMESPACE.log file to the directory install-dir/mgr. You can use the %SetLoggingOptions method of the %DeepSee.WorkMgr class to turn on logging for background agents that the system used during the build process. To do so, make a call like the following:
do ##class(%DeepSee.WorkMgr).%SetLoggingOptions(,,1)
To see this file from the Management Portal, select Analytics > Admin > Logs.
This file also contains information about runtime errors of various kinds such as listing errors and KPI errors.
The time stamps in this files use the local date and time (taking daylight saving time into account).

Previous section           Next section
Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-09-18 06:45:48