Show TOC

Consumption AnnotationsLocate this document in the navigation structure

Define specific behavior that relates to the consumption of CDS content through domain-specific frameworks

Scope and Definition
@Scope:[#ELEMENT, #PARAMETER]
Annotation Consumption
 {
   labelElement : elementRef;
   quickInfoElement : elementRef;
   valueHelp : elementRef;
   hidden : Boolean default true;
   derivation
   {
      lookupEntity : entityRef;
      procedure : String;
      resultElement : elementRef;
      derivationFilter : String;
      binding : array of
      {
         targetParameter : parameterRef;
         targetElement : elementRef;
         type : String(10) enum { PARAMETER; CONSTANT; };
         value : String(512);
      };
   };
 };
@Scope:[#VIEW, #TABLE_FUNCTION, #PARAMETER, #ELEMENT]
Annotation Consumption
 {
   semanticObject : String;
 };
@Scope:[#ELEMENT] 
 {
   filter
   {
      mandatory : Boolean default true;
      defaultValue : String;
      defaultValueHigh : String;
      hidden : Boolean default true;
      selectionType : String(20) enum { SINGLE; INTERVAL; RANGE; HIERARCHY_NODE; };
      multipleSelections : Boolean default true;
      hierarchyBinding : array of
      {
         type : String(10) enum { ELEMENT; PARAMETER; CONSTANT; USER_INPUT; };
         value : String(512);
         variableSequence : Integer;
      };
   };
   groupWithElement: elementRef;
 };
@Scope:[#PARAMETER]
Annotation Consumption
 {
   defaultValue : Expression;
 };
Usage

Via those Annotations the specific behavior is defined which is related to the consumption of CDS content. This metadata makes no assumptions about the concrete consumption technology/infrastructure, but it is applicable across multiple consumption technologies (e.g. Analytics or OData).

Annotation Meaning
Consumption.defaultValue

This annotation enables specification of a default value for a View parameter

Scope: #PARAMETER

Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.

Values:

This value is either proposed to the end user or implicitly set by the consumer (framework) of the view whenever the end user does not explicitly specify a different value. This default value is transparent for the CDS runtime, which means that the View parameter is still mandatory at this level. Therefore, the consumption framework is responsible for passing the specified default value as a parameter binding when the view is invoked.

Note The defaultValue annotation is only allowed for View parameters. Elements and default values can only be specified within filters. Hence, the annotation @Consumption.filter.defaultValue has to be used.
Consumption.derivation
This annotation enables derivation of the value for a parameter or a filter automatically at runtime by selecting a row from a given entity(table). The relevant attributes of a derivation rule are:
  • lookupEntity - Entity which is used to read the result to fill the parameter.

  • procedure - Database Procedure which is used to read the result to fill the parameter.

  • resultElement - Element of the lookupEntity or scalar export parameter of the procedure providing the result

  • derivationFilter - Filter on the lookupEntity to restrict its contents to one row (has no effect on the procedure)

  • binding - Is used to provide a parameterization for the (scalar) input parameters of the lookupEntity or procedure

An element can be annotated with Consumption.derivation only if for this element Consumption.filter is present. The derivation is then used for determining the filter value. An empty derivation of a hidden and mandatory parameter/filter will cause a runtime error.

Note Annotation of a non-filtered element of the projection list with a derivation is not allowed.

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.

Consumption.derivation.binding.targetParameter

This annotation enables provision of a parametrization for the (scalar) input parameters of the lookupEntity procedure. This sub-annotation specifies a parameter name of lookupEntity or procedure.

Values:

Value Description
parameterRef
Consumption.derivation.binding.targetElement

This sub-annotation enables provision of a parametrization for the (scalar) input parameters of lookupEntity or procedure.

Values:

Value Description
elementRef
Consumption.derivation.binding.type

This sub-annotation specifies how the target is filled (by a constant, a parameter or a (filtered) element).

Values:

The following enumerations (String (10)) are provided:

Value Description
ELEMENT
PARAMETER
CONSTANT
Consumption.derivation.binding.value

. This sub-annotation contains, depending on the type, the constant value, the parameter name (without : or $parameter) or the element name.

Note If parameter values are used in this sub-annotation, the corresponding parameter must be declared before the parameter, that is to be derived, is declared.
Note All provided annotation values are treated case sensitive.

Values:

Value Description
String (512) constant value, parameter name (without : or $parameter) or element name
Consumption.derivation.derivationFilter

Filter on the lookupEntity to restrict its contents to one row that has no effect on the procedure. This annotation won't be interpreted by the analytic query layer.

Values:

Value Description
Expression
Consumption.derivation.lookupEntity

reads the result to fill the parameter.

Values:

Description
entityRef
Consumption.derivation.procedure

Database procedure to read the result to fill the parameter. This annotation won't be interpreted by the analytic query layer.

Values:

Description
String
Consumption.derivation.resultElement

Element of the entity/scalar export parameter of the procedure providing the result.

Values:

Description
elementRef
Consumption.filter

This annotation enables filtering on elements of the underlying view. A filter should be specified before executing a query on the view.

Scope: #ELEMENT

Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.

Values:

Usually filter values are entered manually by the user on a UI (filter popup) in order to set a filter on an element of the underlying view. Filters are not explicitly known by the Core CDS Layer, but only by the clients like Datapreview, MDX, Advanced Analysis for Office, BO Explorer or OData. It is the task of the consumption (framework) to convert the user input into the WHERE condition when accessing the data.

Note

Filters can only be specified for elements within the projection list.

Specify a filter before executing a query on the view.

Consumption.filter.defaultValue

This annotation can be used to provide a fix default value for a filter. This value is completely transparent for the CDS runtime, which means that the consumer is responsible for explicitly extending the WHERE condition.

The default value is either proposed to the end user or implicitly set by the consumer (framework) of the view whenever the end user doesn’t explicitly specify a different value.

Values:

Value Description
String Characteristic members need to be provided in internal noncompounded format.
Consumption.filter.defaultValueHigh

This annotation, together with Consumption.filter.defaultValue, allows to specify a default Intervall.

Values:

Value Description
String Characteristic members need to be provided in internal noncompounded format.
Consumption.filter.hidden

The filter will not be shown in the UIs. In combination with a derivation, this leads to a dynamic filter at runtime without user interaction.

Values:

Value Description

Boolean, default true

Consumption.filter.hierarchyBinding.type

This annotation determines how the key element is filled (by a constant, a parameter, a filtered element or by a user input field).

Values:

Value Description
#CONSTANT
#PARAMETER
#ELEMENT
#USER_INPUT
Consumption.filter.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.

Values:

Value Description
String(512)
Consumption.filter.hierarchyBinding.variableSequence

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

Values:

Value Description
#USER_INPUT

Consumption.filter.mandatory

To prompt the “Filter UI” to enforce a user entry for a (semantically) mandatory element, even if a default value exists (for example, defined through a CASE expression).

Example The user deletes the proposal for a mandatory filter in the Filter UI. The UI then displays an error message "Please enter a value for filter ...". Finally, the entered value is sent to the engine. Therefore, the Filter UI makes sure that automatic replacement of the engine is never performed for mandatory filters.

Values (optional):

Value Description

Boolean, default true

Consumption.filter.multipleSelections This annotation indicates the lines that can be entered on filter input (selection) UIs combined with the following selectionType values:
Value Description
selectionType SINGLE and multipleSelections = true IN list
selectionType INTERVAL and multipleSelections = false Single interval
selectionType INTERVAL and multipleSelections = true Several intervals
selectionType RANGE and multipleSelections = true Several ranges (complete (ABAP-like) SELECT options).
Consumption.filter.selectionType

This annotation determines how values can be entered.

Values:

Value Description
SINGLE Single value
INTERVAL Special case of a range with sign = including and operator = BT.
RANGE A range is a complete (ABAP like) SELECT option including sign (including/excluding) and operator (e.g. EQ, CP, BT).
HIERARCHY_NODE Hierarchy node (means everything under the node)
Consumption.groupWithElement

This annotation enables recognition of View/ Entity elements whose values semantically depend on the values of other elements and can only be understood in their context

Scope: #ELEMENT

Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.

Note Whenever such elements are used for querying grouped data, the context-providing elements should also be included in the query's "group by" expression.

Values:

Value Description
elementRef
Consumption.hidden

This annotation prevents fields from being exposed by OData. The annotation therefore prevents fields from being available for the client. This is necessary for system parameters because these parameters need to be filled by the runtime engine, but must not be available for the client.

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine):
  • SADL - Prevents fields from being exposed by OData.

  • Analytic Manager - For #ELEMENT: In the Analytic Query Layer, this annotation is only evaluated if the element represents a measure. Typical usecase: An element is a calculated measure which serves as intermediate result and shall not be shown in the Analytic Query result.

Note

The annotation will not be exposed to UIs.

Values:

Value Description

Boolean, default true

Consumption.labelElement

This annotation enables consumer frameworks (such as UI or analytical clients) to identify through which elements the explanatory texts for the "identifier" elements can be retrieved.

In cases where both the identifier elements and the text elements are exposed, the identifier elements are annotated with the labelElement annotation. They then point to the element that contains the label text. A labelElement annotation silently implies a groupWithElement annotation of the "text" element pointing to the "identifier" element.

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine): SADL - The referenced element will be handled as descriptive text of the annotated field in OData exposure scenarios.
Note

We recommend to use ObjectModel.text.element[ ] instead of the Consumption.labelElement annotation.

Values:

Value Description
elementRef
Consumption.quickInfoElement

This annotation supports the same scenario as labelElement.

Through this annotation the identifier elements are enriched with the information as to which elements contain the corresponding long texts. A quickInfoElement annotation silently implies a group WithElement annotation of the text element pointing to the identifier element.

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager.

Values:

Value Description
elementRef
Consumption.semanticObject

This annotation enables annotation of SAP-specific business semantics, thus extending the standardized business semantics covered by the @Semantics domain

Consumers may leverage this enrichment for enhanced interoperability across applications.

Example SAP Fiori has introduced the concept of intent-based navigation, whereby an intent is a combination <semanticObject> <action>. A semanticObject annotation is used in SAP Fiori UIs to dynamically derive navigation targets for the annotated view as a source.

Scope: #ELEMENT, #PARAMETER, #TABLE FUNCTION, #VIEW

Evaluation Runtime (Engine): SADL - Translates CDS annotations into the corresponding OData annotations.

Values:

Value Description
String For more information Based on Intent.
Consumption.valueHelp

This annotation enables referencing of the association to a CDS view / CDS entity that provides the Value Help object for the annotated element

The ON condition of the referenced association specifies how the value help content needs to be retrieved for the element. Generic UI consumers have to identify these ValueHelp annotations and use the referenced association to retrieve the values.

Instead of defining the "Value element" of the value help view using an equal ON condition of the association, you can also specify the "value element" in the annotation and then have no or non-equal ON conditions for the "value element".

Scope: #ELEMENT, #PARAMETER

Evaluation Runtime (Engine): SADL - Derives a default value help support from the annotated association.

Values:

Value Description
elementRef
Examples
Example 1

The annotations Consumption.labelElement and Consumption.quickInfo are used to link the corresponding text and ID fields:

Sample Code
DEFINE VIEW SalesOrder
AS SELECT FROM sepm_cds_sales_order AS so
{
  key so.sales_order_id AS SalesOrderId,
  
  @Consumption.labelElement: 'CompanyName'
  @Consumption.quickInfoElement: 'CompanyDescription'
  so.buyer_guid AS BuyerGuid,

  so.company_name AS CompanyName,
  
  so.description AS CompanyDescription
}
Example 2

The annotation Consumption.groupWithElement is used to define that the element CompanyName depends semantically on the element BuyerGuid. In the case of an aggregated table, the fields can be displayed combined:

Sample Code
DEFINE VIEW SalesOrder with parameters
AS SELECT FROM sepm_cds_sales_order AS so
{
  key so.sales_order_key AS NodeKey,
  
  so.buyer_guid AS BuyerGuid,
  
  @Consumption.groupWithElement: 'BuyerGuid'
  so.company_name AS CompanyName,
  
  so.currency_code AS CurrencyCode,

  @DefaultAggregation: #SUM
  so.gross_amount AS GrossAmount
}
Example 3

The annotation Consumption.hidden is used to prevent fields from being exposed by OData. The annotation therefore prevents fields from being available for the client. This is necessary for system parameters because these parameters need to be filled by the runtime-engine, but must not be available for the client:

Sample Code
DEFINE VIEW SalesOrder
AS SELECT FROM sepm_cds_sales_order AS so
  ASSOCIATION [0..1] TO sepm_cds_business_partner AS _Customer 
  on $projection.BuyerGuid = _Customer.business_partner_key
{
  
  key so.sales_order_id AS SalesOrderId,
 
  @Consumption.hidden: true
  so.buyer_guid AS BuyerGuid,
 
  _Customer.company_name AS CompanyName
}
Example 4

The annotation Consumption.defaultValue is used to specify default values for parameters. In this example, the currency EUR is used:

Sample Code
DEFINE VIEW SalesOrder with parameters
    @Consumption.defaultValue: 'EUR' 
    p_TargetCurrency : snwd_curr_code
AS SELECT FROM sepm_cds_sales_order AS so
{
  key so.sales_order_key AS NodeKey,
  
  $parameters.p_TargetCurrency AS CurrencyCode,

  currency_conversion( 
    amount              => so.gross_amount, 
    source_currency     => so.currency_code, 
    target_currency     => $parameters.p_TargetCurrency,
    exchange_rate_date  => CAST( '20150101' AS abap.dats )
  ) AS GrossAmount
}
Example 5

The annotation Consumption.valueHelp is used to expose an association as a value help. In this example, the CDS view CurrencyCodeValueHelp is used for the field CurrencyCode:

Sample Code
DEFINE VIEW CurrencyCodeValueHelp
AS SELECT FROM currency_code
{
  key CurrencyCode,
  CurrencyName,
  CurrencyDescription
}

DEFINE VIEW SalesOrder
AS SELECT FROM sepm_cds_sales_order AS so
  ASSOCIATION [0..1] TO CurrencyCodeValueHelp AS _Currency
  on $projection.BuyerGuid = _Customer.business_partner_key    
{
  so.sales_order_id AS SalesOrderId, 

  @Consumption.valueHelp: '_Currency'
  so.currency_code AS CurrencyCode,

  so.gross_amount AS GrossAmount  
}
Example 6

The association Consumption.semanticObject is used to assign semantic objects to CDS views or elements that can be used in the UI for intent-based navigation.

Sample Code
@Consumption.semanticObject: 'SalesOrder'
DEFINE VIEW SalesOrder    
AS SELECT FROM sepm_cds_sales_order AS so
{
  so.sales_order_id AS SalesOrderId, 

  @Consumption.semanticObject: 'BusinessPartner'
  so.buyer_guid AS BuyerGuid,
}
Example 7

The annotation Consumption.filter is used to enable filters for values. In this example, product_hierarchy is filtered for several single values of calendar_day, and for one single interval of product.

Sample Code
@Analytics.query : true
DEFINE VIEW product_hierarchy
AS SELECT FROM sales
{  
   ...
   @Consumption.filter : { selectionType : #SINGLE, multipleSelections : true}    
   calendar_day,    //several single values are allowed
   @Consumption.filter : { selectionType : #INTERVAL, multipleSelections : false }  
   product,      	  // single interval allowed  
   ...
}
Example 8

The annotation Consumption.filter is used to enable filters for values. In this example, costcenter_reporting is filtered hierarchically for the constant CONTR_AREA_10 and for the parameter cost_center_hier_param.

Sample Code
@Analytics.query : true
DEFINE VIEW costcenter_reporting
  with parameters cost_center_hier_param : String 
AS SELECT FROM costcenters
{
  ...
  @Consumption.filter : {
    selectionType : #HIERARCHY_NODE, 
    multipleSelections : false,
    hierarchyBinding :
    [ { type : #CONSTANT, value : 'CONTR_AREA_10' }, 
      { type : #PARAMETER, value : 'cost_center_hier_param' } ]
  }
  costcenter,     // hierarchy node filter
 
  costs,
  ...
}