Its been a long standing bug-bear of mine that there’s no easy way in Excel of knowing that a default member has been set for an attribute, but this is entirely different and much more serious

Consider a simple cube with the below dimensions. The salient point from the cube design is:

• Random Measure – defaults to Daily Sales
  
• Biz Date – defaults to 2011-08-25

The data in the cube is summarily represented below. The yellow bars represent the default members

Now, I want to use this new cube to do Sales reporting by aggregating sales over days. You’ve just done away with the several-hour database queries and are excited about your new cube and the fact that it can do the calculations which used to take hours in a matter of seconds. You’re also excited about the ability for new reports to be generated without the need for IT involvement or testing so business users can ‘self serve’.

Now, I am asked for the total sales across all stores for 24-Aug and 25-Aug.

I do this by setting the below in my Excel

• Biz Date – {2011-08-25, 2011-08-24}
• Risk Measure – { Daily Sales }
• Store – {all}

Now, I pull in my Value and see that the answer is 13.

I send this off pleased with myself that I’ve managed to answer their query in minutes instead of days. Such a simple query, what could possibly go wrong? I’m then asked to break the sales down by both Date and Store for a more granular report.

Now I’m confused – the total is apparently 21, but according to my initial report, it was 13. This is because 13 is reflective of the default member values only – so in this case it is the value for 25-Aug.

Inconsistent behaviours

The situation is made worse because the behaviour is inconsistent and depends entirely on how the query is written

Using Excel and not selecting default members

If you don’t select the default member, you get the correct sum. Look at the below example

Biz Date – {2011-08-24, 2011-08-23}
Risk Measure – { Daily Sales }
Store – {all}

Semantical nuances

How you write your MDX affects the results you get. If you write the below query you get the correct results back.

Excel, unfortunately, generates nested select statements. The actual query generated is below. Its as if the red box is ignored.

A different query, but still keeping with a sub-select similarly ignores the red box.

Summary

This issue will only affect you if you set default members in your dimensions and write queries using sub-selects. If you leave everything defaulted to the ‘all’ member, you can continue blissfully unaware. It may sound obvious, but if you are using defaulted members in your dimensions, make sure you test your output thoroughly.

This is going to be documented on the Microsoft Knowledgebase soon as a KB article, but that’s akin to a health warning on medication.

Acknowledgements

Sanjay Nayyar and Christian Bracchi from IMGROUP for helping identify this issue

While writing the tool, I realized as I’m sure many of you reading this have, that there is little to no documentation on using AMO and its usage is a voyage of discovery. Hindsight being a wonderful tool, it was usually easier to use BIDS and SSMS to do the task, capture the XMLA using profiler and reverse engineer the AMO code from the XMLA by mapping XMLA tags to properties in AMO.

With AMO, to do basic things such as connect to a cube or processAdd a dimension is relatively simple. If, however, you want to do something more complex, you’re on your own and you have a world of unintelligible error messages ahead of you.

Getting started with AMO

Here is some basic code to get you started using AMO. Note that error trapping has been removed for readability.

Tip: In your programs, I suggest you use AMO as a reference so when you come across reserved words such as ‘Action’, you don’t have any confusion with Microsoft.AnalysisServices.Action and System.Action. This also makes the code more readable. In C#, this is done as below.

using AMO = Microsoft.AnalysisServices;

AMO.Server server = new AMO.Server();
server.Connect(<server>);

// Pick your poison:
// "FindByName" uses 'Name' as the method description implies
// "Find" uses 'ID' – which ID you need to know in advance
AMO.Database database = server.Databases.FindByName("<database Name>");
AMO.Database databaseByID   = server.Databases.Find("<database ID>");

AMO.Cube cube = database.Cubes.FindByName("<cube name>");

If you are using AMO to configure / process a cube, it’s a reasonably safe assumption that you’re familiar with BIDS and SSMS. If you’re not, I suggest you get familiar with them before attempting to use AMO as the AMO Object Model is very similar to both BIDS and SSMS. Thus, for example to access a dimension, you use AMO.Database to access it

AMO.Dimension dim =  database.Dimensions.FindByName("<dimension Name>");

If you script out the Adventure Works database, you will see that the Dimension ID and Dimension NAME fields are the same across all Dimensions. This is important because it masks an annoying feature of AMO/SSAS. Specifically, what happens if you rename a Dimension, or if you add it to the Cube and rename it afterwards. It may sound obvious, but the key to successful AMO usage is to know what you need and use the XMLA to make sure you’re asking for what you think you’re asking for

Dimension XMLA

Cube Dimension XMLA

This may not represent the reality of your organisation as the above have never been renamed and are hence identical. Your dimensions may have been renamed several times. If that is the case, the above ID/Name combinations will be inconsistent

For example,

- Create a Named Query called NewNameQuery1 in the DataSourceView
- Create a New Dimension called NewDimension1 referencing NewNameQuery1

- Save the Dimension

- Rename NewDimension1 to NewDimension2
impact: ID will be NewDimension1 forever, Name is now NewDimension2

- Add a CubeDimension referencing NewDimension2
impact: CubeDimension.ID will be NewDimension2 forever, CubeDimension.Name is now NewDimension2

