Building the Cube Programmatically

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(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

Where:

• pCubeName is the logical name of the cube as given in its XData block; this is not case-sensitive.

• pAsync controls whether the system performs the build in multiple background processes. If this argument is true, the system uses multiple processes 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, the system ignores the value of pAsync and uses a single process to build the cube. These options are described in Specifying Cube Options.

  Caution:

  Custom code for build processes must not invoke HALT. Terminating a DeepSee agent may cause a cascade of lower priority agent terminations and result in the build hanging due to a lack of available agents for new tasks.

• pVerbose controls whether the method writes status information. If this argument is 1, the system writes status updates to the command line. (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 in the fact table. This determines the number of rows of the base table that the system uses when building the cube.

  If pMaxFacts is 0, the default, all rows of the base table are processed.

• pTracking is for internal use.

• pBuildStatistics returns an array of information about the cube build. This array has the following nodes:

  Node	Value
  pBuildStatistics(“elapsedTime”)	Elapsed build time, in seconds.
  pBuildStatistics(“errors”)	Number of build errors.
  pBuildStatistics(“factCount”)	Number of facts that were built and indexed.
  pBuildStatistics(“missingReferences”)	Number of missing references.
  pBuildStatistics(“expressionTime”)	Time spent processing sourceExpressions to build the cube elements.
  pBuildStatistics(“iKnowTime”)	Time spent building NLP indexes.

• pFactList is a list of specific Property names in the cube's fact class. If pFactList is supplied, the build will only update the columns listed in that fact list. This list can have either comma-delimited or $LB format. The specific facts being updated will be individually marked as unavailable for queries and queries referencing dimensions based on those facts will throw an error on prepare.

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 process

• 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: 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.