DeepSee Implementation Guide
Using Cube Versions
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Search:    

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 Studio.
Note:
The cube version feature is not supported for a cube that defines a formally shared dimension. It is also not supported for a cube that defines a one-way relationship; it can be used with cubes that define two-way relationships.
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:
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, DeepSee runs the method against the active cube.
When you update the cube version number (in Studio) 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.
Keeping the Cube Current
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.
You can synchronize the cube.
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):
Important:
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.
  1. Add the following parameter to the cube class:
    Parameter USECUBEVERSIONS=1;
    To make this change and the next, it is necessary to use Studio.
  2. Add the following attribute to the <cube> element and then save the class:
    version="versionnum"
    Where versionnum is an integer.
  3. Compile the class. Within the package generated by DeepSee for this cube, there is now a new subpackage (named Versionversionnum). For example:
    In this example, the new package is HoleFoods.Cube.Version1.
    The classes HoleFoods.Cube.Fact, HoleFoods.Cube.Listing, HoleFoods.Cube.Star475620761, and so on existed previously; these were generated for the cube before USECUBEVERSIONS was added. The cube version utilities do not touch these class definitions.
  4. 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.
  5. 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]
  6. In the Terminal, execute the %ActivatePendingCubeVersion() method of the class %DeepSee.CubeVersion.Utils. This method takes one argument, the name of the cube to build (without any version number). For example:
     d ##class(%DeepSee.CubeVersion.Utils).%ActivatePendingCubeVersion("holefoods")
    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.
  7. If you are using the Cube Manager to update this cube, make sure that the update plan for the cube is either Synch Only or Manual. See Keeping the Cube Current.”
Cube Versions and Relationships
You can use the cube version feature with cubes that define relationships. The rules are as follows:
Details for %ActivatePendingCubeVersion()
The %ActivatePendingCubeVersion() method has the following signature:
ClassMethod %ActivatePendingCubeVersion(pCubeGenericName As %String, 
                                        pRemoveDeprecated As %Boolean = 1, 
                                        pVerbose As %Boolean = 1) As %Status
Where:
Updating a Cube Version
Important:
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:
  1. First modify the cube class so that it uses a new version number, in the <cube>element. This precaution prevents any cube changes from being visible too early. (Recall that some cube changes, such as to display names, take effect as soon as you compile a cube. See When to Recompile and Rebuild in Defining DeepSee Models.)
  2. Save the cube class.
  3. 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.
  4. Compile the cube.
    Within the package generated by DeepSee for this cube, there is now another new subpackage with the new version number. For example:
  5. Build the cube.
  6. In the Terminal, execute the %ActivatePendingCubeVersion() method of the class %DeepSee.CubeVersion.Utils. In this case, this method displays output like the following:
     
    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 DeepSee for this cube, there is now only the subpackage with the new version number. For example:
Now all users see the new cube.
Note:
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:
Additional Options
The class %DeepSee.CubeVersion.Utils provides additional methods that you can use for debugging purposes. These include:
For details, see the class reference for %DeepSee.CubeVersion.Utils.
Also, the %BuildCube() of %DeepSee.Utils can return, by reference, the cube name with the active version number. For example:
SAMPLES>set cubename="patients"
 
SAMPLES>set status=##class(%DeepSee.Utils).%BuildCube(.cubename)
 
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)
 
Complete
Elapsed time:                  0.461454s
Source expression time:        0.298187s
 
SAMPLES>w cubename
PATIENTS:1
The method $SYSTEM.DeepSee.BuildCube() does not provide this option.
Disabling the Cube Version Feature
To disable versions for a given cube:
  1. Modify the cube class and specify USECUBEVERSIONS as 0.
  2. Save and compile the class.
  3. Build the cube.
  4. Optionally delete the cube versions that are no longer needed. Execute the following command in the Terminal:
     set status=##class(%DeepSee.CubeVersion.Utils).%RemoveCubeVersion(cubename,version)
    Where cubename is the logical cube name, and versionnum is the version number.
    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.