Modeling With Prompts and Parameter Maps

Proven Practice

IBM Cognos BI - Modeling withPrompts and Parameter Maps in

Framework Manager

Product(s): IBM Cognos ReportNet, IBM Cognos 8,IBM Cognos 10

Area of Interest: Modeling Flexibility

IBM Cognos BI - Modeling with Prompts and Parameter Maps inFramework Manager 2

CopyrightCopyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULCis an IBM Company. While every attempt has been made to ensure that theinformation in this document is accurate and complete, some typographicalerrors or technical inaccuracies may exist. Cognos does not acceptresponsibility for any kind of loss resulting from the use of informationcontained in this document. This document shows the publication date. Theinformation contained in this document is subject to change without notice.Any improvements or changes to the information contained in this documentwill be documented in subsequent editions. This document containsproprietary information of Cognos. All rights are reserved. No part of thisdocument may be copied, photocopied, reproduced, stored in a retrievalsystem, transmitted in any form or by any means, or translated into anotherlanguage without the prior written consent of Cognos. Cognos and theCognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)in the United States and/or other countries. IBM and the IBM logo aretrademarks of International Business Machines Corporation in the UnitedStates, or other countries, or both. All other names are trademarks orregistered trademarks of their respective companies. Information aboutCognos products can be found at www.cognos.comThis document is maintained by the Best Practices, Product and Technologyteam. You can send comments, suggestions, and additions to [email protected] .

IBM Cognos Proprietary Information

mailto:[email protected]


Contents

1 INTRODUCTION....................................................................................................4

1.1 PURPOSE..................................................................................................................41.2 APPLICABILITY.............................................................................................................41.3 EXCLUSIONS AND EXCEPTIONS...........................................................................................4

2 MINIMIZED SQL....................................................................................................5

3 METADATA CACHING.............................................................................................6

3.1 WHAT IS METADATA CACHING?..........................................................................................63.2 WHEN CAN METADATA NOT BE CACHED?................................................................................6

4 USING PARAMETER MAPS......................................................................................8

4.1 SQL IN DATA SOURCE QUERY SUBJECTS..............................................................................94.2 MODEL MAINTENANCE..................................................................................................104.3 CALCULATION AND FILTER OBJECTS...................................................................................12

5 USING PROMPTS.................................................................................................14

5.1 SQL IN DATA SOURCE QUERY SUBJECTS............................................................................145.2 MODEL MAINTENANCE..................................................................................................155.3 CALCULATION AND FILTER OBJECTS...................................................................................16

6 GENERAL RECOMMENDATIONS............................................................................16



1 Introduction

1.1 Purpose

This document outlines proven practices for using prompts and parametermaps in ReportNet and IBM Cognos BI (Framework Manager) to increasemodel flexibility, decrease maintenance, and improve performance.

This document addresses the effects of parameter maps and prompts on SQLgeneration. Other factors such as dimensional information and determinantsplay a role in generating SQL, but that is not covered in this document.

Differences between Model Query Subjects (MQS) and Data Source QuerySubjects (DQS) will be touched on where applicable.

1.2 Applicability

The techniques and product behaviours outlined in this document apply toIBM Cognos ReportNet (tested in MR2), IBM Cognos 8.x., and IBM Cognos10. All versions will be referred to as IBM Cognos BI in this document exceptwhere version specific information is required.

1.3 Exclusions and Exceptions

Statements regarding metadata caching behaviours may change in futurereleases.



2 Minimized SQL

The query engine behind IBM Cognos BI works to reduce the SQL wherepossible to the least set of columns and tables required to process a givenquery. The benefit to this is that with the minimal set of columns and tablesincluded in a SQL expression then the database query planner is more likelyto use the optimal path for returning the required data.

This applies equally to indexes and materialized query tables that the givendatabase may have in place. A good example of this is querying a table,TableA, which has an aggregated view based on ColumnA and the sum ofColumnB. The following statement would trigger the use of the pre-computedaggregate data from the database:

SELECT ColumnA, SUM(ColumnB)

FROM TableA

GROUP BY ColumnA

However, including a column that is not included in the aggregated datasetwould force the query planner to disregard the pre-computed aggregates asa possibility for resolving the query. An example of such a statement wouldbe:

