MDX Essentials: String Functions: The .UniqueName Function

Tuesday Sep 6th 2005 by William Pearson
Share:

MSAS Architect Bill Pearson introduces the .UniqueName function. In a hands-on exercise, we create picklist support for report parameterization within MDX queries, among other uses.

About the Series ...

This article is a member of the series, MDX Essentials. The series is designed to provide hands-on application of the fundamentals of the Multidimensional Expressions (MDX) language, with each tutorial progressively adding features designed to meet specific real-world needs.

For more information about the series in general, as well as the software and systems requirements for getting the most out of the lessons included, please see my first article, MDX at First Glance: Introduction to MDX Essentials.

Note: Current updates are assumed for MSSQL Server, MSSQL Server Analysis Services, and the related Books Online and Samples.

Overview

In this lesson, we will examine another function / property in the MDX toolset, the .UniqueName function. The general purpose of the .UniqueName function is to return the Unique Name of the object to which it is appended. .UniqueName can be used in conjunction with hierarchies, dimensions, levels, and members, in a manner similar to the .Name function that we examined in String Functions: The .Name Function, and, also like .Name, .UniqueName can be useful in a host of different applications. As I have noted in other articles, both .UniqueName and .Name allow us to exercise a great deal of presentation sleight of hand, in working with MDX in Analysis Services, as well as within Reporting Services and various other reporting applications that can access an Analysis Services cube.

The .UniqueName function can be leveraged in activities that range from generating simple lists to supporting sophisticated presentations. We will introduce the function, commenting upon its operation and touching upon examples of effects that we can employ it to deliver. As a part of our discussion, we will:

  • Examine the syntax surrounding the function;
  • Undertake illustrative examples of the uses of the function in practice exercises;
  • Briefly discuss the results datasets we obtain in the practice examples.

The .UniqueName Function

Introduction

According to the Analysis Services Books Online, the .UniqueName function "returns the unique name of a specified level, dimension, member, or hierarchy." .UniqueName has many applications, including its use with the Analysis Services objects that are included in the definition, as well as its pairing with other MDX functions to leverage its power even further. As we saw in our examination of the .Name property, I frequently use it with the .CurrentMember function; we will see an example of this combination within the practice exercises to follow.

We will examine the syntax for the .UniqueName function after our customary overview in the Discussion section that follows. Following that, we will conduct practice examples within a couple of scenarios, constructed to support hypothetical business needs that illustrate uses for the function. This will afford us an opportunity to explore some of the presentation options that .UniqueName can offer the knowledgeable user. Hands-on practice with .UniqueName, where we will create expressions that leverage the function, will help us to activate what we learn in the Discussion and Syntax sections.

Discussion

To restate our initial explanation of its operation, the .UniqueName function, when acting upon a level, dimension, member, or hierarchy, returns the Analysis Services Unique Name of the object to which it is appended with the period (".") delimiter. .UniqueName can be used for a great deal more than the support of simple lists of unique object names, as we have intimated. When we couple it with other functions, we can leverage .UniqueName to deliver a wide range of analysis and reporting utility. As in so many cases with the Microsoft integrated business intelligence solution, consisting of MSSQL Server, Analysis Services and Reporting Services, this function, residing within the Analysis Services layer, can be extended to support capabilities and attributes in the Reporting Services layer. Knowing "where to put the intelligence" among the various layers is critical to optimization, in many cases. For more of my observations on this subject, see Multi-Layered Business Intelligence Solutions ... Require Multi-Layered Architects.

The UniqueName function returns the Unique Name of the object (the "fully qualified" name in MDX), not the Name, which is returned via the .Name function. As promised in String Functions: The .Name Function, we will continue an example we begin at the end of our practice session there, as a prelude to a couple of exercises where we use .Name and .UniqueName together to produce a dataset for a specific objective.

Let's look at some syntax illustrations to further clarify the operation of .UniqueName.

Syntax

Syntactically, anytime we employ the .UniqueName function to return the associated Unique Name, the object upon which we seek to apply the .UniqueName function is specified to the left of .UniqueName. The function takes the object to which it is appended as its argument, and returns within a string the Unique Name of the object specified. The general syntax is shown in the following string:

<<Object >>.Name

As we learned to be the case with .Name in String Functions: The .Name Function, putting .UniqueName to work could not be easier. When using the function to return the Unique Name of one of the several objects with which it works, we simply append it to the right of the object under consideration. We can see a syntax example, for each of the objects for which .UniqueName can return a Unique Name, in Table 1 below.

Object

Example of Use:

Hierarchy

[Date].[Calendar Year].UniqueName