- Rename CubeDimension.Name to NewCubeDimension3
impact: CubeDimension.ID is still NewDimension2, CubeDimension.Name is now NewCubeDimension3

If you look in the Cube Design Properties for the new Cube Dimension, you will see the below

BIDS representation

XMLA representation

Now, if you want to use AMO to reference the above Dimension/CubeDimension, you must use one of the following

/*
 * The below are all logically equivalent [ cubeDimByID.Equals(cubeDimByName) == true ]
 *  - FIND       uses CubeDimensionID
 *  - FINDBYNAME uses CubeDimensionNAME
 * 
 */
AMO.CubeDimension cubeDimByID   = cube.Dimensions.Find("NewDimension2");
AMO.CubeDimension cubeDimByName = cube.Dimensions.FindByName("NewCubeDimension3");

Boolean truefalse1 = cubeDimByID.Equals(cubeDimByName);

/*
 * The below are all logically equivalent [ dimByID.Equals(dimByCubeDim) && dimByCubeDim.Equals(dimByName) && dimByName.Equals(dimByID) == true ]
 *  - FIND       uses DimensionID whether found through linkage of CubeDimension or directly through knowledge of the DimensionID
 *  - FINDBYNAME uses DimensionNAME
 */
AMO.Dimension dimByID       = database.Dimensions.Find("NewDimension1");
AMO.Dimension dimByCubeDim  = database.Dimensions.Find(cubeDimByID.DimensionID);
AMO.Dimension dimByName     = database.Dimensions.FindByName("NewDimension2");

Boolean truefalse2 = dimByID.Equals(dimByCubeDim) && dimByCubeDim.Equals(dimByName) && dimByName.Equals(dimByID);

When you are using AMO, you will need to be clear whether you need the AMO.MeasureGroupDimension.ID, the AMO.CubeDimension.ID or the AMO.Dimension.ID. The best rule of thumb I have found is to assume it is the AMO.Dimension.ID as a first assumption.

Gotchas with AMO

There are several gotchas to be aware of when using AMO, the two main of which are that error messages are almost non-existent, the more interesting though is that you can get a success return message but no changes actually applied. If you are lucky enough to get an error message, there’s usually no guarantee that it relates to what you were trying to do in the first place and the AMO.AmoException.InnerException is cryptic.

Let’s use some code to look at real examples.

Gotcha #1: not using .validate method

Calling .Validate method prior to calling .Update is strongly recommended, this usually gives more usable information on which to act. For example, consider the below code

Having received the popup and no errors, my Dimension Pete Dimension Name should now exist. However, looking in SSMS - its not there. Note: NewDimension2 is the dimension I created earlier for this blogpost.

This is one frustrating feature of AMO and it will definitely bite you many times. Now consider the slightly modified code below.

Now it makes sense why I don’t see my new Dimension above when just calling Update. I have to fix the problems described in the ValidationErrorCollection before it will appear.

Gotcha #2: not calling .update method in the correct order

This code executes successfully, I get no errors and so I think it has worked. It hasn’t.

In order to get it working, FIRST I must call update on the Dimension itself as that has changed.

Now it works successfully.

The revised code is below. Note: I should have called validate before the AMO.Dimension.Update() too but have omitted it here in the interests of space saving

AMO.Dimension d2 = database.Dimensions.FindByName("Dim Time");

d2.Attributes["Day Number Of Week"].Name = "Day Number Of Week renamed";
d2.Update();

 #region hide-me:
 AMO.ValidationErrorCollection returnedErrors = new AMO.ValidationErrorCollection();

 // First validate the operation
 database.Validate(returnedErrors, true);
 if (returnedErrors.Count > 0)
 {
     #region Error Collection
        String s = "";
        int i = 0;
        foreach (AMO.ValidationError err in returnedErrors)
{
            s = String.Format("{0}{1}:{2}\n", s, ++i, err.FullErrorText);
}
        MessageBox.Show(s);
        #endregion
        throw new CustomException(returnedErrors);
}
#endregion

database.Update();

You must call .Update on all affected objects in the correct order. The order is defined by inheritance…so Children come first, and then Parents. So, in the above example, AMO.Dimension is a child of AMO.Database. Hence the order is to call AMO.Dimension first, and AMO.Database second. If I had included a change to an AMO.DimensionPermission, this is a CHILD of AMO.Dimension and hence the order would be AMO.DimensionPermission, AMO.Dimension, AMO.Database

Summary

AMO is very powerful and useful for administration tasks, but you need to be extremely careful what you write and test it thoroughly.

Once you have got AMO working, what can be done is almost limitless. For example, you can script common tasks – such as

- ProcessUpdate all dimensions
- Hide / Unhide Dimension members
- Change drill through members
- Amend the cube calculation script
- Alter Dimension-Data security in a role.

In the book Microsoft SQL Server 2008 Analysis Services Unleashed, Chapter 34 is a great chapter on using AMO with some real code examples to get you started. Combined with the above, hopefully you’ll be able to create many useful tools using AMO. I’d be very interested to hear how you’ve used AMO to enhance cube administration.

Update: I recently found this website too which is another good source of AMO tips.