Implementing InterSystems Business Intelligence
Using Cube Versions
This appendix describes how to use the cube version feature, which enables you to modify a cube definition, build it, and provide it to users, with only a short disruption of running queries. This appendix discusses the following topics:
This feature requires twice the amount of disk space, per cube. Also, this feature requires editing the cube class in Atelier.
Introduction to the Cube Version Feature
The cube version feature enables you to modify a cube definition, build it, and provide it to users, with only a short disruption of running queries. The feature works as follows:
A given cube definition can have versions.
The system generates a version-specific fact table and dimension tables for each cube version.
At any given time, only one cube version is active. The user interfaces and all generated queries use this version.
To make the newest cube version available, it must be activated
. At this point, the system momentarily blocks any queries from being run and then switches to the newest version.
The following figure shows the overall process:
The cube logical name is redirected automatically to the active cube. The Analyzer and other user interfaces use only the cube logical name and thus see only the active cube. Similarly, if you use methods in %DeepSee.Utils
and you specify the cube logical name without a version number, the system runs the method against the active cube.
When you update the cube version number (in Atelier) and recompile, that creates a pending cube, which you can then build. When you are ready, you use a utility method to activate
the cube, which causes the pending cube to become active and causes the previously active cube to become deprecated.
By default, the activation process automatically deletes the deprecated cube. The cube version feature is not intended to support switching back and forth between versions.
The best practice is to use source control. The cube version feature is not a replacement for source control, but can be helpful in conjunction with it.
If a cube uses the cube version feature, you cannot build
the active version of the cube. That is, the method $SYSTEM.DeepSee.BuildCube()
does not affect the active version; instead an error is returned. The Build
option in the Architect behaves the same way. These actions are blocked because they would disrupt running queries for a long time, and the goal of this feature is to prevent that disruption.
Model Changes Can Break Queries
The cube version feature does not check to ensure that queries that function correctly on the active cube will function correctly on the pending cube. For example, if the pending cube no longer includes a model element that is defined in the active cube, any queries that use that element will not work when you activate the pending cube. It is the customer’s responsibility to identify model changes that could cause disruption and to handle such changes appropriately.
Modifying a Cube to Support Versions
To modify a cube so that it supports the cube version feature (and to create and activate the initial version):
Read this note if you are making a transition to cube versions and
you have existing cubes that do not use this feature and
you do not want any queries to be disrupted.
When you make the transition to cube versions, the process is different for the first
cube version. Specifically, the first cube version should be runtime-compatible with the cube currently in use (the unversioned cube definition). This means that the first cube version should not remove or redefine any measures or levels, compared to the non-versioned cube definition. It can add elements; that has no effect on existing queries.
Add the following parameter to the cube class:
To make this change and the next, it is necessary to use Atelier.
Add the following attribute to the <cube>
element and then save the class:
Compile the class. Within the package generated by the system for this cube, there is now a new subpackage (named Versionversionnum
). For example:
Optionally make changes to the cube definition. Read the important note at the start of this section to decide which changes to make. Save your changes.
Build the cube. This step does not affect any running queries (nor do the preceding steps, provided that you follow the guidelines in the important note at the start of this section).
If you build the cube in the Terminal, the system displays slightly different output, to indicate that it is building a specific cube version. For example:
Building cube [HOLEFOODS:1]
This method displays output like the following:
Pending version for holefoods: 1
Pending version synchronized: HOLEFOODS:1
Queries locked for cube: holefoods
Killing active tasks for cube: holefoods
Cube version activated: HOLEFOODS:1
Removing non-versioned cube data
One step of this method does briefly prevent queries from being executed against the cube; however, it is likely that users would not experience any actual delay.
Now all users see the new version of the cube.
Cube Versions and Relationships
You can use the cube version feature with cubes that define relationships. The rules are as follows:
Details for %ActivatePendingCubeVersion()
ClassMethod %ActivatePendingCubeVersion(pCubeGenericName As %String,
pRemoveDeprecated As %Boolean = 1,
pVerbose As %Boolean = 1) As %Status
is the name of the cube, without version number. This argument is not case-sensitive.
specifies whether the method should also remove the cube version that is now being deprecated. If this argument is 1, the method removes the fact table and its data, dimension tables and their data, any cached data, and any internally used metadata for the cube version that is now being deprecated.
When you use this method for the first time, in the transition from a non-versioned cube, it removes the data stored in the fact table and so on for the non-versioned cube. It does not remove the non-versioned generated classes, which the system needs.
specifies whether to display messages indicating the stage of processing of this method.
If you have not yet activated the first cube version, see the previous section
. When you compile the first
cube version, any changes to the cube would affect running queries, even before you activate the cube. Therefore it is necessary to compile, build, and activate one version of the cube that is runtime-compatible with the non-versioned cube; see the previous section
for what this means.
If you have already modified a cube and created an initial version, use the following process to update the cube:
Make changes to the cube as wanted and save them.
Note that for a live system, you should test these changes on a different system first.
Within the package generated by the system for this cube, there is now another new subpackage with the new version number. For example:
Pending version for holefoods: 2
Pending version synchronized: HOLEFOODS:2
Queries locked for cube: holefoods
Killing active tasks for cube: holefoods
Cube version activated: HOLEFOODS:2
Deprecating previously active version: HOLEFOODS:1
Removing previously active version: HOLEFOODS:1
Within the package generated by the system for this cube, there is now only the subpackage with the new version number. For example:
Now all users see the new cube.
You can define subject areas based on a cube that uses the versioning feature. As with any change in a base cube, when you change a cube version, you must also recompile the subject area so it will function properly.
Specifying the Cube to Work With
When you use cube versions, you have the following options for specifying which cube to work with:
When creating a manual query in the Analyzer or in the MDX Query Tool, you can use either of the following forms of cube name:
The logical cube name. In this case, the query uses the active version of the cube.
In the Analyzer, Cube Manager, and other user interfaces, you can work only with the active version, with the exceptions noted in the previous bullet.
The user interfaces display the cube caption, which contains no information about the version.
Also, when you save changes, the saved data contains only the logical cube name (that is, without the version number), unless you typed a version number into a manual query. By default, definitions of pivot tables and listing groups do not contain version numbers.
In the MDX shell, you can use either the logical cube name or the form cubename:versionnum
. If tracing is enabled in the shell, the shell displays the cube version number.
Building cube [PATIENTS:1]
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: 0.461454s
Source expression time: 0.298187s
Disabling the Cube Version Feature
To disable versions for a given cube:
Save and compile the class.
Optionally delete the cube versions that are no longer needed. Execute the following command in the Terminal:
This method returns an error if you attempt to remove the active version.
From this point on, the cube behaves the same as a non-versioned cube.