Dimension

[Warehouse].UniqueName

Level

[Warehouse].[City].UniqueName

Member

[Warehouse].[City].[Seattle].UniqueName


Table 1: Examples Showing the .UniqueName Function Employed with Different Objects

As an example, the following snippet:

 [Warehouse].[City]. UniqueName

returns [Warehouse].[City], the Unique Name of the Warehouse City level. As another example, the following:

[Warehouse].[City]. [Seattle].UniqueName

returns [Warehouse].[All Warehouses].[USA].[WA].[Seattle], the Unique Name of the Warehouse City level member Seattle. As is probably obvious, the .UniqueName function can be best leveraged by combining it with other functions, particularly "relative" functions, to generate lists of names, and so forth, as we will see in short order. The immediate usefulness is obvious: .UniqueName generates the "MDX name," whose utility within queries pays dividends in picklist generation, among other applications.

NOTE: For more information on several of the "relative" functions, see my article MDX Member Functions: "Relative" Member Functions, within the Database Journal MDX Essentials series.

We will practice some uses of the .UniqueName function in the section that follows.

Practice

Preparation

To reinforce our understanding of the basics we have covered so far, we will use the .UniqueName function in a couple of ways that illustrate its operation. We will do so in simple scenarios that place .UniqueName within the context of meeting business requirements similar to those we might encounter in our respective daily environments. The intent is, of course, to demonstrate the operation of the .Unique Name function in a straightforward, memorable manner.

Let's return to the MDX Sample Application as a platform from which to construct and execute the MDX we examine, and to view the results datasets we obtain.

1.  Start the MDX Sample Application.

2.  Clear the top area (the Query pane) of any queries or remnants that might appear.

3.  Ensure that FoodMart 2000 is selected as the database name in the DB box of the toolbar.

4.  Select the Warehouse cube in the Cube drop-down list box.

Let's assume, for our practice example, that we have received a call from the Reporting department of the FoodMart organization, requesting our assistance in meeting a specific report presentation need. A group of report authors want to display the Names of the US Warehouse Cities, alongside the respective "MDX names" (their term for the qualified names / Unique Names within Analysis Services), to provide an index for a developer who needs the Unique ("MDX") Names for a reporting project he has undertaken.

This represents a simple, yet practical, need that we can readily answer using the .UniqueName function in conjunction with a relative function, .CurrentMember. The solution also includes the .Name function, so our example will also serve as a review of what we covered in String Functions: The .Name Function. We will create a basic query that returns the Warehouse City names for each US City in which we conducted Warehouse operations over the past couple of years (1997 and 1998), along with the Unique Name for each respective US Warehouse City. Some of the Unique Names we generate with the query will ultimately find their way into the Dataset definition of reports that the developer intends to construct within Reporting Services – the "MDX" name for the Warehouse City can be used axes, slicers, and so forth, within queries against the Analysis Services cube under consideration.

Let's construct a simple query, therefore, to return the requested Warehouse City information, presenting the Names and Unique Names in two, side-by-side columns, with the corresponding Warehouse City members as rows.

5.  Type (or cut and paste) the following query into the Query pane:

-- MDX035-01  Using .Name  and .UniqueName to generate a name / unique name 
-- index within the data grid
WITH
MEMBER
     [Measures].[Warehouse USA City]
AS
     '[Warehouse].CurrentMember.NAME'
MEMBER
     [Measures].[Warehouse USA City - MDX]
AS
     '[Warehouse].CurrentMember.UNIQUENAME'
SELECT
     {[Measures].[Warehouse USA City], [Measures].[Warehouse USA City - MDX]} 
         ON COLUMNS,
     {DESCENDANTS([Warehouse].[All Warehouses].[USA], [Warehouse].[City])} 
         ON ROWS
FROM 
     [Warehouse]  

6.  Execute the query by clicking the Run Query button in the toolbar.

The Results pane is populated by Analysis Services, and the dataset shown in Illustration 1 appears.


Illustration 1: Results Dataset – Combined Use of .Name and .UniqueName with .CurrentMember

We see Warehouse City Names, the output of the Warehouse USA City calculated member, populating the first data column, with the respective Warehouse City Unique Names (a "qualified" MDX name that can, itself, be used within a query against the Warehouse cube) for each occupying the second data column. The Warehouse City members themselves occupy the row axis, as we requested.

