SAP ABAP Central: ABAP CDS

The syntax of the DDL and of the DCL of the ABAP CDS comprises elements of the general DDL and DCL of SQL. In addition, the syntax makes it possible to define annotations and associations. The syntax and semantics basically match the general CDS concept.

➤ General Syntax Rules

The general syntax rules for the DDL and DCL for defining CDS objects in ABAP CDS are as follows:

Keywords

Keywords must be all uppercase, all lowercase, or in lowercase with an uppercase initial letter. Other mixes of uppercase and lowercase are not allowed.

Names

Names are not case-sensitive.
A name can have a maximum of 30 characters.
A name can consist of letters, numbers, underscores (_), and slashes (/).
A name must start with a letter, slash character, or underscore. Underscores are recommended as the naming convention for associations.
The separator for names with multiple parts is a period (.). Names with multiple parts can be paths, columns with a prefixed data source, and annotations.
The following CDS keywords cannot be used as names: ALL, AND, AS, ASSOCIATION, AVG, CASE, CAST, CROSS, COUNT, DISTINCT, EXISTS, EXTEND, FROM, FULL, GROUP, HAVING, INNER, JOIN, KEY, LEFT, MAX, MIN, NOT, NULL, ON, OR, ORDER, RIGHT, SELECT, SUM, UNION, VIEW, WHEN, WHERE

Literals

