Show TOC

AnalyticsDetails AnnotationsLocate this document in the navigation structure

Enable application developers to specify the default multidimensional layout of the query, the sequence of variables in UI consumption, and the specific aggregation and planning behavior of the data. All these annotations can only be used in views with @Analytics.query : true.

Scope and Definition
@Scope:[#ELEMENT]
Annotation AnalyticsDetails
 {
   query
   {
      formula : String;
      axis : String enum { FREE; ROWS; COLUMNS; };
      totals: String enum { HIDE; SHOW; };
      scaling : Integer;
      decimals : Integer;
      displayHierarchy : String enum { OFF; ON; FILTER; };
      hierarchyBinding : array of
      {
         type : String enum { ELEMENT; PARAMETER; CONSTANT; USER_INPUT; };
         value : String;
         variableSequence : Integer;
      };
   };
   exceptionAggregationSteps : array of
   {
      exceptionAggregationBehavior : String enum { SUM; MIN; MAX; COUNT; AVG; STD; FIRST; LAST};
      exceptionAggregationElements : array of elementRef;
   };
   planning
   {
      enabled : Boolean default true;
      disaggregation : String enum { NONE; TOTAL; DIFFERENCE; };
      distribution : String enum { EQUAL; PROPORTIONAL; PROPORTIONAL_REF; };
      distributionReference : elementRef;
   };
   resultValueSource : String enum { CUBE; DIMENSION; };
 };
@Scope:[#PARAMETER, #ELEMENT]
Annotation AnalyticsDetails
 {
   query
   {
      variableSequence : Integer;
   };
 };
Usage
Annotation Meaning

AnalyticsDetails.exceptionAggregationSteps.exceptionAggregationBehavior

Usually, the default aggregation determines how measures are aggregated in analytics. But in some cases different aggregation behavior is needed for a special element of the entity (dimension of a cube).

Note

Example: A measure "Inventory" can be summed up for the different plants and other dimensions, but not for time – according to time the last or average value might be relevant.

Exception aggregation is optional and is used to define different (to the default aggregation) aggregation behavior for specified elements. In general there can be multiple elements in which a measure has to be aggregated differently. Therefore a list of ExceptionAggregationSteps can be assigned. ExceptionAggregationBehavior defines the aggregation behavior.

Note

Example: In the query there is a measure, which should show the number of customers with positive sales - where sales is a measure of the underlying CUBE view with default aggregation SUM. When the sales measure is now used in a query with exceptionAggregationBehavior: COUNT and exceptionAggregationElements : Customer, the sales must first be aggregated (SUM) at customer level, and then COUNT has to be performed. If the sales for a customer is positive, this means that the sales is replaced by 1 (otherwise it is set to 0). This number can be summed up again.

Scope: #ELEMENT

Evaluation Runtime (Engine): The (logical) order in which the Analytic manager performes the aggregation is as follows: Firstly the DefaultAggregation is performed. This intermediate result is still grouped by all elements in the list of ExceptionAggregationSteps. The result is then aggregated by the exception aggregation in the order of StepNumber.

The first remark holds even if the DefaultAggregation is FORMULA. This means that the calculation is performed when the result is still grouped by the exception aggregation elements. After the formula has been calculated, the result is aggregated according to the list of ExceptionAggregationSteps. This means that the aggregation level to be used for calculation can be defined precisely.
Value Description
SUM sum
MIN minimum
MAX maximum
COUNT counter
AVG average
STD standard deviation
FIRST FIRST
LAST LAST

AnalyticsDetails.exceptionAggregationSteps.exceptionAggregationElements : [ '' ]

The elements which should be aggregated in this step. These elements must represent characteristics.

Scope: #ELEMENT

Evaluation Runtime (Engine): Analytic manager: For more information see AnalyticsDetails.exceptionAggregationSteps.exceptionAggregationBehavior.

Value Description
array of elementRef

list of elements representing characteristics

AnalyticsDetails.planning.disaggregation

This annotations allows you to define the disaggregation behavior. This annotation is only available for elements with AnalyticsDetails.planning.enabled.

Scope: #ELEMENT

Evaluation Runtime (Engine): If a measure is specified with this annotation, it is input-ready in the analytic query. It enables the user to make manual entries for aggregated values. These values must be disaggregated on all the data records that contribute to the aggregated value of the cell.
Value Description
NONE No Disaggregation (default)
TOTAL Disaggregates the value entered.
DIFFERENCE Disaggregates the difference to value entered.

AnalyticsDetails.planning.distribution

If disaggregation is chosen, you can choose how the value is distributed during disaggregation with this annotation.

Scope: #ELEMENT

Evaluation Runtime (Engine): This annotation will be ignored if CDS view or the corresponding element is not enabled for planning.

Value Description
EQUAL Equal distribution (default)
PROPORTIONAL Proportional to the current value
PROPORTIONAL_REF Proportional to the current value of a sibling member in the selection list, which needs to be specified via the AnalyticsDetails.planning.distributionReference annotation.

AnalyticsDetails.planning.distributionReference

If disaggregation is chosen and AnalyticsDetails.planning.distribution : #PROPORTIONAL_REF, you can specify a sibling member in the selection list for reference with this annotation.

Scope: #ELEMENT

Evaluation Runtime (Engine): This annotation will be ignored if CDS view or the corresponding element is not enabled for planning.

Value Description
elementRef Name of sibling member for reference

AnalyticsDetails.planning.enabled

Individual members in the selection list (no calculated elements) need to be annotated for enabling planning. The list can only be used in input-enabled analytic queries. This means that the views have to be annotated with Analytics.query: true and Analytics.planning.enabled: true.

Scope: #ELEMENT

Evaluation Runtime (Engine): If a measure is specified with this annotation, it is input-ready in the analytic query.

Value Description
true The member in the selection list is enabled for planning. This is the default setting.
false The member in the selection list is not enabled for planning.

AnalyticsDetails.query.axis

The elements of the view can be positioned on multiple axes. The elements can be directly annotated with their axis. Measures (elements which can be aggregated (defaultAggregation)) all need to be on the same axis. The annotation of the first measure will therefore be used for all measures of the query. If no AnalyticsDetails.query.axis is found, the system positions the measures on the columns.

The default value for elements which are not measures is the free axis. Note that elements in the projection list, which belong to the same field in the query, will be grouped together.

Scope: #ELEMENT

Evaluation Runtime (Engine): If the BI client does not specify which elements are on which axis, the layout is derived by this annotation.

Value Description
FREE Default value for elements other than measures.
ROWS
COLUMNS Default value for measures.

AnalyticsDetails.query.decimals

For measures, restricted measures and calculated elements, you can set the number of decimals to be used.

Scope: #ELEMENT

Evaluation Runtime (Engine): Analytic manager: This annotation is only relevant for measures. For other elements it will be ignored.

Value Description
Integer number from 0 to 9. Numbers will displayed with n decimals.

AnalyticsDetails.query.displayHierarchy

This annotation allows you to specify the display hierarchy attribute for the element. It is not possible for measures.

Scope: #ELEMENT

Evaluation Runtime (Engine): Analytic managerThe query result is shown in a hierarchy for the specified element.
Value Description
OFF No display hierarchy
ON With display hierarchy. The hierarchy used can be specified by AnalyticsDetails.query.hierarchyBinding
FILTER The display hierarchy is the same one defined on the filter for this element. In this case, a hierarchy filter needs to be defined on the same element. The hierarchy binding is taken from the filter.

AnalyticsDetails.query.formula

This annotation allows you to specify the formula expression, which cannot be expressed as an SQL formula (operands required from the element list of the view). Only numerical values (measures) can be used as operands.

Scope: #ELEMENT

Evaluation Runtime (Engine): Analytic manager: This annotation will be interpreted as a formula.
Value Description
String

This expression can contain the following:

  • cube measures

  • arithmetic expressions

  • functions NDIV0 and NODIM

  • CASE expressions with a maximum of one THEN clause (will be translated into BW IF operator)

    • WHEN clause can contain conditional or Boolean expressions of measures

    • ELSE clause is optional (default to ELSE 0 )

AnalyticsDetails.query.hierarchyBinding.type

The AnalyticsDetails.query.hierarchyBinding annotations allow you to specify a special hierarchy for an element with a display hierarchy. One tupel has to be specified for each key field of the hierarchy directory view. The first entry is supplied to the first key field of the hierarchy directory, the second entry to the second key field, and so on. If only one hierarchy exists, the hierarchy binding can be omitted.

AnalyticsDetails.query.hierarchyBinding.type determines how the key element is filled (by a constant, a parameter, a filtered element or by a user input field).

Scope: #ELEMENT

Evaluation Runtime (Engine): Analytic manager
Value Description
#ELEMENT

Name of an element, which has a unique filter. At runtime the filter value is used for this hierarchy component.
#PARAMETER

Parameter name
#CONSTANT

Constant
#USER_INPUT

USER_INPUT is optional. It will be requested at runtime of the analytic query. It can contain a name. USER_INPUT with the same name will be provided with the same user input at runtime. The variable is placed in the list of all values in accordance with AnalyticsDetails.query.variableSequence.

AnalyticsDetails.query.hierarchyBinding.value

This annotation contains, depending on the type, a literal value, the parameter name (without : or $parameter), the element name and an identifier for the user input field, respectively.

Scope: #ELEMENT

Evaluation Runtime (Engine): Analytic manager
Value Description
String(512)

AnalyticsDetails.query.hierarchyBinding.variableSequence

This annotation allows you to specify the order of parameters and variables on the variable input UIs.

Note

You can also use the annotation Consumption.filter.hierarchyBinding.variableSequence.

In case filters or parameters are not annotated they are displayed after the annotated ones in the order they appear in the CDS document.

Scope: #ELEMENT

Evaluation Runtime (Engine): Analytic manager
Value Description
Integer

This number defines the position of the variable generated for the user input field.

AnalyticsDetails.query.scaling

For measures, restricted measures and calculated elements, you can set the scaling factor to be used.

Scope: #ELEMENT

Evaluation Runtime (Engine): This annotation is only relevant for measures. For other elements it will be ignored.

Value Description
Integer: Integer number from 0 to 9. Numbers will be scaled by a factor of 10**n.

AnalyticsDetails.query.totals

For attributes you can set the behavior for totals.

Scope: #ELEMENT

Evaluation Runtime (Engine): These annotations will be ignored for measures.
Value Description
HIDE Totals or subtotals are not added to the result set for this element.
SHOW In addition to the details, the subtotals are added to the result set for this element.

AnalyticsDetails.query.variableSequence

If user input is necesssary for the parameter, the sequence of all fields for user input at runtime can be specified with this annotation.

Scope: #PARAMETER, #ELEMENT

Evaluation Runtime (Engine): UIs will create user prompts for parameters which require a user input or elements with filters (consumption.filter). This annotation can be used to specify the sequence of user prompts at runtime. If filters or parameters are not annotated, they are displayed after the annotated ones - in the order they appear in the CDS document.
Value Description
Integer Order of parameters and variables. The integer values may contain gaps.

AnalyticsDetails.resultValueSource

This annotation influences the list of values, which should be taken into account for a specific characteristic.

Scope: #ELEMENT

Evaluation Runtime (Engine): When the query is executed, a row of data is only displayed for the characteristic if there are posted values for this characteristic.
Value Description
CUBE All values available in the view of the fromclause.
DIMENSION All values available in dimension.
Examples
Example 1

Calculated Elements:

Sample Code 
@Analytics.query : true
define view fincancial as select from sales

{
  @AnalyticsDetails.query.axis : #ROWS
  product,   
  @AnalyticsDetails.query.axis : #COLUMNS
  @AnalyticsDetails.query.formula : 'revenue - cost'

  1 as absolute_margin,

  @AnalyticsDetails.query.formula : 'NDIV0($projection.absolute_margin / revenue ) * 100'

  1 as relative_margin,
 
  @AnalyticsDetails.query.formula : 'CASE WHEN $projection.relative_margin > 20 THEN revenue ELSE 0 END'
  1 as revenue_for_margin_gt_20 

}
Example 2

Display hierarchy selection:

Sample Code 
@Analytics.query : truedefine view costcenter_reporting 

  with parameters

    cost_center_hier_param : String  

as select from costcenters

{

  ...

  @AnalyticsDetails.query : {

    displayHierarchy: #ON,
    hierarchyInitialLevel: 3

    hierarchyBinding : 

    [ { type : #CONSTANT, value : 'CONTR_AREA_10' },  

      { type : #PARAMETER, value : 'cost_center_hier_param' }

    ]

  } 

  costcenter,  // hierarchy node filter

  costs,

  ...  

}