The calculated members Warehouse USA City and Warehouse USA City – MDX employ the .Name and .UniqueName functions, respectively, in conjunction with the "relative" .CurrentMember function, which, as we can easily see from our practical example, results in a combination list of the Names / qualified names of the members that we specify in our row axis. (Similarly, if we had specified the Warehouse State Province or Warehouse Country levels in the row axis instead, we would have obtained a list of the members of those levels as a result). Intersecting the calculation with the members under consideration can be leveraged, in similar fashion, to produce sophisticated results within more elaborate structures and processes.

7.  Select File -> Save As, name the file MDX035-1, and place it in a meaningful location.

Let's look at an example that expands upon our first, this time to meet a mechanical need within the reporting layer of an integrated BI application. As many of us are aware, enterprise reporting applications typically allow for parameterization (via what are sometimes known as "prompts" or "parameter prompts") to enable information consumers to quickly find the information they need from a report. These parameters, whose values are physically passed to an axis specification or a slicer in the dataset query, often act to put filters into place "on the fly"; these "filters" are thus enacted when the consumer types or selects a value, or a series of values, at run time.

In general, there are two primary types of parameters, type-in and picklist, which can be mechanized through various means. Type-in parameters accept directly typed user input for the value upon which the report is based. An example of input might, for a report based upon an Analysis Services cube, consist of the Unique Name for a given filter, say, for one of the Warehouse Cities in the list we created earlier.

The trouble with type-in parameters is that they are subject to input error, and thus can fail to produce the desired results if they are not precisely correct. This can be particularly cumbersome for information consumers when the report is based upon an Analysis Services cube, because, even with a list like the one we generated above with the Unique Names mapped to the "English" names for various filter selections, the precise MDX qualified name might present a typing challenge for some.

For this reason, the alternative parameter type, the picklist, provides a more user-friendly experience. A picklist presents a selection of choices to a consumer, based upon a static file, a dataset from a larger data source, or through other means. The picklist is often the tool of choice, because of its inherent elimination of typing errors. A well-constructed picklist makes selection easy for the consumer (who is not often pleased with a long scrolling process, or other cumbersome method, as the initial step in generating a commonly requested report). An investment in developing a good picklist often pays great dividends in consumer satisfaction.

The list we have generated above provides virtually all we need to support parameterization within Reporting Services and other enterprise reporting applications. Let's do another example, this time with picklist support the primary objective. We will construct a dataset upon which the picklist selections can be based, and then I will illustrate briefly using this dataset in MSSQL Server Reporting Services.

NOTE: For one hands-on approach (as you will see, they are Legion) to constructing the picklist in Reporting Services, see my article Mastering OLAP Reporting: Cascading Prompts here at Database Journal.

Let's assume, as a background scenario, that the Reporting department with which we worked earlier contacts us to say that they are happy with the "map" we have provided for the developer as outlined in our previous example. Their next request is a common one: they want to provide picklist support within an OLAP report, FoodMart Sales, which they have constructed using MSSQL Server Reporting Services. The data source is the Sales sample cube that accompanies an installation of MSSQL Server Analysis Services (and with which most of us are familiar). The consumers want the selector for the picklist to display the regular Name for the Product Department, the left-most, top level in a drill-down presentation.

While the focus of our article is the MDX required to meet this request, and specifically upon the use of the .UniqueName functions within an MDX query, the dataset that this query generates would be added in Reporting Services' Report Designer, among other steps, to meet the requirement for parameterization within the FoodMart Sales report. Let's create a query to generate the list, and then take a look at how we might use the data returned.

8.  Select File --> New to clear the Query pane for creation of a new query.

9.  Ensure that FoodMart 2000 is selected as the database name in the DB box of the toolbar.

10.  Select the Sales cube in the Cube drop-down list box.

