Building the Cube Programmatically

To build the cube programmatically, execute the %BuildCube()Opens in a new tab class method of the %DeepSee.UtilsOpens in a new tab class. This method has the following signature:

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

Where:

pCubeList is a comma-separated list which contains the names of the cubes which you want to build. You must provide the logical name of the cube. In the Architect, this is the cube’s Cube Name. In the cube class’s XData block, this is the <cube> element’s Name attribute. A cube’s logical name is not case-sensitive.
%BuildCube() builds the cubes which you specify in pCubeList, as well as any related cubes which depend upon them, determining the correct build order automatically.
pAsync controls whether the system performs the build operation using multiple background processes. If this argument is true, then the system uses multiple processes to build each cube in order wherever possible, and does not return until they are all complete.If this argument is false, the system uses a single process and does not return until it is complete.

Note:

If you have specified the cube option Initial build order for a cube, the system ignores the value of pAsync and uses a single process to build the cube. These options are described in Specifying Cube Options.
If you are using %SetAgentCount to limit the assignment of worker agents to background tasks within a namespace, only one build may be active within that namespace at any given time. Build operations in other namespaces are not affected.
pVerbose controls whether the method writes status information. If this argument is 1, the system writes status updates to the current device. (This argument does not affect whether the method writes build errors or other logging information.)
pIndexOnly controls whether the method only updates the indexes. If this argument is 1, the system only updates the indexes of the fact table.
pMaxFacts specifies the maximum number of rows from the base table that the system should use to populate the fact table when it builds the cube (or cubes).
If pMaxFacts is 0 (the default) the system processes all of the rows in the base table
pTracking is for internal use.
pBuildStatistics returns an array of information about the build operation, by reference. This array contains the following values:
- pBuildStatistics(“elapsedTime”) — the total elapsed build time, in seconds.
- pBuildStatistics(“errors”) — the total number of errors that were encountered while building all the cubes.
- pBuildStatistics(“factCount”) — the total number of facts that were built and indexed across all of the cubes which were built.
- pBuildStatistics(“missingReferences”) — the total number of missing references across all of the cubes which were built.
- pBuildStatistics(“expressionTime”) — the total length of time which was spent processing source expressions to build cube elements across all the cubes which were built.
- pBuildStatistics(“iKnowTime”) — the total length of time which was spent building NLP indexes across all the cubes which were built.
- pBuildStatistics(“cubes”, <cubeName>, <statisticName>) — the value of one of the preceding statistics (identified by <statisticName>) for the build operation on an individual cube (identified by <cubeName>). For example, pBuildStatistics(“cubes”, “PATIENTS”, “factCount”) provides the number of facts that were built and indexed during the building of the PATIENTS cube.
- pBuildStatistics(“cubes”, <cubeName>, “async”) — whether the system used multiple background processes to build the cube identified by <cubeName>. If the system built the cube using a single process (for example, if you have specified an Initial Build Order for the cube), the value is 0.
pFactList is a list of specific Property names which may be found in the fact classes for the specified cube. If pFactList is supplied, the build will only update the columns listed in that fact list. This list can be in either comma-delimited or $LB format. The specific facts being updated will be individually marked as unavailable for queries while the build operation is underway. Queries referencing dimensions based on those facts will throw an error when they are prepared.
Note:

You can only use pFactList when pCubeList identifies one cube as the target of a selective build. If other cubes depend upon the cube that you have targeted, %BuildCube() will synchronize the dependent cubes automatically to reflect the changes to the target.
When you specify a pFactList, you must ensure that each cube that the system will update during the build operation meets the following criteria:
- Selective build is enabled.
- The fact table for the cube contains the columns identified in pFactList.
If any cube in the build operation does not meet the preceding conditions, the build operation fails with an error.

Where supported, the system attempts to synchronize the cubes at the end of the main build procedure.

Upon conclusion, 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:

Number of processors used.
Total elapsed time taken by the build operation.
Total amount of time spent evaluating source expressions, summed across all processors.

For example:

 
Building cube [patients]
Existing cube deleted.
Fact table built:        1,000 fact(s) (2 core(s) used)
Fact indexes built:      1,000 fact(s) (2 core(s) used)
Complete
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 indexes on the tables that the queries use.

Cube Build Status

If there is a build in progress, you can monitor its progress using the %BuildStatus()Opens in a new tab method. In the Terminal, call:

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

%BuildStatus() reports on the progress of a build regardless of whether you initiated the build programmatically or using the Architect. If there is no build in progress, %BuildStatus() displays the timestamp of the most recent build, like so: There is no build in progress. Last build was finished on 06/23/2020 11:31:07.

The build dialog in the Architect also reports on the progress of builds which are initiated programmatically.

Minimizing Cube Size During Development

Using Selective Build