Numeric literals must always be specified in full and a decimal point (.) used as a decimal separator if necessary.
Character literals are enclosed in single quotation marks (').

Comments

Two forward slashes (//) or two hyphens (--) introduce a comment, which continues until the end of the line.
Comments within lines or that span multiple lines are enclosed by the characters /* and */.

Separators

Statements can be closed using a semicolon (;). This is optional.

Protected words

Certain keywords are protected and cannot be used as self-defined names. The reserved names that cannot be used are specified in the database table TRESE.

Note:

The closing semicolon after a statement is optional because one piece of CDS source code can currently only contain a single statement.

Examples

SELECT, select, and Select are all valid ways of specifying a keyword. seLect and SeLect, on the other hand, produce syntax errors.
MYVIEW, myview, and myView all identify the same operand.
0.5 is a valid numeric literal, but .5 is not.

➤ Language Elements

The following sections summarize the language elements of the DDL and DCL of the ABAP CDS, arranged by topics.

CDS Views
CDS View Enhancements
CDS Table Functions

CDS Roles

In addition to the language elements show here, CDS source code can also contain annotations with metadata.

1. DDL

1.1 CDS Views

Keywords and Additions

Language Element	Meaning
DEFINE VIEW ... AS	Defines a CDS view
WITH PARAMETERS	Defines input parameters of a CDS view
SELECT [DISTINCT] ... FROM	SELECT statement of a CDS view
INNER JOIN ... ON	Inner join in a SELECT statement
LEFT\|RIGHT OUTER JOIN ... ON	Outer join in a SELECT statement
ASSOCIATION ... TO ... AS ... ON	Defines an association for a path expression in a SELECT statement
1:	Attribute of a path expression
INNER ... WHERE	Attribute of a path expression
LEFT OUTER ... WHERE	Attribute of a path expression
KEY ... AS	Element of a SELECT list
$EXTENSION.*	Elements of an enhancement in a SELECT list
WHERE ...	WHERE clause of a SELECT statement
GROUP BY ...	GROUP-BY clause of a SELECT statement
HAVING ...	HAVING clause of a SELECT statement
UNION ALL ...	UNION clause of a SELECT statement

Expressions

Operators	Meaning
MAX, MIN, AVG, SUM, COUNT	Aggregate expression in a SELECT statement
+, -, *, /	Arithmetic expression in a SELECT statement
CASE, WHEN, THEN, ELSE, END	Case distinction in a SELECT statement
CAST	Cast expression in a SELECT statement
=, <>, <, >, <=, >=, BETWEEN, LIKE, IS NULL, NOT, AND, OR	Relational expression in a SELECT statement

Predefined Functions

Function	Meaning
ABS, CEIL, DIV, DIVISION, FLOOR, MOD, ROUND	Numeric function in a SELECT statement
CONCAT, CONCAT_WITH_SPACE, INSTR,LEFT, LENGTH, LPAD, LTRIM, REPLACE,RIGHT, RPAD, RTRIM, SUBSTRING	String function in a SELECT statement
BINTOHEX, HEXTOBIN	Byte string function in a SELECT statement
COALESCE	Coalesce function in a SELECT statement
UNIT_CONVERSION, CURRENCY_CONVERSION, DECIMAL_SHIFT
	Conversion functions in a SELECT statement
DATS_IS_VALID, DATS_DAYS_BETWEEN, DATS_ADD_DAYS, DATS_ADD_MONTHS	Date function in a SELECT statement
TIMS_IS_VALID	Time function in a SELECT statement
TSTMP_IS_VALID, TSTMP_CURRENT_UTCTIMESTAMP, TSTMP_SECONDS_BETWEEN, TSTMP_ADD_SECONDS	Time stamp function in a SELECT statement

1.2 CDS View Enhancements

Keywords and Additions

Language Element	Meaning
EXTEND VIEW ... WITH	Enhancement of a CDS view with an CDS view enhancement

1.3 CDS Table Functions

Keywords and Additions

Language Element	Meaning
DEFINE TABLE FUNCTION ... RETURNS ... IMPLEMENTED BY METHOD ...	Defines a CDS table function

2. DCL

2.1 CDS Roles

Keywords and Additions

Language Element	Meaning
DEFINE ROLE ... GRANT SELECT ON	Defines a CDS role
WHERE, AND, OR	WHERE clause in the definition of a CDS role
... = ASPECT pfcg_auth ...	Condition for mapping roles
COALESCE	Coalesce function in a SELECT statement
... =\|<>\|<\|>\|<=\|>=\|LIKE\|IS NULL ...	Literal condition

➤ Annotations

An annotation enriches a definition in the ABAP CDS with metadata. It can be specified for specific scopes of a CDS object, namely specific places in a piece of CDS source code. SAP uses a set of predefined SAP annotations.

➥ Syntax for Annotations

Syntax

... @annotation[.annotation1[.annotation2]...][: value| subannos|array] ...

... @<annotation[.annotation1[.annotation2]...][: value| subannos|array] ...

Effect

An annotation has a fixed syntax that dictates the following:

A simple or structured name annotation[.annotation1[.annotation2]...] after the characters @ or @<
One of the following optional alternatives specified after a colon (:):

Specified value value
Structuring of the annotation using subannotations subannos in curly brackets
Definition of an annotation array array in square brackets

In the ABAP CDS DDL, the names and the specified values are not dictated by the syntax. Annotations are evaluated by the framework in which a CDS entity is used. There is a set of SAP annotations predefined by SAP, comprising ABAP annotations evaluated by the ABAP runtime environment and component annotations evaluated by other frameworks. Only specific ABAP annotations, on the other hand, are allowed in the ABAP CDS DCL.

Example

The following CDS source code for defining a CDS view contains ABAP annotations and other annotations at the allowed positions, in other words, for the entire view, for an element of the SELECT list and for an input parameter. The ABAP annotations are EndUserText.label, AbapCatalog.sqlViewName, and ClientDependent for the full view, EndUserText.label and EndUserText.quickInfo for the element in the SELECT list, plus EndUserText.label and Environment.systemField for the input parameter param. The remaining annotations have freely defined names and are used as placeholders for any component annotations.

@EndUserText.label: 'Demo View with Annotations'

@AbapCatalog.sqlViewName: 'DEMO_VIEW_ANNOT'

@AccessControl.authorizationCheck: #NOT_REQUIRED

@ClientDependent: false

@v_annot0

@v_annot1:'abc'

@v_annot2:123

@v_annot3:[ 'abc', 123 ]

@v_annot4:{ annot0, annot1:'abc', annot2:123 }

@v_annot5.annot0

@v_annot5.annot1:'abc'

@v_annot5.annot2:123

@v_annot6:[ 'abc', 123,

[ 'abc', 123 ],

{ annot0, annot1:'abc', annot2:123 } ]

@v_annot7:{ annot0,

annot1:[ 'abc', 123 ],

annot2:{ annot0, annot1:'abc', annot2:123 } }

define view demo_cds_view_annotations

with parameters @p_annot1:'abc'

@p_annot2:123

@EndUserText.label:'Input Parameter'

param : SYST_UNAME

@<Environment.systemField:#USER

as select from demo_expressions

{ @f_annot0

key id as key_field

@<f_annot1:'abc'

@<f_annot2:123,

@EndUserText:{ label:'Some field', quickInfo:'Some info' }

@f_annot1:[ 'abc', 123 ]

num1 as some_field

@<f_annot2:{ annot0, annot1:'abc', annot2:123 }

}

The program DEMO_CDS_DDL_ANNOTATIONS access the associated meta data in the database tables DDHEADANNO, DDFIELDANNO, and DDPARAMETERANNO directly and using the methods of the classes CL_DD_DDL_ANNOTATION_SERVICE and CL_DD_DDL_ANALYZE and displays it. Note the following in particular:

The annotation v_annot3 is an array consisting of two elements, which are identified in the evaluation using the indexes $1$ and $2$.
v_annot4 and v_annot5 are specified in the same way. The structuring in v_annot4 is resolved into individual specifications as in v_annot5.
The annotation v_annot6 is an array, in which the third component (a nested square bracket) is ignored. The other elements are identified for evaluation using the indexes $1$, $2$, and $4$.

Unlike the table DDHEADANNO, the tables DDFIELDANNO and DDPARAMETERANNO for the elements and parameters also contain the name of the element or parameter for which an annotation was created.

1. ABAP CDS - Names for Annotations.

Syntax

... annotation ...

| annotation.annotation1.annotation2...

Effect

An annotation is introduced using the character @ or @< and has a simple name

... annotation ...

or a structured name

... annotation.annotation1.annotation2...

Here, any single names are separated by a period (.). The individual names annotation, annotation1, annotation2, ... can contain letters, digits, and underscores and must start with a letter. In structured names, annotation is the main annotation and annotation1, annotation2, ... are the subannotations. The full name of an annotation must be unique in the scope of the annotation.

@< is used to introduce annotations in comma-separated lists that are specified after a list element.

Apart from these formal rules, a name is not dictated in the syntax of the ABAP CDS DDL. However, the name of an annotation must follow the rules of the framework used for its evaluation.

SAP provides a predefined set of SAP annotations that distinguishes between ABAP annotations and component annotations:

The ABAP runtime environment evaluates every CDS object in ABAP CDS when it is activated and used. A set of ABAP annotations is employed here that expect certain values and are checked when activated. These ABAP annotations are listed in their specific scope in this documentation.
Software components can dictate component annotations that are evaluated by dedicated frameworks.

All other annotations are not usually evaluated, however it is possible that certain frameworks only allow certain annotations.

Only specific ABAP annotations are allowed in the ABAP CDS DCL.

Note: To create a group of structured names, subannotations can be specified in curly brackets after the colon (:) of an annotation.

2. ABAP CDS - Values Specified for Annotations

Syntax

... literal

| true|false

| #value

Effect

A value can be specified directly after the colon : of an annotation. However, an annotation does not have to contain a value. The following can be specified for the value:

Literals

Character literals or numeric literals enclosed in quotation marks

Truth values true and false

These values can be enclosed in quotation marks but do not have to be.

Enumeration values #value

Specific annotations expect preset values, which are specified directly and without quotation marks after the # character.

Apart from these formal rules, a value is not dictated in the syntax of the ABAP CDS DDL. Potential values are determined by the annotation and the framework used to evaluate it. The potential values for ABAP annotations and that are evaluated by the ABAP runtime environment (and sometimes evaluated when activated) are specified in the relevant scope in this documentation. The potential values of the SAP component annotations are specified in the documentation CDS Annotations.

Only specific ABAP annotations with their associated values are allowed in the ABAP CDS DCL.

3. ABAP CDS - Subannotations

Syntax

... { annotation1[:...], annotation2[:...], ... }

Effect

A comma-separated list of subannotations annotation1, annotation2, ... can be specified in curly brackets after the colon : of an annotation. These subannotations have the same syntax as every other annotation. The following can be done after the optional colon in every subannotation:

Values can be specified.
Further substructures can be created.
Arrays can be defined.

A subannotation list in curly brackets after an annotation annotation is a short form for multiple subannotations introduced using the same annotation. The list works in the same way as specifying the following single structured names:

annotation.annotation1[:...]

annotation.annotation2[:...]

...

Example

Specifies ABAP annotations with a structured name (introduced using the same main annotation AbapCatalog) as a list in curly brackets.

@AbapCatalog.buffering:{ status:... type:... }.

4. ABAP CDS - Annotation Arrays

Syntax

... [ value1| subannos1|array1, value2|subannos2|array2, ... ]

Effect

A comma-separated list of values, subannotations or other annotation arrays can be listed in square brackets after the colon : of an annotation. This type of list turns the annotation annotation specified before the colon into an array with elements specified in parentheses.

The specified values value1, value2, ... define elements, which the specified values are assigned to.
Subannotations subannos1, subannos2, ... in curly brackets define structured elements with one or more subannotations.
It is possible to specify annotation arrays array1, array2, ... in square brackets in the syntax, however this is currently ignored when the the annotations are evaluated.

An element of a structured annotation is an annotation for which the same syntax rules apply as for every other annotation. An element does not have an explicit name in the syntax, but is (internally) uniquely identified for the evaluation using an index appended to the name of the array. This also counts nested square brackets that are otherwise ignored by the evaluation.

Example

Annotation array annot with three elements, each of which are assigned a value. The elements can be evaluated using the name annot and their index (from 1 to 3).

@annot:[ 'a', 'b', 'c' ]

Example

Annotation array annot with three elements, which contain subannotations. The elements can be evaluated using the name annot and their index (from 1 to 3).

@annot:[ { annot1 },

{ annot2:{ s1, s2} },

{ annot3.s1, annot3.s2 } ]

The semantics are as follows:

The first element is an annotation with subannotation annot1 and without specified values.
The second element consists of two annotations with subannotations annot2.s1 and annot2.s2 without specified values. The subannotations are created by the structured annotation annot2.
The third element, like the second element, consists of two annotations with subannotations annot3.s1 and annot3.s2, which are explicitly specified here.

➥ Scopes for Annotations

Annotations can be specified for the following scopes in source code in ABAP CDS:

DDL:

View annotations for a CDS view

In front of the statement DEFINE VIEW

Extension annotations for a CDS view extension

In front of the statement EXTEND VIEW

Function annotations for a CDS table function

In front of the statement DEFINE TABLE FUNCTION

Parameter annotations for a parameter of a CDS view

In front of and after the parameter

Parameter annotations for a parameter of a CDS table function

In front of and after the parameter

Element annotations for an element of the SELECT list of a CDS view

In front of and after the element

Element annotations for an element in the element list of a CDS table function

In front of and after the element

DCL:

Role annotations for a CDS role

In front of the statement DEFINE ROLE

➥ Evaluation of Annotations

When an object defined in CDS source code is activated, the metadata defined by the annotations is saved in internal database tables in ABAP Dictionary. These tables can then be accessed to evaluate the data. This is done for every annotation with correct syntax regardless of name and value. ABAP annotations and component annotations are evaluated in different ways:

ABAP Annotations

ABAP annotations define technical and semantic attributes of a CDS object. They are usually evaluated for every CDS object when activated by the ABAP runtime environment. ABAP annotations can modify the behavior of Open SQL statement that access a CDS entity. One important example is how the client-dependency of a CDS entity is defined using the associated ABAP annotation.

ABAP annotations introduced using EndUserText are used to define translatable semantic texts for a CDS object. The value of an annotation like this is saved in special tables that have a language key and that are translatable. The value specified in the source code should consist of text in the original language of the CDS source code and is translated into the required languages. The methods of the class CL_DD_DDL_ANNOTATION_SERVICE read these texts in accordance with an input parameter for the language. There are also special methods GET_LABEL_... that are designed for these texts only.

Component annotations

The component annotations must be evaluated by the frameworks of the corresponding software components using a suitable API and are not relevant for activations and the ABAP runtime environment. Here, the names and values of these component annotations must follow the rules of the relevant framework. For SAP components, these can be taken from the tables of the SAP annotation documents.

The class CL_DD_DDL_ANNOTATION_SERVICE is provided for evaluations of the annotations of CDS entities. The method GET_ANNOTATIONS of the class CL_DD_DDL_ANALYZE also returns the annotations of CDS entities.
Annotations that are not evaluated by the ABAP runtime environment or by frameworks of other software components are usually ignored.

Note

The elements of annotation arrays are saved under the name of the array. A consecutive index enclosed in $ characters $1$, $2$, ... is appended to this array.

Example

The following CDS source code, which defines a CDS view, contains the specific ABAP annotations that are introduced using EndUserText.

@EndUserText.label: 'Demo View mit Texten'
@AbapCatalog.sqlViewName: 'DEMO_VIEW_TEXTS'
@AccessControl.authorizationCheck: #NOT_REQUIRED
define view demo_cds_text_annotations
with parameters @EndUserText.label:'Eingabeparameter'
param : abap.int4
as select from demo_expressions
{ @EndUserText:{ label:'Ein Element', quickInfo:'Feld' }
id }

The program DEMO_CDS_DDL_TEXTS uses methods of the class CL_DD_DDL_ANNOTATION_SERVICE to access the associated texts (in a language-dependent way). The original language of the view is German and the German texts must be available in every system. If an English translation exists, this is also read and displayed.

1. ABAP CDS - Evaluation of Annotations

This example demonstrates how semantics annotations in CDS source code are evaluated.

Source Code

REPORT demo_cds_semantics_annotation.

CLASS demo DEFINITION.
PUBLIC SECTION.
CLASS-METHODS main.
ENDCLASS.

CLASS demo IMPLEMENTATION.
METHOD main.
DATA incomplete_addresses TYPE STANDARD TABLE
OF demo_cds_semantics_annotation
WITH EMPTY KEY.

cl_dd_ddl_analyze=>get_annotations(
EXPORTING
ddlnames = VALUE #( ( 'DEMO_CDS_SEMANTICS_ANNOTATION' ) )
leaves_only = abap_true
IMPORTING
fieldannos = DATA(fieldannos) ).

TYPES field_anno LIKE LINE OF fieldannos.
DATA address_annos TYPE STANDARD TABLE OF field_anno-annoname
WITH EMPTY KEY.
address_annos = VALUE #(
( 'SEMANTICS.NAME.FULLNAME' )
( 'SEMANTICS.ADDRESS.STREET' )
( 'SEMANTICS.ADDRESS.CITY' )
( 'SEMANTICS.ADDRESS.ZIPCODE' )
( 'SEMANTICS.ADDRESS.COUNTRY' ) ).

DATA address_components TYPE STANDARD TABLE OF field_anno-fieldname
WITH EMPTY KEY.
address_components = VALUE #(
FOR address_anno IN address_annos
( VALUE #( fieldannos[ annoname = address_anno ]-fieldname
DEFAULT '---' ) ) ).