Our initial approach is quite similar to the previous example – it is in the intended end use of the returned data where we do something different. We again have a need that we can readily answer using the .UniqueName function in conjunction with a relative function, .CurrentMember. The requirement also includes the .Name function. We will be targeting the Name column in the resulting dataset (let's call it ProdDept_DisplayName) for the Name that is displayed in the selector for the parameter picklist. The Unique Name column of the returned dataset (the qualified "MDX" name for each Product Department), which we will call ProdDept_UniqueName in the query we will construct, will serve as the value that is actually passed to the cube in the MDX of the query. The happy result is that we insulate report consumers from the MDX altogether, while providing them ad hoc selection of a Product Department upon which to filter the report data.

Our first step is to construct a query to return the requested Product Department list, presenting the Names and Unique Names in two side-by-side columns. The corresponding Product Department members will inhabit the row axis.

11.  Type (or cut and paste) the following query into the Query pane:

-- MDX035-02  Using .Name  and .UniqueName to generate a picklist selection
WITH
MEMBER
     [Measures].[ProdDept_DisplayName]
AS
     '[Product].CurrentMember.NAME'
MEMBER
     [Measures].[ProdDept_UniqueName]
AS
     '[Product].CurrentMember.UNIQUENAME'
SELECT
     {[Measures].[ProdDept_DisplayName], [Measures].[ProdDept_UniqueName]} 
         ON COLUMNS,
     {DESCENDANTS([Product].[All Products], [Product].[Product Department])} 
         ON ROWS
FROM 
     [Sales]  

12.  Execute the query by clicking the Run Query button in the toolbar.

The Results pane is populated by Analysis Services, and the dataset depicted in Illustration 2 appears.


Illustration 2: Results Dataset – AnotherUse of .Name and .UniqueName with .CurrentMember

We see Product Department Names, the output of the ProdDept_DisplayName calculated member, populating the first data column, with the respective Product Department Unique Names (again, the "qualified" MDX name that can be used within a query against the Sales cube) for each occupying the second data column. The Product Department members themselves occupy the row axis, as we requested, although the row axis will not be used in the reporting environment. The calculated members ProdDept_DisplayName and ProdDept_UniqueName employ the .Name and .UniqueName functions, respectively, in conjunction (again) with the "relative" .CurrentMember function, which, as we can easily see from our practical example, results in a combination list of the Names / Qualified Names of the members that we specify in our row axis.

13.  Select File -> Save As, name the file MDX035-2, and place it in a meaningful location.

We will not take the steps, within this article, which occur inside the reporting layer to construct the picklist apparatus. However, let's take a look at one approach to assembling the parts in Reporting Services (or, similarly, in another OLAP reporting application). First, we would transfer the query to Reporting Services' Data tab to generate a Dataset within the FoodMart Sales report. This query, together with the dataset it generates, would look something similar to that which is partially shown in Illustration 3.


Illustration 3: Constructing a Dataset in Reporting Services to Support a Parameter Picklist

NOTE: This is only one approach to creating the Dataset – perhaps the more obvious of several, another of which might be more optimal, depending upon the reporting environment under consideration. Other approaches, the components of which might occupy different layers of the Microsoft integrated business intelligence solution, could include installation of the calculated members at the cube level, and then calling them (versus defining and building) them from the reporting layer.

For a step-by-step procedure that demonstrates the construction of such a cube-based solution to support a picklist in Reporting Services, see Create a Cube-Based Hierarchical Picklist in my MDX in Analysis Services series.

Once we have created the Dataset, the next step is to add a parameter to the report. Inside the Report Parameter definition, we would reference the new Dataset (in the example I created for my illustrations I named it pX_ProductDept), as shown, and then select ProdDept_UniqueName and ProdDept_DisplayName as the Value and Label fields respectively. Illustration 4 presents a view of the way all this would tie together in the Report Parameter dialog inside Reporting Services.


Illustration 4: Pulling It All Together inside the Report Parameter ...

At this point all that remains is to return to the primary Dataset underneath the report and to insert the parameter variable within an axis specification or a slicer, where it acts as a filter (there are examples of this, and all other steps, in the articles I have cited above). Executing the query then triggers the "prompting" action of the new Product Department parameter.

The selection list, displaying the regular Product Department name, is manifested in the parameter dropdown when we preview or execute the report, as partially depicted in Illustration 5.


Illustration 5: The Product Department Parameter Selector in Action ...

14.  Close the MDX Sample Application, as desired.

And so we see that our query, using the .Name and .UniqueName functions to present the Names and Unique Names for the Product Departments in two side-by-side columns, can be readily used to support a picklist for a parameter in the reporting layer of our business intelligence solution.

Summary ...

In this article, we explored the MDX .UniqueName function, which can be called upon in activities that range from generating simple lists to supporting parameters in the reporting layer, as well as more sophisticated uses. We introduced the function, commenting upon its operation and touching upon the datasets we can deliver using .UniqueName.

We examined the syntax involved with .UniqueName, and then undertook a couple of illustrative practice examples of business uses for the function, generating queries that capitalized on its primary features. Our exercises included an example that drew upon our earlier examination of the .Name function, which we used in combination with .UniqueName to create a results dataset. We then illustrated using the dataset to support a parameter picklist in a report that queried an Analysis Services cube. Throughout our practice session, we briefly discussed the results datasets we obtained from each of the queries we constructed.

» See All Articles by Columnist William E. Pearson, III

Discuss this article in the MSSQL Server 2000 Analysis Services and MDX Topics Forum.

Share:
Home
Mobile Site | Full Site
Copyright 2017 © QuinStreet Inc. All Rights Reserved