SELECT ColumnA, ColumnC, SUM(ColumnB)

FROM TableA

GROUP BY ColumnA, ColumnC

The inclusion of ColumnC could potentially result in a full scan of TableA ifthere are no other aggregates or indexes to prevent such an access path.

Keep in mind that many databases provide query rewrite capabilities. Withsuch a feature the SQL statement will be rewritten into another statementthat is functionally equivalent. So if we take the following example

SELECT T1.ColumnA, SUM(T1.ColumnB)FROM

(SELECT ColumnA, ColumnC, SUM(ColumnB) as ColumnBFROM TableA GROUP BY ColumnA, ColumnC) as T1

GROUP BY ColumnA

then by rewriting this statement to the functional equivalent, we get thesame result as the first example statement

SELECT ColumnA, SUM(ColumnB)



FROM TableA GROUP BY ColumnA

The above example shows how query rewrite serves to reform the SQL intothe functional equivalent without derived tables or unnecessary columnreferences. However, for the sake of those databases which are not capableof such rewrites and to make the SQL more legible, the aim of a modellershould be to create query subjects that are legible, efficient, andmaintainable.

3 Metadata Caching

3.1 What is metadata caching?

Metadata in the context of Framework Manager is all the information storedwithin the model that describes the objects within a data source and themanipulated objects created from your data source.

In most standard scenarios, all the properties required to describe an objectin Framework Manager will be captured during the import from a datasource. However, there are times when changes to the model will result inquery subjects that could potentially have varying properties.

In cases where the metadata cannot be cached in the model, then whenrunning a report the information must be fetched from the data sourcedirectly. Once the information is fetched from the data source, it will becached for the duration of the connection to the data source. However,retrieving the metadata from a data source can add overhead to yourcomplex reports.

3.2 When can metadata not be cached?

There are several main items which will disable the ability to the metadatastored within the model.



1. Enabling the “Allow enhanced model portability at run time” option inthe project governors will force the fetching from the database.Turning on this governor disables the use of metadata from themodel. Unless the model is being used in multiple environmentswhere the columns in the database could potentially change in datatype then this setting should be left disabled during production use ofthe model. There are cases such as during a model upgrade fromReportNet to IBM Cognos 8 and higher where the metadata shouldnot be preserved so that a subsequent resynchronization of the modelcan appropriately update the data types of the modelled data items.

Note: The Governors dialog may appear differently depending onwhich version of IBM Cognos Framework Manager you are workingwith.



2. Modifications to a DQS SQL expression can also disable caching of themetadata. This depends on the complexity of the statement. Howeverfor most scenarios the reasons for modifying a SQL expression arenon-trivial and the changes will most often result in a non-trivial SQLstatement where metadata cannot be cached.Using Parameter maps, Prompts, aggregates or filters within a DQSSQL expression will result in retrieval of the metadata from thedatabase rather than capturing the information within the model.

In the IBM Cognos 8 MR1 release and beyond, it is possible to get feedbackon metadata caching within Framework Manager. When testing a query,there is additional information provided on the “Query Information” under“Response”. As seen below there is an informational message provided whenmetadata cannot be cached in the model.

The following sections will outline options for designing Framework Managermodels to avoid this behaviour. However, in existing models, it may provedifficult to redesign according to the following sections. In such cases it ispossible to create a set of query subjects to provide the cached metadata. Todo so, one would create a new namespace and import all of the tables intothis new namespace. By leaving these newly imported query subjectsunmodified Framework Manager will be able to reference them as the trivialDB query subject required to satisfy the metadata calls for other queries inthe model.



4 Using Parameter Maps

Parameter maps are an invaluable method for substituting expressions andvalues into a query subject. A prime example of this functionality is availablewithin the GO Data Warehouse sample model where a parameter map servesto provide the capabilities for reporting in multiple data languages dependingon the user locale preference settings.

An additional common application would include replacing data sourceconnection information based on the user logon. Any place where a staticframework for a query subject is required but the detailed definition withinthe query is variable would be a place where a parameter map can beapplied.

4.1 SQL in Data Source Query Subjects

In earlier versions of the GO Data Warehouse sample you will find theparameter map “Language_lookup” being used in the “Product line” DQS asfollows:Select

PRODUCT_LINE.PRODUCT_LINE_CODE,PRODUCT_LINE.PRODUCT_LINE_#$Language_lookup{$runLocale}

# AS PRODUCT_LINEfrom

[go_data_warehouse].PRODUCT_LINE

The parameter map is keyed to the runLocale and provides the appropriatepostfix to the column reference in the SQL statement. In the case of anEnglish locale (en, en-us, en-ca, etc.) the statement would select the“PRODUCT_LINE_EN” column for use within this DQS while French localeswould use “PRODUCT_LINE_FR”.

This example is the key to providing multilingual data to report authorswithout complicated user interaction to pick the desired language column fortheir reporting.

Obviously this is a valuable technique but there are a couple of items toconsider for the above example. The first item for consideration is that theuse of the parameter map in the SQL of a DQS means that the statement isno longer trivial and the SQL cannot be minimized. As a result you wouldexpect to see the above statement as a derived table when used in yourreport queries regardless of whether you are selecting one or both of thecolumns defined by this query subject.



Second, the metadata for the query subject cannot be cached in the modelbecause the definition of the PRODUCT_LINE column is dynamic in nature.From one locale to the next you may receive different columns or expressionswith potentially different data types. The end result is that a call must bemade to the database when the query is executed to determine theproperties of the relevant column used by PRODUCT_LINE.

4.2 Model Maintenance

The core of creating any maintainable application is in making the applicationreadable and making the change process easy for future administrators.Parameter maps are extremely useful for building flexibility into models basedon prompts or session parameters. Unfortunately it is easy to get carriedaway and build too much into being dependent on parameter maps to satisfya request. Such overuse can result in query subjects that are difficult tomaintain.

First, the dialog for creating Parameter Maps is not a full-fledged expressioneditor because the information stored within a parameter map is most often afragment of an expression rather than a full, syntactically correct, statement.Using long values in the parameter map interface can become a maintenanceissue as the expressions may not be fully visible within the frame allocatedfor the parameter map value.

Second, when using parameter maps one must always consider howinformation is stored within the parameter map values. The values areactually stored as static strings without reference to any other objects in yourmodel. The values exist unto themselves and are not evaluated for syntaxvalidity within the context of a query. When testing a query subject it is onlypossible to validate one value from the parameter map at a time. Forexample, a parameter may contain a value which is badly formed or hassyntax errors. If the query subject that uses the parameter map does notreference the malformed value when testing then the developer will not beaware that the invalid syntax is present in the parameter map until reportsbegin to call the invalid parameter map value containing the malformedsyntax.

For the sake of maintaining and validating complex calculations a betterapproach is to create the expressions as individual calculation objects. Thisway the validity of all the expressions can be checked immediately andfeedback on individual calculations which may be syntactically invalid will bedisplayed within the full-fledged expression editor.



A parameter map can then be created to reference these calculations ratherthan storing the full calculation expression itself. Similarly, filters can becreated as filter objects within the model and a parameter map can referencethe filter object from the model rather than defining the full Booleanexpressions within the parameter map values.



Additionally, the overuse of parameter maps can obfuscate the purpose of aquery subject by making it unclear to anyone other than the original author.The following DQS definition is an example of such a scenario:

Select #$Time_Lookup{'DAY'}#,#$Time_Lookup{'WEEK'}#,#$Time_Lookup{'MONTH'}#,#$Time_Lookup{'QUARTER'}#,#$Time_Lookup{'YEAR'}#,#$Time_Lookup{'W_'+$Language_lookup{$runLocale}}# as

WEEKDAY,#$Time_Lookup{'M_'+$Language_lookup{$runLocale}}# as

MONTH1from [go_data_warehouse].TIME_DIMENSION

Based on the use of the “Time_Lookup” parameter map there is no way oftelling what the resulting SQL will return by visual inspection. In thisparticular instance the parameter map was constructed to mimic the original“Time dimension” query subject from the GO Data Warehouse samples whichhas the following structure:

Select TIME_DIMENSION.DAY_KEY,

TIME_DIMENSION.DAY_DATE,TIME_DIMENSION.MONTH_KEY,TIME_DIMENSION.CURRENT_MONTH,TIME_DIMENSION.QUARTER_KEY,TIME_DIMENSION.CURRENT_QUARTER,TIME_DIMENSION.CURRENT_YEAR,TIME_DIMENSION.DAY_OF_WEEK,TIME_DIMENSION.DAY_OF_MONTH,TIME_DIMENSION.DAYS_IN_MONTH,TIME_DIMENSION.DAY_OF_YEAR,TIME_DIMENSION.WEEK_OF_MONTH,TIME_DIMENSION.WEEK_OF_QUARTER,TIME_DIMENSION.WEEK_OF_YEAR,TIME_DIMENSION.WEEKDAY_#$Language_lookup

{$runLocale} # AS WEEKDAY,TIME_DIMENSION.MONTH_#$Language_lookup

{$runLocale} # AS MONTH1 from [go_data_warehouse].TIME_DIMENSION



The second statement shows a much clearer purpose for the time dimensionand makes it immediately obvious which columns are required for the querysubject. The prior version using the “Time_Lookup” map hides the fact thatseveral of the parameter map keys return collections of columns to the querysubject definition. The “DAY” key for example returns the following columns:DAY_KEY, DAY_DATE, DAY_OF_WEEK, DAY_OF_MONTH, andDAY_OF_YEAR.

However, as seen in the next section, the preferred approach to the aboveSQL statement would be to create an MQS and within it create calculationobjects for the WEEKDAY and MONTH so that the SQL in the DQS can bereduced to “select * from …”

4.3 Calculation and Filter Objects

The preferred option for using parameter maps is to include parameter mapsin MQS calculation or filter objects or as stand alone calculation or filterobjects rather than within the SQL expression of the original DQS. By leavingthe original DQS SQL in a pristine import state, we can ensure that no factorswill be present that will prevent either minimized SQL or metadata cachingwithin the model.

The syntax for using parameter maps in calculation or filter objects is similarto referencing them in SQL statements with the exception that any referencesto columns would be changed to reference the associated data item from aDQS.

From the prior section we saw an example of parameter maps being used tochoose a column based on a given locale. By resetting the “Product line” DQSto use

Select * from [go_data_warehouse].PRODUCT_LINE

the DQS will then list all of the columns from the PRODUCT_LINE table. Bycreating a new MQS or a stand alone calculation with the same parametermap, it is possible to do the same column selection as in the original SQLstatement.

#'[Product dimension].[Product line].[PRODUCT_LINE_'+ $Language_lookup{$runLocale}+']'#

The macro expression serves to generate the reference to the model itemrequired. The first portion of the statement serves to identify the namespaceand DQS used to locate the columns for the PRODUCT_LINE labels. Theparameter map then selects the single data item required from the collectionof locale-specific data items just as with the original custom SQL expressionshown in the previous section.



The benefit to this approach is that the resulting SQL for the query subject ismuch easier to read and the model stores all the relevant metadata for eachof the columns and prevents a request to the database for the metadata tobe provided at run-time.



A DQS using the custom SQL with the parameter map would provide thefollowing SQL:select

Product_line.Product_line_code as Product_line_code, Product_line.Product_line as Product_line

from (select

Product_line.PRODUCT_LINE_CODE as Product_line_code, XMIN(Product_line.PRODUCT_LINE for

Product_line.PRODUCT_LINE_CODE ) as Product_line from

(select PRODUCT_LINE.PRODUCT_LINE_CODE, PRODUCT_LINE.PRODUCT_LINE_EN as PRODUCT_LINE

from go_data_warehouse...PRODUCT_LINE) Product_line

group by Product_line.PRODUCT_LINE_CODE ) Product_line

With the changes to use an MQS with the parameter map, we obtain thefollowing SQL:

select Product_line.Product_line_code as Product_line_code, Product_line.Product_line as Product_line

from (select

Product_line.PRODUCT_LINE_CODE as Product_line_code, XMIN(Product_line.PRODUCT_LINE_EN for

Product_line.PRODUCT_LINE_CODE ) as Product_line from go_data_warehouse...PRODUCT_LINE Product_line group by Product_line.PRODUCT_LINE_CODE ) Product_line

The new MQS approach to parameter maps removes the inner derived tableselecting the PRODUCT_LINE_CODE and the PRODUCT_LINE_EN.

Note that the XMIN you see in the SQL is due to the “group by” option beingchecked for the PRODUCT_LINE_CODE determinant. Without this option, theSQL would collapse and remove the aggregation within the SQL. However, inthis case the “group by” option is required for comparing facts from tables atdifferent levels of granularity.



5 Using Prompts

Prompts within a model serve a very valuable role in that they allow users tointeract with the queries at a basic level. This can build performance andfunctionality into a model that would be difficult to achieve consistently in theend-user reporting environment.

A good example of this would be a query subject designed to generate a setof relative time periods. A prompt for a “current date” would allow users toreport relative time periods starting at any arbitrary date. Recreating thistype of reporting in Report Studio is difficult due to the complexity of thequeries required to generate the date ranges. Further, recreating thesequeries in many reports can be both tedious and prone to errors.

5.1 SQL in Data Source Query Subjects

As with parameter maps, when using a prompt in DQS SQL, the addition ofthe prompt means that the SQL is no longer trivial. When the query becomesnon-trivial it is evaluated as a whole to determine both the native SQL andthe metadata associated with the data items. In this case a call to the datasource may be made at run-time to fetch the data item properties. For somedata sources, the function calls within the database required to perform thismetadata fetch can account for several seconds of delay during the preparephase of the query execution while IBM Cognos BI is waiting for the datasource to return the required information.

Since the SQL is evaluated as a unit, the prompt will be displayed to usersany time that the query subject is referenced. In some cases this is good as itenforces a business rule to retrieve user input every time the request issubmitted. In other cases such as when the prompt is used in a calculationthat may or may not be required by the end report, then the prompting maybe considered unnecessary from a user perspective.

An example where the prompt would, by definition, always be presented tothe user would be:

Select *

from [go_data_warehouse].PRODUCT_LINE PRODUCT_LINE

Where PRODUCT_LINE.PRODUCT_LINE_CODE = #prompt(‘Product

Line Code’, ‘integer’)#

Here the user will be forced to select only one Product Line at a time forreporting and would not be able to report against multiple Product Linevalues within the same query.





An example of when the prompt may not be desirable when reporting is:Select

*,Case PRODUCT_LINE.PRODUCT_LINE_CODEWhen #prompt(‘Target Product Line Code’, ‘integer’, ‘1’)#

then 1Else 0End as “Target Product Line”

from [go_data_warehouse].PRODUCT_LINE PRODUCT_LINE

Here the “Target Product Line” calculation may serve to identify a set ofvalues that can be used a as a baseline for comparison with other ProductLines. However, even if the user does not include the “Target Product Line”data item in their report, they will be prompted to provide a Product Linebecause the prompt is essential to evaluating the full definition of the DQS.

5.2 Model Maintenance

The driving force behind prompts within a model is typically for specificbusiness rules or reporting applications. When capturing common promptingscenarios in the model, the end users are forced to satisfy a particularprompt name to execute the query. For simple cases such as Query Studioand Analysis Studio, a single prompt name will have little impact on theability of a user to create their desired queries. For power users of ReportStudio, a single simplistic prompting scenario can be limiting.

A good example of this is the relative time scenario mentioned earlier. Bybuilding a single date prompt into the relative time query subject, it ispossible to generate multiple periods such as Month-To-Date and Year-To-Date to allow for easy reporting of relative time from a relational source.However, if a Report Studio author wanted to generate two queries in asingle report that used different starting dates for the relative time querysubject (say one used December as the current month while another woulduse October), then there would be difficulties as the single prompt namewould drive all the queries that used the relative time query subject and youcould only report from one “current period” at a time.

This type of scenario could drive users to request multiple instances of theprompted query subject to be created in the model using different promptnames. This can quickly scale out of control as the large scale developmentof many redundant query subjects in a model will greatly increasemaintenance costs.



In scenarios where a query subject or calculation will be used by reportauthors in many wildly varying applications, it may be best to leave theprompting to the individual report authors as it is difficult to foresee everypossible application that a user will need to generate for reporting.

5.3 Calculation and Filter Objects

Nearly any prompting scenario can be captured in an MQS or stand alonefilter object. If we take the previous examples, the first case can be definedusing a filter object as:

[Product dimension].[Product line].[PRODUCT_LINE_CODE] = #prompt(‘Product Line Code’, ‘integer’, ‘1’)#

Similarly, the case statement shown previously can be defined as thefollowing calculation in an MQS or stand alone calculation:

Case [Product dimension].[Product line].[PRODUCT_LINE_CODE]When #prompt(‘Target Product Line Code’, ‘integer’, ‘1’)# then 1Else 0End

The difference when using calculation objects is that the “Target Product LineCode” prompt is no longer required if the calculation is not used in the user’sreport. If the calculation is not included in this case, then there is no need toadd it when referencing the base SQL statement from the DQS or to preparethe SQL for the request.

Also when using calculations and filter objects in MQSs or as stand aloneobjects, the DQS SQL statement can be left untouched and the SQL willremain trivial. This eliminates the need to fetch metadata data from a datasource connection as the information can be cached within the model andmaintains the ability to minimize the SQL.

6 General Recommendations

In practice, it is better to use parameters and prompts within MQS or standalone calculation and filter objects rather than inserting them within the SQLof a data source query subject. Following this approach will ensure betterSQL generation that leads to better performance or better matching withunderlying materialized views.

Parameter maps are ideal for scenarios where information needs to beswapped dynamically based on session information or user interaction viaprompts. As a general rule, parameter maps should be reserved for thefollowing two scenarios.



Using a parameter map greatly simplifies the resulting SQL for a query orexpression. For example the following calculation in an MQS referencingcolumns from Table1 and Table2

CASE #prompt(‘Prompt Name’, integer, ‘0’)#WHEN 1 THEN [Table1].[Column1] * [Table2].[Column2]WHEN 2 THEN [Table1].[Column2]ELSE 0END

can be converted to use a parameter map#$Parameter_Map{ prompt(‘Prompt Name’, integer, ‘0’)}#

where the Parameter map would contain the following:

Key Value

1 [Table1].[Column1] * [Table2].[Column2]

2 [Table1].[Column1]

The default value of the parameter map would be set to zero so thatwhen ‘0’ is supplied from the prompt the return would be the integervalue of zero.

With the parameter map, the individual conditions from the CASEstatement can be inserted as required. This potentially eliminates theneed to join to Table2 for when the prompt value equals 2 while theoriginal case statement would have forced the join between the twotables every time the calculation was used regardless of the user input tothe generated prompt.

Using a parameter map accomplishes an operation that would be difficultif not impossible for the end user. An example would be the multi-lingualreporting data in the sample models. Based on the user preferences, themodel will swap columns to return the appropriate data language forreporting.

Similarly a parameter map can be used to swap columns, tables,schemas, or even data source connections based on parameters such asthe user ID. This could be used to mimic the Virtual Private Databasefunctionality that vendors such as Oracle are capable of, in otherdatabases that do not naturally support such functionality.



In regards to prompt macros being built into a model, the main considerationfor their use is in foreseeing all possible applications that a user maygenerate within the query tools. Typically a prompt built into a model willrestrict some of the flexibility available to users in one way or another. Thedegree to which these restrictions impact the ability of users to generate thequeries they need is the deciding factor for or against using a prompt withina model.In practice, when generating parameter maps and prompts within a model, itis difficult to see all the possible scenarios for their use when they are beingcreated. In an ad-hoc reporting environment, this can be detrimental as themodel will tend to direct users along set query paths determined by aparameter map or prompt.

If parameterization and prompting in the model are taken to extremes, thenthe resulting queries can become inflexible to a point where a query subjectcan only be used to answer one specific business question. In such a scenariothe tasks of a report author have been effectively rolled entirely into themodel. At this point the overhead for model maintenance will be quite high asreports will be tied to such a degree to the query subject definition that newreports may require development of entirely new queries within the model.Likewise, updates to existing reports may require involvement of the modeldeveloper rather than being entirely within the scope of a report author’scapabilities.

By careful planning and limitation of parameterization and prompting toscenarios where they are absolutely required, a model developer can ensurethat future maintenance tasks will remain simple and that the impact ofchange will be minimal to the report authors. Likewise the model will remainflexible enough to satisfy the ad-hoc nature of reporting in today’s businessworld.


Date post:	10-Oct-2014
Category:	Documents
Upload:	viji-banu
View:	456 times
Download:	1 times

Modeling With Prompts and Parameter Maps

Documents