SELECT *
FROM demo_cds_semantics_annotation
INTO @DATA(address).
LOOP AT address_components INTO DATA(component).
ASSIGN COMPONENT component OF STRUCTURE address
TO FIELD-SYMBOL(<value>).
IF sy-subrc <> 0 OR <value> IS INITIAL.
incomplete_addresses = VALUE #( BASE incomplete_addresses
( address ) ).
EXIT.
ENDIF.
ENDLOOP.
ENDSELECT.

cl_demo_output=>display( incomplete_addresses ).
ENDMETHOD.
ENDCLASS.

START-OF-SELECTION.
demo=>main( ).

Description

This program uses a simple example to show how annotations can be evaluated in a framework. All rows in a CDS entity are to be found that do not contain a fully specified address. Here, a fully specified address is simply a set of elements for name, street, city, postal code, and country, none of which can be empty.

To do this, the program uses cl_dd_ddl_analyze=>get_annotations to read the element annotations of a CDS entity and gets the names of the elements defined (using semantics annotations) as the required components of an address in the internal table address_components. In the next step, the CDS entity is read using SELECT and a dynamic ASSIGN statement is used to check whether all required elements have a non-initial value for each read row. The output consists of any rows that do not contain a full address.

The following CDS view is used as an example for a CDS entity:

@AbapCatalog.sqlViewName: 'DEMO_CDS_SEMANNO'
@AccessControl.authorizationCheck: #NOT_REQUIRED
define view demo_cds_semantics_annotation
as select from scustom
{ id,
@Semantics.name.fullName
name,
@Semantics.name.prefix
form,
@Semantics.address.street
street,
@Semantics.address.postBox
postbox,
@Semantics.address.zipCode
postcode,
@Semantics.address.city
city,
@Semantics.address.country
country,
@Semantics.address.subRegion
region,
@Semantics.contact.type
custtype,
@Semantics.language
langu,
@Semantics.eMail.address
email }

This view wraps the database table SCUSTOM, which contains address data. The assignment of the semantics annotations to the columns of the database table gives the columns semantics that can be evaluated. Previously, this was only provided by those names and data elements that are no longer relevant for the evaluation depicted here.

➥ SAP Annotations

SAP annotations are annotations specified by SAP. When specified by SAP, an annotation must have the following:

the name
the possible values
the structure consisting of subannotations
the structure consisting of annotation arrays

SAP annotations are evaluated by SAP frameworks and can be one of the following two types: ABAP annotations or component annotations. ABAP annotations are evaluated when the object defined in the DDL source code is activated or when the object is used in the ABAP runtime environment. Component annotations, on the other hand, are evaluated by frameworks of other software components. An ABAP annotation can also be evaluated by other software components. Any application annotations that are not evaluated by a framework are ignored.

The following tables are a compilation of SAP annotations in the ABAP CDS DDL.

Annotations for which the component "ABAP" is entered in the "Framework" column are evaluated as ABAP annotations by the ABAP runtime environment. The precise semantics of these annotations are described under the scope in question in the documentation.
Annotations for which a different component is entered in the "Framework" column are component annotations. The component defines technical and semantic attributes of CDS objects required by specific software components, such as ODATA, UI, and Analytics. The documentation CDS Annotations describes the meaning of component annotations, which SAP component is evaluated by these annotations, and the permitted values for these annotations.

If square brackets [ ] are specified after a name in square brackets in the "Annotation" column, this means that the annotation before the square brackets is an annotation array and the element after the square brackets belongs to this element. The notation in the CDS source code compiles the elements in the square brackets

1. ABAP CDS, Annotation Array

This example shows how an annotation array is evaluated in a piece of CDS source code.

Source Code

REPORT demo_cds_annotation_array.

CLASS demo DEFINITION.
PUBLIC SECTION.
CLASS-METHODS main.
ENDCLASS.

CLASS demo IMPLEMENTATION.
METHOD main.
cl_dd_ddl_analyze=>get_annotations(
EXPORTING ddlnames = VALUE #( ( 'DEMO_CDS_ANNOTATION_ARRAY' ) )
leaves_only = abap_true
IMPORTING
fieldannos = DATA(annos) ).
cl_demo_output=>display( annos ).
ENDMETHOD.
ENDCLASS.

START-OF-SELECTION.
demo=>main( ).

Description

The program reads the element annotations of the following CDS view:

@AbapCatalog.sqlViewName: 'DEMO_CDS_ANNOARR'
define view demo_cds_annotation_array
as select from demo_expressions
{ @Consumption.filter.hierarchyBinding:
[ { type: '...', value: '...', variableSequence: '...' },
{ type: '...', value: '...', variableSequence: '...' } ] id }

An annotation array Consumption.filter.hierarchyBinding with two elements is assigned to the view field ID and each of the elements is structured using three subannotations type, value, and variableSequence.

The annotation array is a component annotation defined by SAP and specified in the following form in the table for consumption annotations: