PUBLIC

SAP HANA Platform SPS 12

Document Version: 1.2 – 2018-01-24

SAP HANA Developer Guide

For SAP HANA Web Workbench
Content

1 SAP HANA Developer Guide for SAP HANA Web-Based Development Workbench. . . . . . . . . . . 6

2 SAP HANA Web-Based Development Workbench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.1 SAP HANA Web-based Development Workbench: Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Editor Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Text Editing Keyboard Shortcuts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Toolbar and Context-Menu Options in the Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2 SAP HANA Web-based Development Workbench: Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Catalog Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
SQL Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
SQL Result Table and Data Preview Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.3 SAP HANA Web-based Development Workbench: Trace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Trace Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Database Trace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
SQL Trace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Plan Trace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3 Getting Started with Application Development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

3.1 Tutorial: Create a Simple SAPUI5 Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.2 Tutorial: Create and Debug a Server-side JavaScript Application. . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.3 Maintaining Repository Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Repository Package Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Define Repository Package Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Create Repository Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Delete Repository Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.4 Creating the Application Descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Define the Application Root Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Enable Access to the Application Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Define Application Access Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.5 Maintaining Application Artifacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Design-Time Application Artifacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
File Versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
3.6 Storing Source Code on GitHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.7 Maintaining Application Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Set up Application Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Set up Application Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.8 Maintaining HTTP Destinations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

SAP HANA Developer Guide

2 PUBLIC Content
 Tutorial: Create an HTTP Destination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
HTTP Destination Configuration Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
The HTTP Destination Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Tutorial: Create an OAuth Configuration Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

4 Setting up the Persistence Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

4.1 Creating the Persistence Model in Core Data Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Tutorial: Get Started with CDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Create a CDS Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Create an Entity in CDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Create a User-Defined Structured Type in CDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Create an Association in CDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Create a View in CDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Modifications to CDS Artifacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
Tutorial: Import Data with CDS Table Import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Migrate an Entity from HDBTable to CDS (hdbdd). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
4.2 Creating the Persistence Model with HDBTable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Create a Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Tutorial: Create a Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Create a Reusable Table Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Create an SQL View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Create a Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238
Create a Synonym. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Tutorial: Import Data with HDBTable Table Import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

5 Developing Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264

5.1 Create and Edit Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Define and Use Table Types in Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Tutorial: Create an SQLScript Procedure that Uses Imperative Logic. . . . . . . . . . . . . . . . . . . . . 269
5.2 Tutorial: Create a Scalar User-Defined Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
5.3 Tutorial: Create a Table User-Defined Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
5.4 SQLScript Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
5.5 Debugging Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Debug Privileges for Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Assign the DEBUG Privilege. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Assign the ATTACH DEBUGGER Privilege . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Debug Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Debug an External Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

6 Defining Web-based Data Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

6.1 Data Access with OData in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
OData in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

SAP HANA Developer Guide

Content PUBLIC 3
 Tutorial: Use the SAP HANA OData Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Define the Data an OData Service Exposes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Create an OData Service Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
OData Service Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
OData Service-Definition Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
OData Service Definition Language Syntax (XS Advanced). . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
OData Service Definition: SQL-EDM Type Mapping (XS Advanced). . . . . . . . . . . . . . . . . . . . . . 321
OData Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
OData Batch Requests (XS Advanced). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
6.2 Data Access with XMLA in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
XML for Analysis (XMLA). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Tutorial: Use the SAP HANA XMLA Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
Define the Data an XMLA Service Exposes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Create an XMLA Service Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
XMLA Service Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
XMLA Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Multidimensional Expressions (MDX). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .332
MDX Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
MDX Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .335
6.3 Using the SAP HANA REST API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
SAP HANA REST Info API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
SAP HANA REST File API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
SAP HANA REST Change-Tracking API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
SAP HANA REST Metadata API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
SAP HANA REST Transfer API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
SAP HANA REST Workspace API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

7 Writing Server-Side JavaScript Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351

7.1 Data Access with JavaScript in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
7.2 Using Server-Side JavaScript in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Tutorial: Write Server-Side JavaScript Application Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352
JavaScript Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Displaying the Function Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Getting Immediate Feedback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Server-Side JavaScript Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
7.3 Using Server-Side JavaScript Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Import Server-Side JavaScript Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Write Server-Side JavaScript Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
7.4 Using the Server-Side JavaScript APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Tutorial: Use the XSJS Outbound API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Tutorial: Call an XS Procedure with Table-Value Argument. . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Tutorial: Query a CDS Entity using XS Data Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

SAP HANA Developer Guide

4 PUBLIC Content
 Tutorial: Update a CDS Entity Using XS Data Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
7.5 Creating Custom XS SQL Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Create an XS SQL Connection Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
The SQL Connection Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
SQL Connection Configuration Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .408
7.6 Setting the Connection Language in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
7.7 Scheduling XS Jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Tutorial: Schedule an XS Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Add or Delete a Job Schedule during Runtime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
7.8 Tracing Server-Side JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .422
Tutorial: Trace a Server-Side JavaScript Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
7.9 Debugging Server-Side JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Tutorial: Create and Debug a Server-side JavaScript Application. . . . . . . . . . . . . . . . . . . . . . . .425
XSJS Debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
XSJS Debugger Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Debug Session Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
7.10 Testing XS JavaScript Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Automated Tests with XSUnit in SAP HANA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Application Development Testing Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Test an SAP HANA XS Application with XSUnit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Testing JavaScript with XSUnit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

8 Building UIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

8.1 Building User Interfaces with SAPUI5 for SAP HANA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
8.2 Consuming Data and Services with SAPUI5 for SAP HANA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
8.3 SAPUI5 for SAP HANA Development Tutorials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Tutorial: Create a Hello-World SAPUI5 Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Tutorial: Consume an XSJS Service from SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Tutorial: Consume an OData Service from SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Tutorial: Consume an OData Service with the CREATE Option. . . . . . . . . . . . . . . . . . . . . . . . . 469

9 Setting Up Roles and Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

9.1 Create a Design-Time Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
Change a Design-Time Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .478
Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .491
9.2 Run the File Access Check for Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
9.3 Creating Analytic Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .511
Create SQL Analytic Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Create Classical XML-Based Analytic Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Analytic Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

SAP HANA Developer Guide

Content PUBLIC 5
1 SAP HANA Developer Guide for SAP
HANA Web-Based Development
Workbench

This guide explains how to build applications using SAP HANA, including how to model data, how to write
procedures, and how to build application logic in SAP HANA Extended Application Services, classic model.

The SAP HANA Developer Guide for SAP HANA Web Workbench explains the steps required to develop, build,
and deploy applications that run in the SAP HANA XS classic model run-time environment using the tools
provided with the browser-based SAP HANA Web-based Workbench. It also describes the technical structure
of applications that can be deployed to the XS classic run-time platform. The information in the guide is
organized as follows:

● Introduction and overview

A high-level overview of the basic capabilities and architecture of SAP HANA XS classic model. This section
also includes an information map, which is designed to help you navigate the library of information
currently available for SAP HANA developers.
● Getting started
A collection of tutorials which are designed to demonstrate how to develop, build. and deploy a simple SAP
HANA-based application on SAP HANA XS classic model quickly and easily
● The development process
Step-by-step information that shows in detail how to develop the various elements that make up an XS
classic application. The information provided uses tasks and tutorials to explain how to develop the SAP
HANA development objects. Where appropriate, you can also find background information that explains
the context of the task, and reference information that provides the detail you need to adapt the task-
based examples to suit the requirements of your application environment.

SAP HANA Developer Guide

6 PUBLIC SAP HANA Developer Guide for SAP HANA Web-Based Development Workbench
2 SAP HANA Web-Based Development
Workbench

SAP HANA Extended Application Services (SAP HANA XS) provides the SAP HANA Web-based Development
Workbench that you can use to build and test development artifacts in the SAP HANA environment.

The SAP HANA Web-based Development Workbench allows you to develop entire applications in a Web
browser without having to install any development tools and is therefore a quick and easy alternative to using
the SAP HANA studio for developing native applications for SAP HANA XS. It provides an intuitive user
interface and simplifies development by providing many convenient functions. For example, it includes a wizard
for creating applications and automatically generates the application descriptors (the .xsapp and .xsaccess
files) that SAP HANA applications are required to have.

The SAP HANA Web-based Development Workbench is available on the SAP HANA XS Web server at the
following URL:

http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide

Note
The SAP HANA Web-based Development Workbench supports Microsoft Internet Explorer (10+), Mozilla
Firefox, and Google Chrome Web browsers.

Required Roles

Before you start using the SAP HANA Web-based Development Workbench, the SAP HANA administrator must
set up a user account for you in the database and assign the developer roles you require for the specific tools:

Tool Description Required Role

Editor Inspect, create, change, delete and activate SAP HANA re­ sap.hana.ide.roles::EditorDeveloper
pository objects

Debug server-side JavaScript code sap.hana.xs.debugger::Debugger

Catalog Create, edit, execute and manage SQL catalog artifacts in sap.hana.ide.roles::CatalogDeveloper
the SAP HANA database

Security Create users and user roles sap.hana.ide.roles::SecurityAdmin

Traces View and download SAP HANA trace files and set trace lev­ sap.hana.ide.roles::TraceViewer
els

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 7
Tool Description Required Role

Note
The parent role sap.hana.ide.roles::Developer allows you to use all tools included in the SAP HANA Web-based Develop­
ment Workbench. To use the debugging features, however, you also need to be assigned the
sap.hana.xs.debugger::Debugger role.

Related Information

SAP HANA Web-based Development Workbench: Editor [page 8]

SAP HANA Web-based Development Workbench: Catalog [page 18]
SAP HANA Web-based Development Workbench: Trace [page 26]

2.1 SAP HANA Web-based Development Workbench: Editor

SAP HANA Web-based Development Workbench includes an all-purpose editor tool that enables you to
maintain and run design-time objects in the SAP HANA Repository.

The Editor component of the SAP HANA Web-based Development Workbench provides a browser-based
environment for developing SAP HANA Extended Services (SAP HANA XS) repository artifacts. To use the
Editor you must have the privileges granted by the role sap.hana.ide.roles::EditorDeveloper or the parent role
sap.hana.ide.roles::Developer.

Note
The Web-based Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor

SAP HANA Developer Guide

8 PUBLIC SAP HANA Web-Based Development Workbench
The figure below shows the main features of the Editor tool:

Feature Overview

In addition to the basic functions of creating, editing, and executing repository objects, the Editor provides
additional features, which are described briefly in the table below.

Feature Description

Multi-file drop zone You can upload multiple files at once to a repository package by dragging and dropping the se­
lected files (from your desktop, for example) into the area marked as the multi-file drop zone.
The multi-file drop zone is visible when a package is selected in the package tree.

Multiple editors You can open multiple editor tabs or you can open an editor as its own browser tab.

File history The tabs (files) you opened during your last session will reopen when you log in to a new ses­
sion.

File shortcuts You can use shortcuts to open files.

Version history You can view a list of file versions, compare one version of a file with another one, and revert a
file to a previous version.

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 9
Feature Description

Templates You can use templates for standard SAP HANA XS applications, including SAPUI5 applications
and SAP Fiori applications. You can also use code snippet templates for individual files, such
as .hdbtable, .hdbschema, .xsjs, .xsodata, and .hdbprocedure files.

Automatic syntax high­ Syntax highlighting of source code, code completion options, and checks for syntax errors are
lighting and code com­ available for most artifact types.
pletion

ESLint code checks The JavaScript editor includes the ESLint validation tool, which highlights any code that does
not conform to ESLint standards. You can configure or disable the check in the editor settings.

Inactive save and object You can save and execute an inactive version of your artifact before activating it to make it avail­
execution able for others to use. You can enable this functionality in the editor settings.

Direct testing You can test html pages and XSJS services directly from the editor in the browser. The applica­
tion preview allows you to test HTML pages with various form factors.

Tip
The direct-testing feature adds a timestamp as a URL parameter to bypass caching. How­
ever, internal Ajax calls in your application might be cached by the browser. Try clearing the
browser-specific cache if you do not immediately see your changes reflected on execution.

Debugging You can use the integrated debugging features to debug your application. Note that to be able
to use the debugging features, you need to be assigned the sap.hana.xs.debugger::Debugger
role.

Immediate feedback This option lets you inspect the execution of an xsjs function, including execution times for SQL
queries.

Function flow A code flow visualizer that shows you which JavaScript functions are called in a file and allows
you to navigate between them.

JSDoc You can generate JSDoc documentation for XSJS, XSJSLIB, and JS files.

Related Information

Editor Settings [page 10]

Text Editing Keyboard Shortcuts [page 13]
Toolbar and Context-Menu Options in the Editor [page 15]
Design-Time Application Artifacts [page 69]

2.1.1 Editor Settings

Set your preferences for working with the Editor tool of the SAP HANA Web-based Development Workbench.

You can open the Editor Settings dialog box by choosing (Settings) in the toolbar.

SAP HANA Developer Guide

10 PUBLIC SAP HANA Web-Based Development Workbench
Text Editor Font Size and Background Color

Configure the appearance of the text editor on the General tab.

Option Description

Editor font size Use the slider to adjust the font size.

Editor background dark Select this checkbox to change the background color of the text editor to black.

Code Check

Configure the ESLint code check, which is included in the JavaScript editor, on the General tab.

Option Description

Code check level Select a new code check level or disable the code check entirely by selecting Disable.

Disable code check on Select this checkbox so the code check is not triggered every time you make a change to your
change code.

Inactive Save and Inactive Object execution

Enable these features on the General tab to be able to save and execute inactive versions of your artifacts
before activating them to make them available for others to use.

Option Description

Enable inactive save Lets you save inactive versions of an object.

The Save without Activating option will be enabled in the editor:

● As a toolbar button

● From the Menu ( Menu File Save without Activating )

Enable inactive object execution Lets you run inactive versions of an object.

Note
In the version history of any file that has an inactive version, the inactive version is marked with [l] and is
listed above the active versions. You can compare the inactive version with other versions.

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 11
Debug Session

Select a debug session when you want to debug JavaScript (XSJS and XSJSLIB) code from a different session
(for example, a different application or browser instance). The debugger will be connected to the selected
session.

Option Description

Session to debug The session you want to use for debugging JavaScript (XSJS and XSJSLIB) files.

Auto-Save

On the Auto-Save tab, you can enable the auto-save feature to automatically save the editor state to the local
browser cache at preset intervals. Use this option to avoid losing work due to server session timeout, browser
crash, or accidental closure.

Option Description

Enable client-side auto-save Select this checkbox to save changes in all open files automatically at regular intervals.

Set auto-save frequency Select how frequently files should be auto-saved.

Changes in all open files will be saved automatically at the chosen interval and when­
ever you close a file or switch to another tab.

Caution
● All cached file contents are stored unencrypted in the browser's local storage and can therefore be
viewed by anyone else using the computer.
● The cache will be cleared as soon as you disable the auto-save option.

Note
In the version history of any file that has a locally cached version, the locally cached version is marked with
[L] and is listed above the inactive version and active versions. You can compare the locally cached version
with other versions and restore it.

SQL Result

On the SQL Execution tab, use the following options to determine how SQL query results are displayed in the
result table on the Result tab of the SQL console.

SAP HANA Developer Guide

12 PUBLIC SAP HANA Web-Based Development Workbench
Option Description

Limit for LOB columns Enter the limit in bytes for LOB columns displayed in the result table. Values exceeding this limit
(bytes) will be truncated.

Representation of null Change the character used to represent NULL values in the result table. The default value is "?".
values

Maximum result size Enter the maximum number of records to be fetched from the database and displayed in the re­
sult table.

Related Information

File Versions [page 72]

2.1.2 Text Editing Keyboard Shortcuts

In the editor, you can use common shortcut key codes to make quick edits in open files. Whether a feature is
supported depends on the artifact type.

Action PC (Windows/Linux) Mac

Add multi-cursor above CTRL + ALT + UP ARROW CTRL + Option + UP ARROW

Add multi-cursor below CTRL + ALT + DOWN ARROW CTRL + Option + DOWN ARROW

Add next occurrence to multi-selection CTRL + ALT + RIGHT ARROW CTRL + Option + RIGHT ARROW

Add previous occurrence to multi- CTRL + ALT + LEFT ARROW CTRL + Option + LEFT ARROW
selection

Copy CTRL + C Command + C

Copy lines up ALT + SHIFT + UP ARROW Command + Option + UP ARROW

Copy lines down ALT + SHIFT + DOWN ARROW Command + Option + DOWN ARROW

Cut CTRL + X Command + X

Duplicate selection CTRL + SHIFT + D Command + SHIFT + D

Find CTRL + F Command + F

Find next CTRL + K Command + G

Find previous CTRL + SHIFT + K Command + SHIFT + G

Fold selection ALT + L , CTRL + F1 Command + Option + L , Command

+ F1

Go to line CTRL + L Command + L

Go to matching bracket CTRL + P

Go to start CTRL + HOME Command + HOME , Command + UP

ARROW

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 13
Action PC (Windows/Linux) Mac

Go to word left CTRL + LEFT ARROW Option + LEFT ARROW

Go to word right CTRL + RIGHT ARROW Option + RIGHT ARROW

Indent line TAB TAB

Make uppercase CTRL + U CTRL + U

Make lowercase CTRL + SHIFT + U CTRL + SHIFT + U

Move lines up ALT + UP ARROW Option + UP ARROW

Move lines down ALT + DOWN ARROW Option + DOWN ARROW

Move multicursor from current line to CTRL + ALT + SHIFT + UP ARROW CTRL + Option + SHIFT + UP
the line above ARROW

Move multicursor from current line to CTRL + ALT + SHIFT + DOWN CTRL + Option + SHIFT + DOWN
the line below ARROW ARROW

Outdent line SHIFT + TAB SHIFT + TAB

Paste CTRL + V Command + V

Redo CTRL + Y Command + SHIFT + Z , Command +

Y

Remove current occurrence from CTRL + ALT + SHIFT + RIGHT CTRL + Option + SHIFT + RIGHT
multi-selection and move to next ARROW ARROW

Remove current occurrence from CTRL + ALT + SHIFT + LEFT CTRL + Option + SHIFT + LEFT
multi-selection and move to previous ARROW ARROW

Remove line CTRL + D Command + D

Remove to line end ALT + DEL CTRL + K

Remove to line start ALT + BACKSPACE Command + BACKSPACE

Remove word left CTRL + BACKSPACE Option + BACKSPACE , CTRL +

Option + BACKSPACE

Remove word right CTRL + DEL Option + DEL

Replace CTRL + H Command + Option + F

Select all text CTRL + A Command + A

Select down SHIFT + DOWN ARROW SHIFT + DOWN ARROW

Select left SHIFT + LEFT ARROW SHIFT + LEFT ARROW

Select line end SHIFT + END SHIFT + END

Select line start SHIFT + HOME SHIFT + HOME

Select page down SHIFT + PAGE DOWN SHIFT + PAGE DOWN

Select page up SHIFT + PAGE UP SHIFT + PAGE UP

Select right SHIFT + RIGHT ARROW SHIFT + RIGHT ARROW

Select to end CTRL + SHIFT + END Command + SHIFT + DOWN ARROW

Select to line end ALT + SHIFT + RIGHT ARROW Command + SHIFT + RIGHT ARROW

SAP HANA Developer Guide

14 PUBLIC SAP HANA Web-Based Development Workbench
Action PC (Windows/Linux) Mac

Select to line start ALT + SHIFT + LEFT ARROW Command + SHIFT + LEFT ARROW

Select to matching bracket CTRL + SHIFT + P

Select to start CTRL + SHIFT + HOME Command + SHIFT + UP ARROW

Select up SHIFT + UP ARROW SHIFT + UP ARROW

Select word left CTRL + SHIFT + LEFT ARROW Option + SHIFT + LEFT ARROW

Select word right CTRL + SHIFT + RIGHT ARROW Option + SHIFT + RIGHT ARROW

Split line CTRL + O

Transpose letters CTRL + T CTRL + T

Toggle line comment CTRL + / Command + /

Toggle block comment CTRL + SHIFT + /

Toggle show invisibles CTRL + I

Undo CTRL + Z Command + Z

Unfold ALT + SHIFT + L , CTRL + SHIFT Command + Option + SHIFT + L ,

+ F1 Command + SHIFT + F1

2.1.3 Toolbar and Context-Menu Options in the Editor

The SAP HANA Web-based Development Workbench Editor provides quick access to a variety of useful
developer tools.

Toolbar

The Editor toolbar provides the following options.

Icon Option Description

Settings Opens the dialog box for maintaining editor settings, such as inactive
save and object execution, auto-save, and the ESLint code check.

Navigation Links Provides direct navigation to other tools: Catalog, Security, Trace,
Lifecycle Management

Menu Provides a dropdown menu with file, edit, search, view, and tools
menu options

Find File Searches within the Content tree for the specified file. The search in­
cludes both inactive and activated artifacts. The file name is case
sensitive.

Save/Save without Activat­ Saves an active or inactive version of a file

/ ing

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 15
Icon Option Description

Insert Snippet Inserts the appropriate code snippets and templates for the selected
artifact type

Format Formats the source code

Run Runs HTML pages and XSJS services directly in the browser, and al­
lows you to test HTML pages with various form factors in an applica­
tion preview

Assign Execution Authoriza­ Assigns schema privileges to your user, by default, EXECUTE, SE­
tion LECT, INSERT, UPDATE, and DELETE

Maintain Credentials/ Goes directly to the related runtime configuration in the SAP HANA
Details XS Administration Tool, such as security and authentication, XS jobs,
and HTTP destinations

Show Function Flow Shows an outline view of all functions in the selected file

Show Immediate Feedback Opens a panel for inspecting the execution of an XSJS function, in­
cluding execution times for SQL queries

Show/Hide SQL Result Shows or hides the result table displayed for SQL queries

Context Menu

Some additional tools and features that are available in the context-sensitive menu for the different artifact
types are listed in the table below.

Menu Option Description

Packages

New -> File/Package/Role/Calculation Create a new object in the selected package.

View/Analytic Privilege/Flow Graph/
ReplicationTask/HDB Procedure

Import -> File Import a file from your local file system to the selected package.

Import -> Archive Import an archive (ZIP) from your local file system to the selected package.

Export Package Download the package as a ZIP file to your local file system.

Delivery Unit -> Assign Assign the selected delivery unit to the package and sub-packages (optional).

Delivery Unit -> Unassign Unassign the delivery unit from the selected package and sub-packages.

Change Package Attributes Display and edit details of the selected package, for example, the package de­
scription and the person responsible for the package’s creation and mainte­
nance.

Create Application Create an SAP HANA XS application using a standard template (use the empty
template if you just want to generate the application descriptors).

Synchronize with Github Synchronize changes made to local file versions with the versions of the files on
GitHub.

SAP HANA Developer Guide

16 PUBLIC SAP HANA Web-Based Development Workbench
Menu Option Description

Activate All Generate catalog object versions for all inactive artifacts in the currently se­
lected package.

Force Delete Use force delete when normal deletion is prevented due to the package contain­
ing inactive objects from a workspace that is not the standard workspace used
by the SAP HANA Web-based Development Workbench. The files in the other
workspaces will be deleted as well.

Search Text Search for specific text within files contained in your package structure and op­
tionally replace with other text.

The search results are displayed in a separate panel, where each row represents
a file in which the search string was found. Click a row multiple times to cycle
through the occurrences in a file. To replace text, use the Previous hit, Next hit,
Replace, and Replace all buttons.

Generate JSDoc Generate JSDoc documentation for XSJS, XSJSLIB, and JS files contained in the
selected package.

Packages and Files

Delete Delete the selected artifact.

Copy Shortcut Open the shortcut dialog box to copy the file shortcut.

Cut, Copy, Paste Cut and paste or copy and paste the selected artifact at the location you require
in the package structure. Manually correct inconsistencies resulting from this
action.

Rename Rename the selected package or file. Manually correct inconsistencies resulting
from the renaming.

Files

Open With -> Code Editor Open the selected file in the appropriate editor.

Versions Display the complete list of file versions available for the selected item. Right-
click an entry in the history list to compare two versions of the file or restore a
file version.

Activate Generate a catalog object version for the currently selected inactive artifact.
When you activate an artifact, the XS repository also tries to activate dependent
objects.

Activate without Cascade Activate the selected artifact only. This is useful for artifacts that have depend­
encies to others, in particular where there are complex dependency chains.

Revert Restore the latest active version of the file. In cut-and-paste cases, the file does
not have an active version so far and is therefore just deleted.

Related Information

Design-Time Application Artifacts [page 69]

Enabling the Text Search [page 18]

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 17
2.1.3.1 Enabling the Text Search

The text search functionality requires the full-text index queues to be active. The queues are, by default, active
initially. As an administrator, you can check the status of the queues and restart them, if necessary, using the
commands listed below.

Use the M_FULLTEXT_QUEUES view to check the full-text index queue status and SYS.FULLTEXT_INDEXES to
view the configuration of a full-text index.

Command

SELECT * FROM M_FULLTEXT_QUEUES;

SELECT * FROM SYS.FULLTEXT_INDEXES;

SELECT * FROM SYS.M_FULLTEXT_QUEUE_DOCUMENTS_;

Use the ALTER FULLTEXT INDEX statement to suspend or reactivate the queue.

Command

ALTER FULLTEXT INDEX "_SYS_REPO"."FTI_ACTIVE_OBJECT_CDATA" SUSPEND QUEUE;

ALTER FULLTEXT INDEX "_SYS_REPO"."FTI_ACTIVE_OBJECT_CDATA" ACTIVATE QUEUE;

ALTER FULLTEXT INDEX "_SYS_REPO"."FTI_ACTIVE_CONTENT_TEXT_CONTENT_CONTENT" SUSPEND QUEUE;

ALTER FULLTEXT INDEX "_SYS_REPO"."FTI_ACTIVE_CONTENT_TEXT_CONTENT_CONTENT" ACTIVATE QUEUE;

ALTER FULLTEXT INDEX "_SYS_REPO"."FTI_ACTIVE_OBJECT_TEXT_CONTENT_CONTENT" SUSPEND QUEUE;

ALTER FULLTEXT INDEX "_SYS_REPO"."FTI_ACTIVE_OBJECT_TEXT_CONTENT_CONTENT" ACTIVATE QUEUE;

Related Information

M_FULLTEXT_QUEUES
FULLTEXT_INDEXES

2.2 SAP HANA Web-based Development Workbench:

Catalog

SAP HANA Web-based Development Workbench includes a catalog tool that enables you to develop and
maintain SQL catalog objects in the SAP HANA database.

The Catalog component of the SAP HANA Web-based Development Workbench contains the database objects
that have been activated, for example, from design-time objects or from SQL DDL statements. The objects are
divided into schemas, which is a way to organize activated database objects. To use the Catalog you must have
the privileges granted by the role sap.hana.ide.roles::CatalogDeveloper or the parent role
sap.hana.ide.roles::Developer.

SAP HANA Developer Guide

18 PUBLIC SAP HANA Web-Based Development Workbench
 Note
The Web-based Catalog tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/catalog

Feature Overview

In addition to the basic tools for creating, editing, and executing database objects, the Catalog provides
additional features, which are described briefly in the table below.

Feature Description

Catalog objects The catalog browser allows you to import and export catalog objects, filter on the catalog tree,
search for specific catalog objects, and display a where-used list.

Favorites You can save your frequently used objects for easier access.

Shortcuts You can use shortcuts to open files.

SQL console You can execute SQL statements (such as CREATE, SELECT, INSERT, UPDATE, DELETE,
GRANT). You can also generate SQL statements, for example, to create, select, or insert entries
in database tables or invoke procedures or functions.

You can open, save, and download SQL files.

Code completion In the SQL editor you can use the semantic code completion feature, a context-based search
tool that lists suggested catalog objects and local variables.

Definition view Displays the definition of runtime objects, for example, stored procedures, functions, tables, or
views.

Content view Displays the content of tables or views. You have additional options, such as copying rows or
cells, changing layouts, and exporting data as csv files.

Debugging The SQL debugger allows you to set breakpoints in the runtime object and call it from the SQL
console.

Performance analysis The performance analysis option allows you to acquire performance measurement data while
executing a SQL statement to assess whether a SQL statement is problematic.

Provisioning Administrator tools for managing remote data sources.

Related Information

Catalog Settings [page 20]

SQL Console [page 22]
SQL Result Table and Data Preview Table [page 24]
Tutorial: Create a Table [page 221]
Debugging Procedures [page 278]

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 19
2.2.1 Catalog Settings

Set your general preferences for working with the Catalog tool of the SAP HANA Web-based Development
Workbench.

You can open the Settings dialog box by choosing (Settings) in the toolbar.

Text Editor Font Size and Background Theme

Configure the appearance of the SQL editor.

Option Description

Editor font size Use the slider to adjust the font size.

Editor background Select one of the following themes:

SAP Cumulus (bright theme)

Example:

SAP Basement (dark theme with reduced luminosity)

Example:

SAP Morlock (dark theme, but more colorful and vivid than SAP Basement)

Example:

Auto-Save

Enable the auto-save feature to automatically save SQL console contents to the local browser cache.

Option Description

Auto-save SQL console to local Select this checkbox to automatically save SQL console contents to the local storage.

SAP HANA Developer Guide

20 PUBLIC SAP HANA Web-Based Development Workbench
 Caution
● All cached file contents are stored unencrypted in the browser's local storage and can therefore be
viewed by anyone else using the computer.
● The cache will be cleared as soon as you disable the auto-save option.

SQL Result and Data Preview

Use the following options to determine how SQL query results are displayed in the result table on the Result tab
of the SQL console and in the data preview table.

Option Description

Limit for LOB Columns Enter the limit in bytes for LOB columns displayed in the result table and data preview table.
(Bytes) Values exceeding this limit will be truncated.

Representation of Null Change the character used to represent NULL values in the result table and data preview table.
Value The default value is "?".

Maximum Result Size Enter the maximum number of records to be fetched from the database and displayed in the
result table and data preview table.

Browser

Use the following option to retrieve a limited number of objects in the catalog browser.

Option Description

Limit the number of ob­ Enter the maximum number of objects to be displayed by the browser.
jects to retrieve
For example, if you enter 10, a maximum of 10 schemas will be displayed and under each
schema a maximum of 10 tables, 10 procedures, 10 table types, and so on.

If the number of available objects exceeds the number specified here, the message Object
limit <number> reached appears.

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 21
2.2.2 SQL Console

The SQL console provides an SQL editor that allows you to work with SQL statements. You can enter, execute,
and analyze SQL statements in the SQL console.

Opening the SQL Console

You can open the SQL console in the following ways:

● In the toolbar, choose (Open SQL console).

● In the catalog tree, choose Open SQL Console from the context menu of a schema or schema sub-node.
● Invoke a procedure or function or generate a SQL statement on a table or view using the respective context
menu or toolbar option.

Each SQL console works with its own schema and parameters. You can see with which schema the SQL
console is currently associated in the now editing section on the screen, as shown in the example below:

The current schema is used when SQL statements use database object names, for example, table names, that
are not prefixed with a schema name.

Tip
You can change the current schema by dragging and dropping a schema from the catalog tree into the now
editing section.

Entering SQL Statements

The following rules apply:

● You can write SQL syntax elements in upper case or lower case.
● You can add any number of spaces and line breaks.
● To force the system to distinguish between upper-case and lower-case letters in database object names
(such as table names), enter the name between double quotation marks, for example, "My_Table".
● Separate multiple SQL statements with a semicolon (;).
● To comment out a line, use -- (double hyphens) at the start of the line.

SAP HANA Developer Guide

22 PUBLIC SAP HANA Web-Based Development Workbench
Using Code Completion

The code completion feature provides a list of syntactic and semantic proposals based on the given context
and textual input. Code completion proposals include the following:

● Local variables, such as input and output parameters, declared scalar variables
● Catalog objects, such as schemas, views, table functions, procedures, scalar functions, synonyms
● Code snippets
● Keywords

To open a list of proposals, press the key combination CTRL + SPACEBAR at the appropriate point in your code
and then use the arrow keys to scroll through the displayed list. Press ENTER on a highlighted entry to apply it
to your code.

Example:

Displaying Metadata as Hover Text

Press CTRL and hover over a table, view, or procedure in the SQL console to display the definition of the object.

Example:

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 23
Executing SQL Statements

Execute SQL statements by choosing (Run) in the toolbar. If you have entered several statements, you can
execute them individually by highlighting the statement and choosing (Run). If you do not highlight an
individual statement, all statements are executed.

The Result tab appears with the statement's results. Multiple Result tabs may open depending on the number
of statements executed.

Downloading and Uploading SQL Files

You can open, save, and download SQL console contents as SQL files.

Note that you can enable auto-save for SQL console contents in the catalog settings.

2.2.3 SQL Result Table and Data Preview Table

You can view the results of your SELECT queries in a result table on the Result tab of the SQL console. The table
content view lets you preview table data as well as view the SQL query that was automatically generated to
retrieve the data.

SQL Result Tab

The results of a SQL select statement or procedure call are shown in a result table on the Result tab. The
number of tabs shown depends on the number of statements you have executed.

Example:

SAP HANA Developer Guide

24 PUBLIC SAP HANA Web-Based Development Workbench
Data Preview

The content view lets you preview the data contained in a table. It also shows the SQL query that was used to
retrieve the data.

To open the data preview for a table or view, locate the object in the catalog structure and, in the context menu,
choose Open Content.

Example:

Table Actions

The following table actions are supported:

Option Icon Description

Copy selected rows Opens a dialog box that allows you to copy the selected rows. If
you want, you can change the delimiter and remove the header.

Change layout Opens a dialog box for selecting the columns to be displayed.

Show/hide current statement Shows or hides the current SQL statement.

Export Exports the table data as a csv file. You have the option of chang­
ing the delimiter.

Setting table properties Opens a dialog box for configuring table properties.

Maintain table data (data pre­ Lets you insert, edit, and delete table data.
view only)

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 25
Option Icon Description

Add filter (data preview only) Provides an advanced filter option with a list of filter operators.

Example:

1. Select column 2. Add filter condition

Configuration Settings

In the catalog settings, you can specify the following:

● Maximum result size (default: 1000)

● Representation of NULL values (default: "?")
● LOB column limit (bytes)

2.3 SAP HANA Web-based Development Workbench: Trace

SAP HANA Web-based Development Workbench includes a trace tool that enables you to view the SAP HANA
trace files.

The Trace component of the SAP HANA Web-based Development Workbench provides a browser-based
environment for viewing trace files and configuring traces. To use the Trace component, you must have the
privileges granted by the role sap.hana.ide.roles::TraceViewer or the parent role sap.hana.ide.roles::Developer.

Note
The Web-based Trace tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/trace.

SAP HANA Developer Guide

26 PUBLIC SAP HANA Web-Based Development Workbench
Trace Types

The trace tool supports the following trace types:

● XS application trace
Provides tracing functionality for SAP HANA XS applications. Application-specific trace messages are
written into a trace file according to the trace level you specify, for example, "Info", "Error", "Debug".
● SQL trace
Collects information about all SQL statements executed on the XS Engine and saves it in a trace file for
further analysis.
● Database Trace
Records information about activity in the components of the SAP HANA database. You can use this
information to analyze performance and to diagnose and debug errors.
● Plan trace
Allows you to collect SQL queries and their execution plans, executed in a given time frame for a particular
application session.

Trace File Deletion

The trace tool allows you to manually delete trace files you no longer require. You have the following options:

● Delete trace files by service

● Delete trace files by type
● Back up files. You can compress and save the selected files instead of deleting them.

In the toolbar, choose (Delete Trace Files) to open the Delete Trace Files dialog box.

Note
Trace files of running services or an active SQL trace cannot generally be deleted.

Related Information

Trace Settings [page 28]

Tutorial: Trace a Server-Side JavaScript Application [page 422]
Database Trace [page 29]
SQL Trace [page 30]
Plan Trace [page 31]

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 27
2.3.1 Trace Settings

Set your preferences for working with the Trace tool of the SAP HANA Web-based Development Workbench.

You can open the Settings dialog box by choosing (Trace Settings) in the toolbar.

Font Size and Background Theme

Configure the appearance of the trace files.

Option Description

Editor font size Use the slider to adjust the font size.

Editor background dark Select a background theme.

File Display

Use this option to determine which part of the trace file should be displayed by default.

Option Description

Display Part Specify either the start of the file, end of the file (default), or the entire file.

Display Lines The number of lines to be displayed from either the start of the file or the end of the file.

Browser

Use this option to retrieve a limited number of objects in the trace browser.

Option Description

Limit the number of SQL objects to retrieve Enter the maximum number of objects to be retrieved.

Text Highlight

Specify the text that should be highlighted in the trace files.

Option Description

Error Color Text Enter the text you want to be highlighted in the error color.

SAP HANA Developer Guide

28 PUBLIC SAP HANA Web-Based Development Workbench
Option Description

Warning Color Text Enter the text you want to be highlighted in the warning color.

Preview Shows how the text will be highlighted. Press ENTER to update the preview.

2.3.2 Database Trace

The database trace records information about activity in the components of the SAP HANA database. You can
use this information to analyze performance and to diagnose and debug errors.

Each service of the SAP HANA database writes to its own trace file. The file names follow the default naming
convention:

<service>_<host>.<port_number>.<3_digit_file_counter>.trc.

Example
indexserver_veadm009.34203.000.trc

Information recorded by the alert trace component is written to the file:

<service>_alert_<host>.trc

You can access database trace files in the Trace Files tree on the left of the Trace screen.

Database Trace Configuration

You configure the database trace in the Database Trace section on the Trace Configuration tab.

Database tracing is always active. Information about error situations is always recorded.

If a trace component is available in all services, it can be configured for all services at once. You can also
configure the trace level of a component individually for a specific service. The trace level of a component
configured at service level overrides the trace level configured at the ALL SERVICES level. Some components
are only available in a particular service and cannot be changed at the ALL SERVICES level.

In the Database Trace Configuration dialog box, a trace level that has been inherited from the ALL SERVICES
configuration (either the default or system configuration) is shown in brackets.

Not all trace components are visible by default in the Database Trace Configuration dialog box. To view all
additional components, select Show All Components.

Example
You change the trace level of the memory component to ERROR for all services and for the indexserver
service, you change it to WARNING. This means that the memory component of the indexserver service will
trace up to level WARNING and the memory component of all other services will trace to the level ERROR.

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 29
The following trace levels are available:

● NONE (0)
● FATAL (1)
● ERROR (2)
● WARNING (3)
● INFO (4)
● DEBUG (5)

The higher the trace level, the more detailed the information recorded by the trace.

Note
Even if you select NONE, information about error situations is still recorded.

2.3.3 SQL Trace

The SQL trace collects information about all SQL statements executed on the XS Engine and saves it in a trace
file for further analysis. It is inactive by default.

Information collected by the SQL trace includes overall execution time of each statement, the number of
records affected, potential errors (for example, unique constraint violations) that were reported, the database
connection being used, and so on. So the SQL trace is a good starting point for understanding executed
statements and their potential effect on the overall application and system performance, as well as for
identifying potential performance bottlenecks at statement level.

You can view SQL trace files under the SQL Trace node in the Trace Files tree on the left of the Trace screen.

SQL Trace Activation and Configuration

You activate and configure the SQL trace in the SQL Trace section on the Trace Configuration tab. Since the SAP
HANA Web-based Development Workbench runs on the XS Engine, you need to enable the SQL trace
specifically for the XS Engine:

Note
Writing SQL trace files can impact database performance significantly. They also consume storage space on
the disk. Therefore, it is not recommended that you leave the SQL trace enabled all the time.

SAP HANA Developer Guide

30 PUBLIC SAP HANA Web-Based Development Workbench
Related Information

SQL Trace Options

2.3.4 Plan Trace

The plan trace enables you to collect SQL queries and their execution plans, executed in a given time frame for
a particular application session. For each SQL query that has been traced, you can drill down the specific
execution plan in order to analyze its performance.

Note
As of SPS 10, only 'SELECT' statements are traced with the plan trace.

Prerequisites

● You have the TRACE ADMIN system privilege.

● You have the privileges granted by the role sap.hana.ide.roles::TraceViewer; this role is included in the
parent role sap.hana.ide.roles::Developer.

Activate the Plan Trace

1. Open the Trace Configuration tab if it is not already open by choosing (Configuration) in the toolbar.

2. Choose (Edit Configuration) in the Plan Trace section.

The Plan Trace Configuration dialog box appears. It shows that the current trace status is inactive.
3. Check that the Active radio button is selected under trace status.
4. Optionally enter values for the additional parameters.
5. Choose Next.
A summary is displayed of the configuration parameters you have set.
6. Choose OK to activate the plan trace.

View a Trace Plan List

1. Switch to the catalog and execute some SELECT queries in the SQL console.
2. Deactivate the trace tool.
Repeat the procedure described above for activating the trace, but make sure that the Inactive radio button
is selected.

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 31
3. Open the traced plan list.
Choose (Plan Trace) in the toolbar or click the Current List of Traces link in the Plan Trace section on the
Configuration tab.
The Plan Trace tab opens, displaying a traced plan list, as shown in the example below:

Drilldown

To drill down into further details, you have the following options:

● Save the traced plan list by downloading it. A trace_log.zip file will be downloaded to your PC, which
you can investigate further using the SAP HANA studio.

Note
You need to manually change the file extension to plz.

● Show detailed plan information. To do this, select a plan and choose (Show Plan). The Plan Analysis
page opens.

SAP HANA Developer Guide

32 PUBLIC SAP HANA Web-Based Development Workbench
Related Information

Query Plan Analysis

SAP HANA Developer Guide

SAP HANA Web-Based Development Workbench PUBLIC 33
3 Getting Started with Application
Development

To develop applications using SAP HANA Extended Application Services (SAP HANA XS), you use a
hierarchical package structure to organize the design-time artifacts that make up your applications. Within this
structure you apply application descriptors to define which application content is to be exposed and to control
access to it.

1. To set up a package hierarchy, you create a root package for your application-development activities, and
within this package you create additional subpackages to organize the applications and the application
content. All artifacts are stored in the SAP HANA repository.
To avoid conflicts with applications from SAP or other providers, we recommend that you use your
company’s dedicated name space (DNS) as the name of your root application development folder, for
example, com.acme.
2. To expose and control access to application content, you create application descriptors. These are files
that define the following:
○ The root point in the package hierarchy from which content can be served to client requests
○ Whether the application is permitted to expose data to client requests and what kind of access to the
data is allowed
3. To secure the application, you decide how to grant access to the applications you develop. For example,
you specify which authentication method, if any, is to be used to grant access to content exposed by an
application, and what content is visible.

Related Information

Maintaining Repository Packages [page 38]

Creating the Application Descriptors [page 47]
Maintaining Application Security [page 75]

3.1 Tutorial: Create a Simple SAPUI5 Application

In this tutorial, you use the SAP HANA Web-based Development Workbench Editor to develop an SAPUI5
application that displays a button in a browser window which fades out when clicked.

Prerequisites

You have the privileges granted by the role sap.hana.ide.roles::EditorDeveloper; this role is included in the
parent role sap.hana.ide.roles::Developer.

SAP HANA Developer Guide

34 PUBLIC Getting Started with Application Development
Context

You use the SAPUI5 Hello World template to create an application that consists of the following files:

● index.html: contains the application code.

● Application descriptors .xsaccess and .xsapp: mandatory for all applications deployed on SAP HANA
extended application services (SAP HANA XS).

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. From the context menu of the Content folder, choose Create Application.
3. Choose the SAP UI5 Hello World template.
4. Enter a package name, for example, demo.hello, and choose Create.

The system creates the index.html, .xsaccess, and .xsapp files, and automatically opens the
index.html file.

5. Select the index.html file and choose (Run) in the toolbar.

A browser window opens that displays a button.
6. Click the button.
The button fades out.

Related Information

Define the Application Root Package [page 48]

Enable Access to the Application Packages [page 50]

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 35
3.2 Tutorial: Create and Debug a Server-side JavaScript
Application

In this tutorial, you use the SAP HANA Web-based Development Workbench Editor to create and debug a
server-side JavaScript application. The application displays a browser window where you can enter two values
in URL parameters and display the results immediately in the browser window.

Prerequisites

● You have the privileges granted by the role sap.hana.ide.roles::EditorDeveloper; this role is included in the
parent role sap.hana.ide.roles::Developer.
● You have been assigned the user role sap.hana.xs.debugger::Debugger.
● Your SAP HANA administrator has enabled debugging in the SAP HANA system.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. From the context menu of the Content folder, choose Create Application.
Create the application in a package that does not already contain any application descriptors (for
example, .xsaccess and .xsapp files).
3. Choose the Empty application (with XSAccess and XSApp) template.
4. Enter a package name, for example, demo.first, and choose Create.
The system creates the index.html, .xsaccess, and .xsapp files, and automatically opens a dummy
index.html file.
5. To create a server-side JavaScript demo, do the following:
a. Delete the automatically created index.html file.
b. From the context menu of the demo.first folder, choose New File .
c. Enter a file name with the .xsjs extension, for example, debug.xsjs, and choose Create.
d. Enter the following server-side JavaScript code into the file and save it:

function doMultiply(var1, var2) {

return var1 + " X " + var2 + " = " + var1 * var2;
}
function doAdd(var1, var2) {
return var1 + " + " + var2 + " = " + (parseInt(var1, 10) +
parseInt(var2, 10));
}
$.response.contentType = "application/json";
$.response.status = 200;
$.response.contentType = "text/plain";
try {
var variable1 = parseInt($.request.parameters.get("var1"),10);

SAP HANA Developer Guide

36 PUBLIC Getting Started with Application Development
 var variable2 = parseInt($.request.parameters.get("var2"), 10);
switch ($.request.parameters.get("mode")) {
case "multiply":
$.response.setBody((doMultiply(variable1, variable2)));
break;
case "add":
$.response.setBody((doAdd(variable1, variable2)));
break;
default:
$.response.setBody(("Service not supported: " +
$.request.parameters.get("mode")));
break;
}
} catch (err) {
$.response.setBody("Failed to execute action: " + err.toString());
}

6. Choose (Run) in the toolbar.

A browser window opens.
7. Edit the URL parameters as follows and press Enter :
a. For multiply, enter <your_file_name>.xsjs?mode=multiply&var1=10&var2=200.
b. For addition, enter <your_file_name>.xsjs?mode=add&var1=10&var2=200.
The system computes the result and displays it in the browser window.
8. Set a breakpoint in front of the code line in the doAdd function by simply clicking the line number and then
repeat step 7b using, for example: <your_file_name>.xsjs?mode=add&var1=10&var2=200
During program execution, the Debugger panel opens in the editor as soon as a breakpoint is encountered.
You can see that the XSJS debugger has stopped at the breakpoint you defined and that the values of
<var1> and <var2> are shown in the Watch Area pane.
9. Evaluate an expression.

a. Choose (Evaluate expression) on the Debugger toolbar.

b. In the Evaluate expression dialog box, enter the expression parseInt(var1)+parseInt(var2) and
choose Evaluate.
c. Check that the result is displayed correctly on the right.
10. Change the value assigned to a variable.
a. In the same Evaluate expression dialog box, change the value assigned to the variable <var1>, for
example, to var1=100, and choose Evaluate.

b. Close the dialog box and choose (Resume (F10)) to finish the debugger session.
c. Switch to the application window to confirm that the change you made is reflected in the displayed
result.

Related Information

XSJS Debugger [page 427]

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 37
3.3 Maintaining Repository Packages

All content delivered as part of the application you develop for SAP HANA is stored in packages in the SAP
HANA repository. The packages are arranged in a hierarchy that you define to help make the process of
maintaining the packages transparent and logical.

Context

To perform the high-level tasks that typically occur during the process of maintaining repository packages, you
need to be familiar with the concepts of packages and package hierarchies. Packages enable you to group
together the artifacts you create and maintain for your applications. You must also be aware of the privileges
the application developers require to access (and perform operations on) the packages.

Procedure

1. Define the package hierarchy

The package hierarchy is essential for ease of maintenance as well as the configuration of access to
packages and the privileges that are required to perform actions on the packages.
2. Define package privileges
You can set package authorizations for a specific user or for a role. Authorizations that are assigned to a
repository package are implicitly assigned to all sub-packages, too.
3. Create a package
Packages are necessary to group logically distinct artifacts together in one object location that is easy to
transport.

Related Information

Repository Package Hierarchy [page 38]

Define Repository Package Privileges [page 40]
Create Repository Packages [page 43]

3.3.1 Repository Package Hierarchy

A package hierarchy can include sub-packages, for example, to isolate the data model from the business logic.

You can create a package hierarchy, for example, by establishing a parent-child type relationship between
packages. The assignment of packages to delivery units is independent of the package hierarchy; packages in a

SAP HANA Developer Guide

38 PUBLIC Getting Started with Application Development
parent-child relationship can belong to different delivery units. SAP recommends that you assign to one
specific delivery unit all packages that are part of a particular project or project area.

The package hierarchy for a new project typically includes sub-packages, for example, to isolate the data model
from the business logic. Although there are no package interfaces to enforce visibility of objects across
packages, this separation of logical layers of development is still a recommended best practice.

The following simple example shows a package structure containing tutorials for the use of a new application:

sap
\
hana
\
app1
\
code
demos
docs
\
tutorials
manuals
help

● Package hierarchy
Each vendor uses a dedicated namespace, for example, com.acme.
● Package type
Some packages contain content; other packages contain only other (sub)packages. Packages can also
contain both objects and (sub)packages.
● Package naming conventions
There are recommendations and restrictions regarding package names.

All content delivered by SAP should be in a sub-package of "sap". Partners and customers should choose their
own root package to reflect their own name (for example, the domain name associated with the company) and
must not create packages or objects under the "sap" root structural package. This rule ensures that customer-
or partner-created content will not be overwritten by an SAP update or patch.

Note
SAP reserves the right to deliver without notification changes in packages and models below the "sap" root
structural package.

There are no system mechanisms for enforcing the package hierarchy. The "sap" root structural package is not
automatically protected. However, by default you cannot change the content of packages that did not originate
in the system. In addition, an authorization concept exists, which enables you to control who can change what
inside packages.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 39
3.3.2 Define Repository Package Privileges

In the SAP HANA repository, you can set package authorizations for a specific user or for a role.

Context

Authorizations that are assigned to a repository package are implicitly assigned to all sub-packages, too. You
can also specify if the assigned user authorizations can be passed on to other users.

Procedure

1. Open the SAP HANA Web-based Development Workbench Security tool.

The Security tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/security

2. Expand the Security Users node.

3. Select the user to whom you want to assign authorizations.
4. Choose the Package Privileges tab.

5. Choose the (Add) button and enter all or part of the package name to locate the repository package.
6. Select the relevant package from the list of matching items and choose OK.
The selected package is added to the table.
7. In the table, select the package you just added and in the privileges list select the required privileges, for
example:
a. REPO.READ
Read access to the selected package and design-time objects (both native and imported)
b. REPO.EDIT_NATIVE_OBJECTS
Authorization to modify design-time objects in packages originating in the system the user is working
in
c. REPO.ACTIVATE_NATIVE_OBJECTS
Authorization to activate/reactivate design-time objects in packages originating in the system the user
is working in
d. REPO.MAINTAIN_NATIVE_PACKAGES
Authorization to update or delete native packages, or create sub-packages of packages originating in
the system in which the user is working
8. Save your changes.

SAP HANA Developer Guide

40 PUBLIC Getting Started with Application Development
3.3.2.1 Package Privileges

Package privileges authorize actions on individual packages in the SAP HANA repository.

Privileges granted on a repository package are implicitly assigned to the design-time objects in the package, as
well as to all sub-packages. Users are only allowed to maintain objects in a repository package if they have the
necessary privileges for the package in which they want to perform an operation, for example to read or write
to an object in that package. To be able perform operations in all packages, a user must have privileges on the
root package .REPO_PACKAGE_ROOT.

If the user authorization check establishes that a user does not have the necessary privileges to perform the
requested operation in a specific package, the authorization check is repeated on the parent package and
recursively up the package hierarchy to the root level of the repository. If the user does not have the necessary
privileges for any of the packages in the hierarchy chain, the authorization check fails and the user is not
permitted to perform the requested operation.

In the context of repository package authorizations, there is a distinction between native packages and
imported packages.

● Native package
A package that is created in the current system and expected to be edited in the current system. Changes
to packages or to objects the packages contain must be performed in the original development system
where they were created and transported into subsequent systems. The content of native packages are
regularly edited by developers.
● Imported package
A package that is created in a remote system and imported into the current system. Imported packages
should not usually be modified, except when replaced by new imports during an update. Otherwise,
imported packages or their contents should only be modified in exceptional cases, for example, to carry
out emergency repairs.

Note
The SAP HANA administrator can grant the following package privileges to an SAP HANA user: edit,
activate, and maintain.

Related Information

Package Privilege Options [page 42]

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 41
3.3.2.2 Package Privilege Options

Package privileges authorize actions on individual packages in the SAP HANA repository. In the context of
repository package authorizations, there is a distinction between native packages and imported packages.

Note
To be able perform operations in all packages in the SAP HANA repository, a user must have privileges on
the root package .REPO_PACKAGE_ROOT.

Privileges for Native Repository Packages

A native repository package is created in the current SAP HANA system and expected to be edited in the
current system. To perform application-development tasks on native packages in the SAP HANA repository,
developers typically need the privileges listed in the following table:

Package Privilege Description

REPO.READ Read access to the selected package and design-time ob­

jects (both native and imported)

REPO.EDIT_NATIVE_OBJECTS Authorization to modify design-time objects in packages

originating in the system the user is working in

REPO.ACTIVATE_NATIVE_OBJECTS Authorization to activate/reactivate design-time objects in

packages originating in the system the user is working in

REPO.MAINTAIN_NATIVE_PACKAGES Authorization to update or delete native packages, or create

sub-packages of packages originating in the system in which
the user is working

Privileges for Imported Repository Packages

An imported repository package is created in a remote SAP HANA system and imported into the current
system. To perform application-development tasks on imported packages in the SAP HANA repository,
developers need the privileges listed in the following table:

Note
It is not recommended to work on imported packages. Imported packages should only be modified in
exceptional cases, for example, to carry out emergency repairs.

SAP HANA Developer Guide

42 PUBLIC Getting Started with Application Development
 Package Privilege Description

REPO.READ Read access to the selected package and design-time ob­

jects (both native and imported)

REPO.EDIT_IMPORTED_OBJECTS Authorization to modify design-time objects in packages

originating in a system other than the one in which the user
is currently working

REPO.ACTIVATE_IMPORTED_OBJECTS Authorization to activate (or reactivate) design-time objects

in packages originating in a system other than the one in
which the user is currently working

REPO.MAINTAIN_IMPORTED_PACKAGES Authorization to update or delete packages, or create sub-

packages of packages, which originated in a system other
than the one in which the user is currently working

Related Information

Package Privileges [page 506]

3.3.3 Create Repository Packages

In SAP HANA, a package contains a selection of repository objects. You assemble a collection of packages into
a delivery unit, which you can use to transport the repository objects between SAP HANA systems.

Context

You can use repository packages to manage the various elements of your application development project in
the SAP HANA repository.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Expand the Content node to display the namespace hierarchy for package content.

3. From the context menu of the Content folder (or a folder of your choice), choose New Package .
The Create Package dialog box appears.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 43
4. Maintain the package details.
a. Enter a name for the new package.
The package name is mandatory. Note that guidelines and conventions apply to package names.
b. Fill in the other optional information as required:
○ Enter a package description.
○ Assign responsibility of the package to a specific user.

Note
If omitted, the user responsible for a new package is, by default, the user who created it.

○ Specify a language for the package content.

5. Choose Create.
The new package appears in the package hierarchy. The fully qualified package name and package
properties are shown above the multi-file drop zone in the panel on the right.

Next Steps

To specify the delivery unit that a package is to be assigned to, select the package and from the context menu
choose Delivery Unit Assign . Then enter the name of the delivery unit and choose Assign.

Related Information

Define Repository Package Privileges [page 40]

Maintaining Delivery Units

3.3.3.1 SAP HANA Repository Packages and Namespaces

In SAP HANA, a package typically consists of a collection of repository objects, which can be transported
between systems. Multiple packages can be combined in a delivery unit (DU).

An SAP HANA package specifies a namespace in which the repository objects exist. Every repository object is
assigned to a package, and each package must be assigned to a specific delivery unit. In the repository, each
object is uniquely identified by a combination of the following information:

● Package name
● Object name
● Object type

Note
Multiple objects of the same type can have the same object name if they belong to different packages.

SAP HANA Developer Guide

44 PUBLIC Getting Started with Application Development
Before you start the package development process, consider the following important points:

● Package hierarchy
Each vendor uses a dedicated namespace, and the package hierarchy you create enables you to store the
various elements of an application in a logical order that is easy to navigate.
● Package type
Packages can be structural or non-structural; some packages contain content; other packages contain
only other (sub)packages.
● Package naming conventions
There are recommendations and restrictions regarding package names, for example, the name's maximum
length and which characters must not be used.

Package Naming Conventions

The following rules apply to package names:

● Permitted characters
Lower/upper case letters (aA-zZ), digits (0-9), hyphens (-), underscores (_), and dots (.) are permitted in
package names. Dots in a package name define a logical hierarchy. For example, "a.b.c" specifies a package
"a" that contains sub-package "b", which in turn contains sub-package "c".
● Forbidden characters
A package name must not start with either a dot (.) or a hyphen (-) and cannot contain two or more
consecutive dots (..).
● Package name length
The name of the complete package namespace hierarchy (for example, “aa.bb.cc.zz” including dots) must
not be more than 190 characters long. In addition, on object activation, the maximum permitted length of a
generated catalog name (which includes the package path, the separating dots, and the object base name)
is restricted to 127 characters.
○ hdbtable hdbview, hdbsequence, hdbstructure, hdbprocedure objects

sap.test.hana.db::myObject

○ CDS objects

sap.test.hana.db::myContext.myEntity

3.3.3.2 Repository Package Types

SAP HANA enables the use of various types of package, which are intended for use in particular scenarios.

SAP HANA Application Services provide or allow the following package types:

● Structural
Package only contains sub-packages; it cannot contain repository objects.
● Non-Structural
Package contains both repository objects and subpackages.

The following packages are delivered by default with the repository:

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 45
● sap
Transportable package reserved for content delivered by SAP. Partners and customers must not use the
sap package; they must create and use their own root package to avoid conflicts with software delivered by
SAP, for example when SAP updates or overwrites the sap package structure during an update or patch
process.
● system-local
Non-transportable, structural packages (and subpackages). Content in this package (and any
subpackages) is considered system local and cannot be transported. This is similar to the concept of the
$tmp development class in SAP NetWeaver ABAP.
● system-local.generated
Non-transportable, structural packages for generated content, that is; content not created by manual user
interaction
● system-local.private
Non-transportable, structural package reserved for objects that belong to individual users, for example,
system-local.private.<user_name> . To avoid compatibility issues with future functionality, do not
use the system-local.private package or any of its sub-packages.

3.3.4 Delete Repository Packages

In SAP HANA development, repository packages are used to manage various elements of your application
development project. Sometimes you need to delete a package that contains repository objects from other
developers.

Prerequisites

You are assigned the REPO.WORK_IN_FOREIGN_WORKSPACE system privilege.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. In the Content tree, locate the package that you want to delete.
3. Delete the package.
1. In the context menu of the package that you want to delete, choose Delete.
2. When prompted, choose OK.

SAP HANA Developer Guide

46 PUBLIC Getting Started with Application Development
Related Information

System Privileges (Reference) [page 494]

3.4 Creating the Application Descriptors

The application descriptors describe the framework in which an SAP HANA XS application runs. The
framework defined by the application descriptors includes the root point in the package hierarchy where
content is to be served to client requests, and who has access to the content.

Prerequisites

● You must be familiar with the concept of the application descriptor file (.xsapp), the application-access
file (.xsaccess), and if required, the application-privileges file (.xsprivileges).

Context

When you develop and deploy applications in the context of SAP HANA Extended Application Services (SAP
HANA XS), you must define the application descriptors. Maintaining the application descriptors involves the
following tasks:

Procedure

1. Create an application-descriptor file.

The package that contains the application descriptor file becomes the root path of the resources exposed
to client requests by the application you develop.
2. Create an application-access file.
The application-access file enables you to specify who or what is authorized to access the content exposed
by a SAP HANA XS application package and what content they are allowed to see. You can use keywords in
the application-access file to set authentication rules, define package-privilege levels (for example,
EXECUTE or ADMIN, specify the connection security level (for example, SSL/HTTPS), and allow (or
prevent) the creation of entity tags (Etags). You can also define rewrite rules for URLs exposed by an
application, for example, to hide internal details of URL paths from external users, clients, and search
engines.
3. Create an application-privileges file. (Optional)
The application-privileges file enables you to define the authorization privileges required for access to an
SAP HANA XS application, for example, to start the application (EXECUTE) or to perform administrative

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 47
 actions on an application (ADMIN). The privileges defined here are activated for a particular application in
the application-access file. These privileges can be checked by an application at runtime. Privileges defined
apply to the package where the privileges file is located as well as any packages further down the package
hierarchy unless an additional privileges file is present, for example, in a subpackage.

3.4.1 Define the Application Root Package

Each application that you want to develop and deploy on SAP HANA Extended Application Services (SAP HANA
XS) must have an application-descriptor (.xsapp) file.

Prerequisites

You have created an application root package.

Context

This file is the core file that you use to indicate an application's availability within SAP HANA XS. It marks the
point in the package hierarchy at which an application's content is available, that is, the package that contains
this file becomes the root path of the resources exposed by the application you develop.

Note that the .xsapp file has no content except the set of curly brackets {} and no name; it only has the file
extension .xsapp.

Tip
When creating applications, remember that it is not necessary to manually create the application
descriptors. Choose an appropriate application template or the empty application template and these files
will be created automatically.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor

2. Select the package where you want to create the new file and from the context menu choose New
File .
3. Enter the file name .xsapp and choose Create.
4. Save the file.

SAP HANA Developer Guide

48 PUBLIC Getting Started with Application Development
Related Information

The SAP HANA XS Application Descriptor [page 49]

3.4.1.1 The SAP HANA XS Application Descriptor

Each application that you want to develop and deploy on SAP HANA Extended Application Services (SAP HANA
XS) must have an application descriptor file. The application descriptor is the core file that you use to describe
an application's framework within SAP HANA XS.

The package that contains the application descriptor file becomes the root path of the resources exposed to
client requests by the application you develop.

Note
The application-descriptor file has no name and no content; it only has the file extension “xsapp”, for
example, .xsapp. For backward compatibility, content is allowed in the .xsapp file but ignored.

The application root is determined by the package containing the .xsapp file. For example, if the package
sap.test contains the file .xsapp, the application will be available under the URL http://<host>:<port>/
sap.test/. Application content is available to requests from users.

Caution
Make sure that the folder containing the .xsapp application descriptor file also contains an .xsaccess file,
which controls access to the application.

The contents of the package where the .xsapp file resides (and any subfolders) are exposed to user requests
and, as a result, potentially reachable by attackers. You can protect this content with the appropriate
authentication settings in the corresponding application-access (.xsaccess) file, which resides in the same
package. Bear in mind that by exposing Web content, you run the risk of leaking information; the leaked
information can be used in the following ways:

● Directly
Data files such as .csv files used for the initial database load can contain confidential information.
● Indirectly
File descriptors can give details about the internal coding of the application, and files that contain the
names of developers are useful; they can be used by an attacker in combination with social-engineering
techniques.

To help protect your application from security-related issues, place the application descriptor (.xsapp) as
deep as possible in the package hierarchy. In addition, include only the index page in this package; all other
application data should be placed in sub-folders that are protected with individual application-access files.

Tip
Keep the application package hierarchy clean. Do not place in the same package as the .xsapp file (or sub-
package) any unnecessary content, for example, files which are not required for the application to work.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 49
Related Information

The Application-Access File [page 52]

3.4.2 Enable Access to the Application Packages

The application-access (.xsaccess) file enables you to specify who or what is authorized to access the
content exposed by the application package and what content they are allowed to see.

Prerequisites

● An application root package

● An application descriptor file (.xsapp) for the selected application

Context

You can use a set of keywords in the application-access file to specify if authentication is required to enable
access to package content, which data is exposed, and if rewrite rules are in place to hide target and source
URLs, for example, from users and search engines. You can also specify what, if any, level of authorization is
required for the package and whether SSL is mandatory for client connections.

The application-access file does not have a name before the dot (.); it only has the file extension .xsaccess.
The contents of the .xsaccess file must be formatted according to JavaScript Object Notation (JSON) rules.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Select the root package of the application to which you want to enable access and from the context menu
choose New File .
3. Enter the file name .xsaccess and choose Create.
A basic .xsaccess file must, at the very least, contain a set of curly brackets, for example, {}. Note that
the .xsaccess file uses keyword-value pairs to set access rules; if a mandatory keyword-value pair is not
set, then the default value is assumed.
4. Enable application access to data.

SAP HANA Developer Guide

50 PUBLIC Getting Started with Application Development
 To enable or disable access to content at a package or subpackage level, you use the exposed keyword:

{
"exposed" : true
}

5. Define the application authentication method.

To ensure that basic or form-based logon works when it is enabled using the SAP HANA XS Administration
Tool, the authentication keyword is required in the .xsaccess file, too, and must be set to the respective
value, as shown in the following example:

{
"authentication" : { "method" : "Form"}
}

Note
Provided the Public security option is disabled (default setting) in the SAP HANA XS Administration Tool,
both the form-based authentication and basic authentication options are automatically enabled.

You can use the SAP HANA XS Administration Tool to configure applications to use additional
authentication methods, for example, logon tickets, or Single Sign On (SSO) providers such as SAML2
and X509.

6. Optionally specify the application privileges if required.

Use the authorization keyword in the .xsaccess file to specify which authorization level is required by a
user to access a particular application package. The authorization keyword requires a corresponding entry
in the .xsprivileges file, for example, execute for basic privileges or admin for administrative privileges
on the specified package:

{
"authorization":
["<package.path>::Execute",
"<package.path>::Admin"
]
}

7. Save the file in the package with which you want to associate the rules you have defined.

Related Information

The Application-Access File [page 52]

Application-Access File Keyword Options [page 53]
Application-Access URL Rewrite Rules [page 64]

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 51
3.4.2.1 The Application-Access File

SAP HANA XS enables you to define access to each individual application package that you want to develop
and deploy.

The application-access file enables you to specify who or what is authorized to access the content exposed by
a SAP HANA XS application package and what content they are allowed to see. For example, you use the
application-access file to specify if authentication is to be used to check access to package content and if
rewrite rules are in place that hide or expose target and source URLs.

The application-access file does not have a name; it only has the file extension .xsaccess. The content of
the .xsaccess file is formatted according to JSON rules, and the settings specified in an .xsaccess file apply
not only to the package the .xsaccess file belongs to but also any subpackages lower in the package
hierarchy. Multiple .xsaccess files are allowed, but only at different levels in the package hierarchy. You
cannot place two .xsaccess files in the same package.

Note
The settings specified in an .xsaccess file in a subpackage take precedence over any settings specified in
a .xsaccess file higher up the package hierarchy; the subpackage settings are also inherited by any
packages further down the package hierarchy. Any settings not modified by the .xsaccess in the
subpackage remain unchanged, that is: as defined in the parent package or, where applicable, the default
settings.

Using multiple .xsaccess files enables you to specify different application-access rules for individual
subpackages in the package hierarchy. Following the inheritance rule, any applications below the application
package containing the modified access settings inherit the new, modified settings.

The following example shows the composition and structure of the SAP HANA XS application access
(.xsaccess) file, which comprises a list of key-value pairs that specify how the application service responds to
client requests. For example, in this file, "exposed" : true indicates that data is available to client requests;
"force_ssl" : true specifies that standard HTTP requests are not allowed by the Web browser.

Note
Some elements can also be specified in the application's runtime configuration, for example, using the SAP
HANA XS Administration Tool. For example, you can configure applications to refuse insecure HTTP
connections, allow the use of e-tags, or enable additional authentication methods such as Single Sign On
(SSO) providers SAML2 and X509.

Example
The Application-Access (.xsaccess) File

{
"exposed" : true, // Expose data via http
"authentication" :
{
"method": "Form"
},
"authorization": // Privileges for application access
[
"sap.xse.test::Execute",
"sap.xse.test::Admin"

SAP HANA Developer Guide

52 PUBLIC Getting Started with Application Development
 ],
"rewrite_rules" : // URL rewriting rules
[ {
"source": "/entries/(\\d+)/(\\d+)/(\\d+)/",
"target": "/logic/entries.xsjs?year=$1&month=$2&day=$3"
} ],
"mime_mapping" : // Map file-suffix to MIME type
[ {
"extension":"jpg", "mimetype":"image/jpeg"
} ],
"force_ssl" : true, // Accept only HTTPS requests
"enable_etags" : true, // Allow generation of etags
"prevent_xsrf" : true, // Prevent cross-site request forgery
"anonymous_connection" : "sap.hana.sqlcon::AnonConn", //.xssqlcc object
"default_connection" : "sap.hana.sqlcon::sqlcc", //.xssqlcc object
"cors" : // Permit cross-origin browser requests
{
"enabled" : false
},
"default_file" : "homepage.html", // Override default access setting
"cache_control" : "no-cache, no-store", // Manage static Web-content cache
"headers": // Enable X-Frame-Options HTTP header field
{
"enabled": true,
"customHeaders":
[ {
"name":"X-Frame-Options","value":"SAMEORIGIN"
} ]
}
}

Related Information

Application-Access File Keyword Options [page 53]

Set up Application Security [page 76]

3.4.2.2 Application-Access File Keyword Options

The application-access (.xsaccess) file enables you to specify whether or not to expose package content,
which authentication method is used to grant access, and what content is visible.

Example
The Application Access (.xsaccess) File

Note
This example of the .xsaccess file is not a working model; it is used to illustrate the syntax for all
possible options.

{
"exposed" : false,
"authentication" :

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 53
 {
"method": "Form"
},
"authorization":
[
"sap.xse.test::Execute",
"sap.xse.test::Admin"
],
"anonymous_connection" : "sap.hana.sqlcon::AnonConn",
"default_connection" : "sap.hana.sqlcon::sqlcc",
"cache_control" : "no-store",
"cors" :
{
"enabled" : false
},
"default_file" : "index_1.html",
"enable_etags" : false,
"force_ssl" : true,
"mime_mapping" :
[
{
"extension":"jpg", "mimetype":"image/jpeg"
}
],
"prevent_xsrf" : true,
"rewrite_rules" :
[{
"source" : "...",
"target" : "..."
}]
"headers":
{
"enabled": true,
"customHeaders": [ {"name":"X-Frame-Options","value":"<VALUE>"} ]
}
}

exposed

{
"exposed" : false,
}

The exposed keyword enables you define if content in a package (and its subpackages) is to be made available
by HTTP to client requests. Values are Boolean true or false. If no value is set for exposed, the default setting
(false) applies.

Tip
Only expose content that is absolutely necessary to enable the application to run.

Consider whether it is necessary to expose data via HTTP/S. Not exposing data via HTTP enables you to keep
your files accessible to other programs but prevent direct access to the data via URL. Since the application's
index.html page must normally remain reachable, consider storing the index.html file separately with a
dedicated .xsaccess file that enables access (“exposed”: true). You can keep all other content hidden, for
example, in separate package to which access is denied (“exposed”: false).

SAP HANA Developer Guide

54 PUBLIC Getting Started with Application Development
Packages without a dedicated .xsaccess file inherit the application-access settings defined in the parent
folder. If an .xsaccess file exists but the exposed keyword is not defined, the default setting false applies.

anonymous_connection

{
"anonymous_connection" : "sap.hana.sqlcon::AnonConn",
}

The anonymous_connection keyword enables you to define the name of the .xssqlcc file that will be used
for SQL access when no user credentials are provided. SAP HANA XS enables you to define the configuration
for individual SQL connections. Each connection configuration has a unique name, for example, Registration,
AnonConn, or AdminConn, which is generated from the name of the corresponding connection-configuration
file (Registration.xssqlcc, AnonConn.xssqlcc, or AdminConn.xssqlcc) on activation in the repository.
If no value is set, the default setting is “null”.

Tip
It is not recommended to enable anonymous access.

If it is necessary to provide anonymous access to an application, design your application in such a way that all
files requiring anonymous access are placed together in the same package, which you can then protect with
the permissions defined in a dedicated .xsaccess file. Remember that the behavior of the anonymous
connection depends on the details specified in the corresponding SQL configuration file (.xssqlcc).

default_connection

{
"default_connection" : "sap.hana.sqlcon::sqlcc",
}

If the default_connection is set in the .xsaccess file, the specified SQL connection configuration (for
example, defined in sqlcc) is used for all SQL executions in this package, whether or not the requesting user is
authenticated in SAP HANA or not. The difference between the default_connection and the
anonymous_connection is that the anonymous SQL connection configuration is only used if the requesting
user is not authenticated. Like any other property of the xsaccess file, the default_connection is inherited
down the package hierarchy, for example, from package to subpackage. The default_connection can also
be overwritten, for example, by locating an xsaccess file with a different default_connection in one or
more subpackages.

Tip
If the requesting user is authenticated, the user name will be available in the connection as the
APPLICATIONUSER session variable.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 55
The credentials to use for an SQL execution are determined according to the following order of priority:

1. The SQL connection configuration (SQLCC) specified in $.db.getConnection(sqlcc); this applies only
in XS JavaScript (not OData, for example)
2. The value specified in default_connection (if set)
3. An authenticated user
4. The valued specified in anonymous_connection (if set)

The default_connection is intended for use with anonymous parts of the application that require the same
privileges for all users. If the anonymous part of an application is designed to behave according to the privileges
granted to authenticated users, the anonymous_connection should be used. This is particularly important if
analytic privileges are involved, for example, to restrict the amount of returned rows (not overall access to the
table). In most cases, the default_connection should be used.

authentication

{
"authentication" :
{
"method": "Form"
},
}

The authentication keyword is required in the .xsaccess file and must be set to the value "form", for
example "method" : "Form", to ensure that form-based logon works when you enable it using the SAP
HANA XS Administration Tool.

Note
Use the SAP HANA XS Administration Tool to configure applications to use additional authentication
methods, for example, basic, logon tickets, or Single Sign On (SSO) providers such as SAML2 and X509. You
must also enable the Form-based authentication checkbox, if you want your application (or applications) to
use form-based logon as the authentication method. Any other keywords in the authentication section of
the .xsacess file are ignored.

● Form-based authentication
Redirect the logon request to a form to fill in, for example, a Web page.
To ensure that, during the authentication process, the password is transmitted in encrypted form, it is
strongly recommended to enable SSL/HTTPS for all application connections to the XS engine, for
example, using the force_ssl keyword. If you set the force_ssl option, you must ensure that the SAP Web
Dispatcher is configured to accept and manage HTTPS requests.
Form-based authentication requires the libxsauthenticator library, which must not only be available
but also be specified in the list of trusted applications in the xsengine application container. The application
list is displayed in the SAP HANA studio's Administration Console perspective in the following location:
Administration Configuration tab xsengine.ini application_container application_list . If it is not
displayed, ask the SAP HANA administrator to add it.

SAP HANA Developer Guide

56 PUBLIC Getting Started with Application Development
 Note
If you need to troubleshoot problems with form-based logon, you can configure the generation of useful
trace information in the XSENGINE section of the database trace component using the following entry:
xsa:sap.hana.xs.formlogin.

authorization

{
"authorization":
[
"sap.xse.test::Execute",
"sap.xse.test::Admin"
],
}

The authorization keyword in the .xsaccess file enables you to specify which authorization level is
required for access to a particular application package, for example, execute or admin on the package
sap.xse.text.

Note
The authorization levels you can choose from are defined in the .xsprivileges file for the package, for
example, "execute" for basic privileges, or "admin" for administrative privileges on the specified package. If
you do not define any authorization requirements, any user can launch the application.

If you use the authorization keyword in the .xsaccess file, for example, to require “execute” privileges for
a specific application package, you must create a .xsprivileges file for the same application package (or a
parent package higher up the hierarchy, in which you define the “execute” privilege level declared in
the .xsaccess file.

Authorization settings are inherited down the package hierarchy from a package to a subpackage. However,
you can specify different authorization levels for different subpackages; this new setting is then inherited by
any subpackages further down the hierarchy. To disable authorization for a subpackage (for example, to
prevent inheritance of authorizations from the parent package), you can create a (sub)package-
specific .xsaccess file with the authorization keyword explicitly set to null, as illustrated in the following
example.

{
"authorization": null
}

Bear in mind that the “authorization”:null setting applies not only to the package in which
the .xsaccess with the null setting is located but also to any subpackages further down the package
hierarchy. You can re-enable authorization in subpackage levels by creating new a .xsaccess file.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 57
cache_control

{
"cache_control":"no-store",
}

The cache_control keyword enables you to override the cache-control header for Web content served by the
SAP HANA XS Web server. So-called cache-control directives (for example, public, private, no-store)
enable you to control the behavior of the Web browser and proxy caches, for example, whether or not to store a
page, how to store it, or where. For more information about the values you can use to set cache_control, see
the HTTP standard for cache-control directives. If no value for code_controlis set in the .xsaccess file, the
default setting is “null”.

Tip
For security reason, it is recommended to set the cache_control keyword to “no-cache, no-store”.
However, if nothing is cached or stored, there is an obvious impact on application performance.

If application performance allows, the no-cache, no-store setting is advisable for the following reasons:

● From a client perspective:

If an application is handling sensitive data, it is bad practice to cache the data in the local browser since
this could lead to unintended disclosure of information.
● From a server perspective:
Allowing an application to cache data can open up the application to attack. For example, if attackers build
a malicious page and host it on a proxy server between your server and the requesting client, it would be
possible to steal data from the client or prevent access to the application altogether. Since the risk of such
an attack is small, you might want to consider allowing caching, as long as it does not adversely affect
performance.

cors

{
"cors" :
{
"enabled" : false
},
}

The cors keyword enables you to provide support for cross-origin requests, for example, by allowing the
modification of the request header. Cross-origin resource sharing (CORS) permits Web pages from other
domains to make HTTP requests to your application domain, where normally such requests would
automatically be refused by the Web browser's security policy.

If CORS support is disabled ("enabled" : false), the following settings apply on the Web server:

● The server does not respond to any CORS preflight requests

● The server does not add CORS response headers to any CORS requests
● The server refuses to execute the resource specified in the request

SAP HANA Developer Guide

58 PUBLIC Getting Started with Application Development
To enable support for CORS, set the cors keyword to {“enabled”:true}, which results in the following
default corsconfiguration:

{"cors":{"enabled":true,"allowMethods":
[“GET”,”POST”,”HEAD”,”OPTIONS”],"allowOrigin": [“*”], “maxAge”:”3600”}}

The following table describes the options that are supported with the cors keyword:

{"cors":{"enabled":true, "allowMethods":<ALLOWED_METHODS>,
"allowOrigin":<ALLOWED_ORIGIN>,
“maxAge”:<MAX_AGE>, “allowHeaders”:<ALLOWED_HEADERS>,
“exposeHeaders”:<EXPOSED_HEADERS>}}

Default Settings for CORS Options

CORS Option Description

ALLOWED_METHODS A single permitted method or a comma-separated list of methods that are allowed by the
server, for example, “GET”, “POST”. If allowMethods is defined but no method is
specified, the default “GET”, “POST”, “HEAD”, “OPTIONS” (all) applies. Note
that matching is case-sensitive.

ALLOWED_ORIGIN A single host name or a comma-separated list of host names that are allowed by the
server, for example: www.sap.com or *.sap.com. If allowOrigin is defined but
no host is specified, the default “*” (all) applies. Note that matching is case-sensitive.

ALLOW_HEADERS A single header or a comma-separated list of request headers that are allowed by the
server. If allowHeaders is defined but no header is specified as allowed, no default
value is supplied.

MAX_AGE A single value specifying how long a preflight request should be cached for. If maxAge is
defined but no value is specified, the default time of “3600” (seconds) applies.

EXPOSE_HEADERS A single header or a comma-separated list of response headers that are allowed to be
exposed. If exposeHeaders is defined but no response header is specified for expo­
sure, no default value is supplied.

Alternatively, you can isolate the part of the application where CORS must be allowed, for example, in a specific
subpackage. By adding a dedicated .xsaccess file to this CORS-related subpackage, you can set the cors
option in the dedicated .xsaccess file to true.

default_file

{
"default_file" : "new_index.html",
}

The default_file keyword enables you to override the default setting for application access (index.html) when
the package is accessed without providing a file in the URI. If you use the default_file but do not specify a value,
the default setting “index.html” is assumed.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 59
 Tip
It is good practice to specify a default file name manually. Changing the default from index.html to
something else can help make your application less vulnerable to automated hacker tools.

rewrite_rules

{
"rewrite_rules" :
[{
"source": "...",
"target": "..."
}],
}

The rewrite_rules keyword enables you hide the details of internal URL paths from external users, clients,
and search engines. Any rules specified affect the local application where the .xsaccess file resides (and any
subpackage, assuming the subpackages do not have their own .xsaccess files); it is not possible to define
global rewrite rules. URL rewrite rules are specified as a source-target pair where the source is written in the
JavaScript regex syntax and the target is a simple string where references to found groups can be inserted
using $groupnumber.

Tip
It is not recommended to rely on rewrite rules to make an application secure.

In the following example, the rule illustrated hides the filename parameter and, as a result, makes it harder to
guess that the parameter provided after /go/ will be used as a filename value. Note that it is still necessary to
validate the received input

{
"rewrite_rules" :
[{
"source": "/go/(\\d+)/",
"target": "/logic/users.xsjs?filename=$1"
}],
}

mime_mapping

{
"mime_mapping" :
[
{
"extension":"jpg", "mimetype":"image/jpeg"
}
],

SAP HANA Developer Guide

60 PUBLIC Getting Started with Application Development
 }

The mime_mapping keyword enables you to define how to map certain file suffixes to required MIME types. For
example, you can map files with the .jpg file extension to the MIME type image/jpeg.

This list you define with the mime_mapping keyword supersedes any default mapping defined by the server;
the Web browser uses the information to decide how to process the related file types.

Caution
Make sure you do not instruct the browser to execute files that are not meant to be executed, for example,
by mapping .jpg image files with the MIME type application/javascript.

The default MIME mappings remain valid for any values you do not define with the mime_mapping keyword.
Consider restricting any explicit mappings to file types where the default behavior does not work as expected
or where no default value exists, for example, for file types specific to your application.

force_ssl

{
"force_ssl" : false,
}

The force_ssl keyword enables you to refuse Web browser requests that do not use secure HTTP (SSL/
HTTPS) for client connections. If no value is set for force_ssl, the default setting (false) applies and non-
secured connections (HTTP) are allowed.

Tip
To ensure that, during the authentication process, passwords are transmitted in encrypted form, it is
strongly recommended to enable SSL/HTTPS for all application connections to the XS engine. If you set the
force_ssl option, you must ensure that the SAP Web Dispatcher is configured to accept and manage HTTPS
requests. For more information, see the SAP HANA XS section of the SAP HANA Administration Guide.

Enabling theforce_ssl option ensures that your application is reachable only by means of an HTTPS
connection. If your application must support standard HTTP (without SSL), make sure that no sensitive data is
being sent either to or from the application. Disabling the force_ssl option allows attackers to read whatever
is sent over the network. Although it is possible to use message-based encryption for sensitive data while
allowing HTTP, it is much better to work with HTTPS.

Caution
If a runtime configuration exists for your application, the force_ssl setting in the runtime configuration
supersedes the force_ssl in the .xsaccess.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 61
enable_etags

{
"enable_etags" : true,
}

You can allow or prevent the generation of entity tags (etags) for static Web content using the enable_etags
keyword. If no value is set, the default setting (true) applies, in which case etags are generated. Etags are used
to improve caching performance, for example, so that the same data is not resent from the server if no change
has occurred since the last time a request for the same data was made.

If etags are enabled, the browser sends with each HTTP request the etag retrieved from its cached page. If the
etag from the cached page matches the etag from the server, the server answers with the status code 304 (not
modified) and does send the full requested page. Although enabling etags has the positive side-effect of
helping to prevent cache poisoning attacks, there is no direct security risk associated with disabling etags from
the developer's perspective.

prevent_xsrf

{
"prevent_xsrf" : true,
}

You can use the prevent_xsrf keyword in the .xsaccess file to protect applications from cross-site request-
forgery (XSRF) attacks. XSRF attacks attempt to trick a user into clicking a specific hyperlink, which shows a
(usually well-known) Web site and performs some actions on the user’s behalf, for example, in a hidden iframe.
If the targeted end user is logged in and browsing using an administrator account, the XSRF attack can
compromise the entire Web application. There is no good reason why you would explicitly set this keyword to
false.

Note
It is recommended to enable the prevent_xsrf feature for all applications that are not read-only.

The prevent_xsrf keyword prevents the XSRF attacks by ensuring that checks are performed to establish
that a valid security token is available for a given Browser session. The existence of a valid security token
determines if an application responds to the client's request to display content; if no valid security token is
available, a 403 Forbidden message is displayed. A security token is considered to be valid if it matches the
token that SAP HANA XS generates in the back end for the corresponding session.

Note
The default setting is false, which means there is no automatic prevention of XSRF attacks. If no value is
assigned to the prevent_xsrf keyword, the default setting (false) applies.

SAP HANA Developer Guide

62 PUBLIC Getting Started with Application Development
Setting the prevent_xsrf keyword to true ensures XSRF protection only on the server side. On the client
side, to include the XSRF token in the HTTP headers, you must first fetch the token as part of a GET request, as
illustrated in the following example:

xmlHttp.setRequestHeader("X-CSRF-Token", "Fetch");

You can use the fetched XSRF token in subsequent POST requests, as illustrated in the following code example:

xmlHttp.setRequestHeader("X-CSRF-Token", xsrf_token);

headers

{
"headers":
{
"enabled": true,
"customHeaders": [ {"name":"X-Frame-Options","value":"<VALUE>"} ]
}
}

Enable support for the X-Frame-Options HTTP header field, which allows the server to instruct the client
browser whether or not to display transmitted content in frames that are part of other Web pages. You can also
enable this setting in the application's corresponding runtime configuration file, for example, using the XS
Administration Tool.

Caution
Runtime settings override any settings specified in the design-time configuration.

<VALUE> can be one of the following:

● DENY
● SAMEORIGIN
● ALLOW-FROM <URL>
You can only specify one URL with the ALLOW-FROM option, for example: "value":"ALLOW-FROM
http://www.site.com".

Note
To allow an application to use custom headers, you must enable the headers section.

Related Information

Server-Side JavaScript Security Considerations [page 361]

The SQL Connection Configuration File [page 407]

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 63
3.4.2.3 Application-Access URL Rewrite Rules

Rewriting URLs enables you to hide internal URL path details from external users, clients, and search engines.
You define URL rewrite rules in the application-access file (.xsaccess) for each application or for an
application hierarchy (an application package and its subpackages).

The rewrite rules you define in the .xsaccess file apply only to the local application to which the .xsaccess
file belongs; it is not possible to define global rules to rewrite URLs. Rules are specified as a source-target pair
where the source is written in the JavaScript regex syntax, and the target is a simple string where references
to found groups can be inserted using $groupnumber.

The following examples show how to use a simple set of rewrite rules to hide internal URLs from requesting
clients and users.

The first example illustrates the package structure that exists in the repository for a given application; the
structure includes the base package apptest, the subpackages subpackage1 and subpackage2, and several
other subpackages:

sap---apptest
|---logic
| |---users.xsjs
| |---posts.xsjs
|---posts
| |---2011...
|---subpackage1
| |---image.jpg
|---subpackage2
| |---subsubpackage
| | |---secret.txt
| |---script.xsjs
|---subpackage3
| |---internal.file
|---users
| |---123...
|---.xsapp
|---.xsaccess
|---index.html

The application-access file for the package apptest (and its subpackages) includes the following rules for
rewriting URLs used in client requests:

{
"rewrite_rules": [
{
"source": "/users/(\\d+)/",
"target": "/logic/users.xsjs?id=$1"
},
{
"source": "/posts/(\\d+)/(\\d+)/(\\d+)/",
"target": "/logic/posts.xsjs?year=$1&month=$2&day=$3"
}
]
}

Assuming we have the package structure and URL rewrite rules illustrated in the previous examples, the
following valid URLs would be exposed; bold URLs require authentication:

/sap/apptest/
/sap/apptest/index.html
/sap/apptest/logic/users.xsjs

SAP HANA Developer Guide

64 PUBLIC Getting Started with Application Development
 /sap/apptest/logic/posts.xsjs

The rewriting of the following URLs would be allowed:

/sap/apptest/users/123/ ==> /sap/appTest/logic/users.xsjs?id=123

/sap/apptest/posts/2011/10/12/ ==> /sap/appTest/logic/posts.xsjs?
year=2011&month=10&day=12

3.4.3 Define Application Access Privileges

The application-privileges (.xsprivileges) file allows you to define the authorization levels required to
access an application, for example, to start the application or perform administrative actions on an application.
You can assign the application privileges to the individual users who require them.

Prerequisites

● An application descriptor file (.xsapp) for the selected application

● An application access file (.xsaccess) for the selected application

Context

The .xsprivileges file must reside in the same application package that you want to define the access
privileges for.

Note
If you use the .xsprivileges file to define application-specific privileges, you must also add a
corresponding entry to the same application's .xsaccess file, for example, using the authorization
keyword.

The application-privileges file does not have a name; it only has the file extension .xsprivileges. The
contents of the .xsprivileges file must be formatted according to JavaScript Object Notation (JSON) rules.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Select the application package whose access privileges you want to define and from the context menu
choose New File .

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 65
 Note
Multiple .xsprivileges files are allowed, but only at different levels in the package hierarchy; you
cannot place two .xsprivileges files in the same application package. The privileges defined in
a .xsprivileges file are bound to the package to which the file belongs and can only be applied to this
package and its subpackages.

3. Enter the file name .xsprivileges and choose Create.

4. Define the required application privileges.
In the .xsprivileges file, you define a privilege for an application package by specifying an entry name
with an optional description. This entry name is then automatically prefixed with the package name in
which the .xsprivileges file is located to form a unique privilege name. For example,
com.acme.myapp::Execute would enable execute privileges on the package com.acme.myapp. The
privilege name is unique to the package to which it belongs and, as a result, can be used in
multiple .xsprivileges files in different packages.

{
"privileges" :
[
{ "name" : "Execute", "description" : "Basic execution
privilege" },
{ "name" : "Admin", "description" : "Administration
privilege" }
]
}

5. Specify which privileges are required to access the application or application package.
If you use the .xsprivileges file to define application-specific privileges, you must also add a
corresponding entry to the same application's .xsaccess file, for example, using the authorization
keyword.

Note
The .xsprivileges file lists the authorization levels that are available for access to an application
package; the .xsaccess file defines which authorization level is assigned to which application package.

a. Locate and open the application access file (.xsaccess) for the application for which you want to
define application privileges.
b. Specify the privileges required to access the application or application package.
Use the authorization keyword in the .xsaccess file to specify which authorization level is required by
a user to access a particular application package.

{
"exposed" : true,
"authentication" :
[
{ "method" : "Form" }
],
"authorization":
[
"<package.path>::Execute",
"<package.path>::Admin"
]
}

SAP HANA Developer Guide

66 PUBLIC Getting Started with Application Development
6. Save your changes and additions.
The activation of the application privileges creates the corresponding objects, which you can use to assign
the specified privileges to a user.
7. Assign the application privilege to the users who require it.
After activation of the .xsprivileges object, the only user who by default has the application privileges
specified in the .xsprivileges file is the _SYS_REPO user. To grant the specified privilege to (or revoke it
from) other users, use the GRANT_APPLICATION_PRIVILEGE or REVOKE_APPLICATION_PRIVILEGE
procedure in the _SYS_REPO schema.
To grant the execute application privilege to a user, open the catalog and run the following command in the
SQL editor:

call
"_SYS_REPO"."GRANT_APPLICATION_PRIVILEGE"('"<package.path>::Execute"','<UserNa
me>')

To revoke the execute application privilege to a user, run the following command in the SQL editor:

call
"_SYS_REPO"."REVOKE_APPLICATION_PRIVILEGE"('"<package.path>::Execute"','<UserN
ame>')

Related Information

The Application-Privileges File [page 67]

3.4.3.1 The Application-Privileges File

In SAP HANA Extended Application Services (SAP HANA XS), the application-privileges (.xsprivileges) file
can be used to create or define the authorization privileges required for access to an SAP HANA XS application,
for example, to start the application or to perform administrative actions on an application. These privileges
can be checked by an application at runtime.

The application-privileges file has only the file extension .xsprivileges; it does not have a name and is
formatted according to JSON rules. Multiple .xsprivileges files are allowed, but only at different levels in
the package hierarchy; you cannot place two .xsprivileges files in the same application package. The
package privileges defined in a .xsprivileges file are bound to the package to which the .xsprivileges
file belongs and can only be used in this package and its subpackages.

Inside the .xsprivileges file, a privilege is defined by specifying an entry name with an optional description.
This entry name is then automatically prefixed with the package name to form the unique privilege name, for
example, sap.hana::Execute.

As an application privilege is created during activation of an .xsprivileges file, the only user who has the
privilege by default is the _SYS_REPO user. To grant or revoke the privilege to (or from) other users you can use
the GRANT_APPLICATION_PRIVILEGE or REVOKE_APPLICATION_PRIVILEGE procedure in the _SYS_REPO
schema.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 67
 Note
The .xsprivileges file lists the authorization levels that are available for access to an application
package; the .xsaccess file defines which authorization level is assigned to which application package.

In the following above, if the application-privileges file is located in the application package sap.hana.xse,
then the following privileges are created:

● sap.hana.xse::Execute
● sap.hana.xse::Admin

The privileges defined apply to the package where the .xsprivileges file is located as well as any packages
further down the package hierarchy unless an additional .xsprivileges file is present, for example, in a
subpackage. The privileges do not apply to packages that are not in the specified package path, for example,
sap.hana.app1.

Example
The SAP HANA XS Application-Privileges File

The following example shows the composition and structure of a basic SAP HANA XS application-privileges
file.

{
"privileges" :
[
{ "name" : "Execute", "description" : "Basic execution
privilege" },
{ "name" : "Admin", "description" : "Administration privilege" }
]
}

If the .xsprivileges file shown in the example above is located in the package sap.hana.xse, you can
assign the Execute privilege for the package to a particular user by calling the
GRANT_APPLICATION_PRIVILEGE procedure, as illustrated in the following code:

call "_SYS_REPO"."GRANT_APPLICATION_PRIVILEGE"('"sap.hana.xse::Execute"',
'<user>')

3.5 Maintaining Application Artifacts

The design-time building blocks of an SAP HANA applications are called development objects (or artifacts),
and many have a mandatory file extension, for example, .hdbtable (design-time table definition), .hdbview
(design-time SQL-view definition), or .hdbrole (design-time role definition).

Some of the development objects you encounter when creating an application, such as projects and packages,
are designed to help you structure your application. Other objects such as schemas, table definitions, or
analytical and attribute views, help you organize your data. Design-time definitions of procedures and server-
side JavaScript code are the core objects of an SAP HANA application; these, too, have mandatory file
extensions, for example, .hdbprocedure or .xsjs. Other types of development objects help you control the
access to runtime objects.

SAP HANA Developer Guide

68 PUBLIC Getting Started with Application Development
When you activate an application artifact, the file extension (for example, .hdbdd, .xsjs, or
hdbprocedure, ...) is used to determine which runtime plug-in to call during the activation process. The plug-
in reads the repository artifact selected for activation (for example, a table definition, a complete CDS
document, or server-side JavaScript code), interprets the object description in the file, and creates the
appropriate runtime object in the designated catalog schema.

The file extensions associated with application artifacts are used in other contexts, too. For example, in SAP
HANA studio, a context-sensitive menu is displayed when you click an artifiact with the alternate mouse
button; the options displayed in the menu is determined, amongst other things, according to the file extension.

Related Information

Design-Time Application Artifacts [page 69]

3.5.1 Design-Time Application Artifacts

The design-time building blocks of your SAP HANA applications have a mandatory file extension, for
example, .hdbtable (design-time table definition) or .hdbview (design-time SQL-view definition).

In SAP HANA, application artifacts have a mandatory file extension, which is used to determine the Repository
tools required to parse the contents of the design-time artifact on activation. The following tables list the most
commonly used building blocks of an SAP HANA application; the information provided shows any mandatory
file extension and, if appropriate, indicates where to find more information concerning the context in which the
object can be used.

Design-time Application Building Blocks

File Extension Object Description

.aflpmml Procedure A file used by the application function modeler to store details of
a procedure defined using application functions in the Predictive
Analysis Library * (PAL) or Business Function Library * (BFL).
Using the AFM also generates a .diagram and a .aflmodel
file.

.analyticview Analytic view A file containing a design-time definition of an analytic view; the
view can be referenced in an OData service definition.

.attributeview Attribute view A file containing a design-time definition of an attribute view; the
view can be referenced in an OData service definition.

.calculationview Calculation view A file containing a design-time definition of an calculation view;

the view can be referenced in an OData service definition.

.hdbdd CDS document A file containing a design-time definition of a CDS-compliant

data-persistence object (for example, an entity or a data type)
using the Data Definition Language (DDL).

.hdbprocedure Procedure Replaces .procedure. A design-time definition of a database

function for performing complex and data-intensive business
logic that cannot be performed with standard SQL.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 69
File Extension Object Description

.hdbrole Role A file containing a design-time definition of an SAP HANA user

role.

.hdbscalarfunction Scalar user-defined A file containing a design-time definition of a a scalar user-de­

function fined function (UDF), which is a custom function that can be
called in the SELECT and WHERE clauses of an SQL statement.

.hdbschema Schema A design-time definition of a database schema, which organizes

database objects into groups.

.hdbsequence Sequence A design-time definition of a database sequence, which is set of

unique numbers, for example, for use as primary keys for a spe­
cific table.

.hdbstructure Table type A design-time definition of a database table type using

the .hdbtable syntax. Used for defining reusable table types,
for example, for parameters in procedures.

.hdbsynonym Database synonym A design-time definition of a database synonym using

the .hdbsynonym syntax.

.hdbtable Table A design-time definition of a database table using

the .hdbtable syntax.

.hdbtablefunction Table user-defined func­ A file containing a design-time definition of a table user-defined
tion function (UDF), which is a custom function that can be called in
the FROM–clause of an SQL statement.

.hdbtextbundle Resource Bundle A file for defining translatable UI texts for an application. Used in
SAP UI5 applications.

.hdbti Table Import definition A table-import configuration that specifies which .csv file is im­
ported into which table in the SAP HANA system.

.hdbview SQL View A design-time definition of a database view, which is a virtual ta­
ble based on an SQL query.

.procedure Procedure A design-time definition of a database function for performing

complex and data-intensive business logic that cannot be per­
formed with standard SQL.

.proceduretemplate Procedure template A design-time artifact containing a base script with predefined
placeholders for objects such as tables, views and columns.

.project Project An Eclipse project for developing your application or part of an

application. The .project file is a design-time artifact that is
stored in the SAP HANA repository.

.searchruleset Search Rule Set * A file that defines a set of rules for use with fuzzy searches. The
rules help decide what is a valid match in a search.

.xsaccess Application Access File An application-specific configuration file that defines permis­
sions for a native SAP HANA application, for example, to manage
access to the application and running objects in the package.

.xsapp Application Descriptor An application-specific file in a repository package that defines

the root folder of a native SAP HANA application. All files in that
package (and any subpackages) are available to be called via
URL.

.xsappsite Application Site A file that defines an application site

SAP HANA Developer Guide

70 PUBLIC Getting Started with Application Development
 File Extension Object Description

.xshttpdest HTTP destination config- A file that defines details for connections to a remote destination
uration by HTTP (or HTTPS)

.xsjob Scheduled XS job A JSON-compliant file used to define recurring tasks that run in
the background (independent of any HTTP request/response
process); a scheduled job can either execute a JavaScript func­
tion or call a SQLScript procedure.

.xsjs Server-Side JavaScript A file containing JavaScript code that can run in SAP HANA Ex­
Code tended Application Services and be accessed via URL

.xsjslib Server-Side JavaScript A file containing JavaScript code that can run in SAP HANA Ex­
Library tended Application Services but cannot be accessed via URL.
The code can be imported into an .xsjs code file.

.xsoauthappconfig OAuth application con­ A file describing high-level details of an application that enables
figuration file logon to a service running on a remote HTTP destination using
OAuth

.xsoauthclientconfi OAuth client configura- A file containing detailed information about a client application
g tion file that uses OAuth as the authentication mechanism for logon to a
remote HTTP destination

.xsoauthclientflavo OAuth client flavor file The corresponding OAuth flavors file for the OAuth client config-
r uration

.xsodata OData Descriptor A design-time object that defines an OData service that exposes
SAP HANA data from a specified end point.

.xsprivileges Application Privilege A file that defines a privilege that can be assigned to an SAP
HANA Extended Application Services application, for example,
the right to start or administer the application.

.xssecurestore Application secure store The design-time file that creates an application-specific secure
store; the store is used by the application to store data safely and
securely in name-value form.

.xssqlcc SQL Connection Config- A file that enables execution of SQL statements from inside
uration server-side JavaScript code with credentials that are different to
those of the requesting user

.xswidget Widget A file that defines a standalone SAP HANA application for the
purpose of integration into an application site

.xsxmla XMLA Descriptor A design time object that defines an XMLA service that exposes
SAP HANA data

Caution
(*) SAP HANA server software and tools can be used for several SAP HANA platform and options scenarios
as well as the respective capabilities used in these scenarios. The availability of these is based on the
available SAP HANA licenses and the SAP HANA landscape, including the type and version of the back-end
systems the SAP HANA administration and development tools are connected to. There are several types of
licenses available for SAP HANA. Depending on your SAP HANA installation license type, some of the
features and tools described in the SAP HANA platform documentation may only be available in the SAP
HANA options and capabilities, which may be released independently of an SAP HANA Platform Support
Package Stack (SPS). Although various features included in SAP HANA options and capabilities are cited in
the SAP HANA platform documentation, each SAP HANA edition governs the options and capabilities

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 71
 available. Based on this, customers do not necessarily have the right to use features included in SAP HANA
options and capabilities. For customers to whom these license restrictions apply, the use of features
included in SAP HANA options and capabilities in a production system requires purchasing the
corresponding software license(s) from SAP. The documentation for the SAP HANA options is available in
SAP Help Portal. If you have additional questions about what your particular license provides, or wish to
discuss licensing features available in SAP HANA options, please contact your SAP account team
representative.

Additional Application Building Blocks

Object Description File Extension

Package A container in the repository for development objects. Packages are represented by
folders.

Attribute, Analytic and A view created with modeling tools and designed to model a busi­ Created with the Systems
Calculation View ness use case. view.

Decision Table A table used to model business rules, for example, to manage
data validation and quality.

Analytic Privilege A set of rules that allows users to seeing a subset of data in a ta­
ble or view.

3.5.2 File Versions

The version history lets you view a list of file versions, compare one version of a file with another one, and revert
a file to a previous version.

You can open the version history by choosing Versions from the context menu of a file. The version history is
shown in the Versions panel on the right.

Compare File Versions

To compare one version of a file with another one, select the radio button of one of the file versions (referred to
as the base version) and from the context menu of the other file version choose Compare with selected.

The differences in the two file versions are highlighted in a side-by-side display on the compare tab. You can
switch to a unified view by choosing Toggle diff view in the Versions panel.

The difference blocks are indicated by a light blue marker on the right of the compare tab, where dark blue
shows your current cursor position. You can navigate between the blocks by clicking the markers, the
highlighted code lines, or using the arrows (Next diff block, Previous diff block). Additions to the code are shown
in green, while deletions are shown in red.

In the side-by-side view, a line between the two panes shows the location of a change in the two files.

SAP HANA Developer Guide

72 PUBLIC Getting Started with Application Development
Revert File Version

From the context menu of the relevant file version, choose Revert to version. You can restore a previous version
or a locally cached version.

Version Information

The version history provides the following information about each version:

● Version number: Available for active and inactive versions, but not for locally cached versions and GitHub
versions.
● Version marker:
○ Inactive version: [l]
○ Locally cached version: [L]
○ Deleted version: [D]
○ GitHub version: [G]
● Date and time when the version was changed.
● The name of the user who made the change. Depending on the version type, this is either the user’s GitHub
user name or their SAP HANA database user name.

Example

The example below shows the version history for a file that has active versions, an inactive version, a locally
cached version, and a GitHub version. Note that the locally cached version is listed above its GitHub version,
inactive version, and active versions:

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 73
Related Information

Editor Settings [page 10]

Storing Source Code on GitHub [page 74]

3.6 Storing Source Code on GitHub

You can use GitHub to store and share your source code.

Prerequisites

● You have a GitHub user account.

● You have created a GitHub repository.

Context

The SAP HANA Web-based Development Workbench allows you to push and pull changes made to your code
between your SAP HANA repository and your repositories on GitHub. GitHub requires your user credentials
whenever you commit changes to your GitHub repositories.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Connect a package with a GitHub repository.
a. In the Content tree, select the package that you want to connect with GitHub and from the context
menu choose Synchronize with GitHub.
The Git Pane opens on the right.
b. Before you can select a GitHub repository, you need to provide your GitHub credentials:

1. In the Git Pane, choose (Edit GitHub repository connection details).

2. Enter your GitHub user name, GitHub password, and GitHub email and choose OK.

SAP HANA Developer Guide

74 PUBLIC Getting Started with Application Development
 Note
You can save this information as defaults in your Editor settings. You will then be connected
automatically with the specified credentials. You will still be able to choose (Edit GitHub
repository connection details) to overwrite these values.

You are now connected to GitHub and can choose a repository.

c. Choose a repository and branch.

1. Select a GitHub repository.

2. Select a branch.
3. Choose Connect to connect the selected package with the specified GitHub repository.

Your SAP HANA package is now connected to the selected repository, allowing you to fetch and commit
code changes from and to the selected branch.
3. Clone the GitHub repository branch to the SAP HANA package.
Under Synchronization, choose Fetch.
All files contained in the repository are pulled to your SAP HANA package. In the message console you can
see exactly which files have been pulled.
4. Push changes to the GitHub repository.
a. Make a change to a file contained in the SAP HANA package.
b. Under Synchronization, choose Commit.
c. In the Commit dialog box, enter a commit description and choose Commit.
In the message console, you can see which files have been pushed to GitHub.
5. Check which version of a file is currently contained in the GitHub repository.
To open the version history, select a file and choose Versions from the context menu.
For files contained in packages for which a connection has been established to GitHub (see step 2), the top
entry in the version list is marked with [G] and shows the current version of the file on GitHub, that is,
when the last push to GitHub occurred.

Related Information

File Versions [page 72]

Create a GitHub Repository

3.7 Maintaining Application Security

As part of the application-development process, you must decide how to provide access to the applications you
develop. Application access includes security-related matters such as authentication methods and
communication protocols

In addition to the features and functions you can enable with keywords in the .xsaccess file, SAP HANA
Extended Application Services (SAP HANA XS) provides a dedicated SAP HANA XS administration tool that is

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 75
designed to help you configure and maintain the authentication mechanism used to control access to the
applications you develop. The SAP HANA XS Administration Tool enables you to configure the following runtime
elements for an application:

● Security
Choose the security level you want to set to provide access to the application. For example, you can expose
the application with/without requiring authentication (public/private) and force the application to accept
only requests that use SSL/HTTPS.
● Authentication
Select an authentication type to use when checking user credentials before authorizing access to an
application, for example: form-based authentication (with user name and password), SAML (SSO with
Security Assertion Markup Language), SAP logon tickets...

Related Information

Set up Application Security [page 76]

3.7.1 Set up Application Security

To restrict access to the applications you develop, you must configure the application to work with particular
authentication methods and communication protocols.

Prerequisites

To perform the steps in this task, you must ensure the following prerequisites are met:

● You have access to an SAP HANA system

● You have the privileges granted in the following SAP HANA XS user roles:
○ sap.hana.xs.admin.roles::RuntimeConfAdministrator

Context

You must specify whether or not to expose application content, which authentication method is used to grant
access to the exposed content, and what content is visible.

Procedure

1. Start the SAP HANA XS Administration Tool.

SAP HANA Developer Guide

76 PUBLIC Getting Started with Application Development
 The tool is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:
80<SAPHANAinstance>/sap/hana/xs/admin/.

Note
In the default configuration, the URL redirects the request to a logon screen, which requires the
credentials of an authenticated SAP HANA database user to complete the logon process. To ensure
access to all necessary features, the user who logs on should have the SAP HANA XS role
sap.hana.xs.admin.roles::RuntimeConfAdministrator.

2. Select the security options your applications use.

You can setup the following application-related security options:

Note
Security settings are automatically inherited by applications further down the application hierarchy.
However, you can override the inherited security settings at any application level by modifying the
settings for a particular application. Applications below the application with the modified security
settings inherit the new, modified settings.

a. Use the Public (no authentication required) option to specify if applications require user authentication
to start.
○ Disabled
This is the default setting. In disabled mode, Form-based authentication and Basic authentication
options are enabled automatically in the Authentication screen area.
○ Enabled
If you enable the Public option , no authentication is required to start an application; the
Authentication screen area is hidden, and you cannot select any authentication-method options.
b. Use the Force SSL option to specify if client requests must use secure HTTP (HTTPS).
○ Disabled
This is the default setting. With Force SSL disabled, the application returns a response to all
requests (both HTTP and HTTPS).
○ Enabled
If you enable the Force SSL option , requests from browsers using standard HTTP are refused.

Note
Enabling the Force SSL option only ensures that the selected application refuses any request
that does not use HTTPS; it does not set up the Secure Sockets Layer (SSL) protocol for you.
The SAP HANA administrator must configure the SAP Web Dispatcher to accept (and forward)
HTTPS requests in addition.

Related Information

Set up Application Authentication [page 78]

The Application-Access File [page 52]

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 77
3.7.2 Set up Application Authentication
To restrict access to the applications you develop, you must configure the application to work with particular
authentication methods and communication protocols.

Prerequisites

To perform the steps in this task, you must ensure the following prerequisites are met:

● You have access to an SAP HANA system

● You have the privileges granted in the following SAP HANA XS user roles:
○ sap.hana.xs.admin.roles::RuntimeConfAdministrator

Context

Before you define which authentication methods an application uses to grant access to the application content,
you must use the application security tools to define whether or not to expose application content and, if so,
which content to expose. SAP HANA XS enables you to define multiple authentication methods to verify the
credentials of users who request access to the exposed content; multiple authentication methods are
considered according to a specific order of priority. For example, if the first authentication method fails, SAP
HANA tries to authenticate the user with the next authentication method specified. To configure the
authentication method an application uses to verify user credentials, perform the following steps:

Procedure

1. Start the SAP HANA XS Administration Tool.

The tool is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:
80<SAPHANAinstance>/sap/hana/xs/admin/.

Note
In the default configuration, the URL redirects the request to a logon screen, which requires the
credentials of an authenticated SAP HANA database user to complete the logon process. To ensure
access to all necessary features, the user who logs on should have the SAP HANA XS role
sap.hana.xs.admin.roles::RuntimeConfAdministrator.

2. Select the security options your applications use.

If you have already set the application security level, you can safely skip this step. You can setup the
following application-related security options:

Note
Security settings are automatically inherited by applications further down the application hierarchy.
However, you can override the inherited security settings at any application level by modifying the

SAP HANA Developer Guide

78 PUBLIC Getting Started with Application Development
 settings for a particular application. Applications below the application with the modified security
settings inherit the new, modified settings.

a. Use the Public (no authentication required) option to specify if applications require user authentication
to start.
○ Disabled
This is the default setting. In disabled mode, Form-based authentication and Basic authentication
options are enabled automatically in the Authentication screen area.
○ Enabled
If you enable the Public option , no authentication is required to start an application; the
Authentication screen area is hidden, and you cannot select any authentication-method options.
b. Use the Force SSL option to specify if client requests must use secure HTTP (HTTPS).
○ Disabled
This is the default setting. With Force SSL disabled, the application returns a response to all
requests (both HTTP and HTTPS).
○ Enabled
If you enable the Force SSL option , requests from browsers using standard HTTP are refused.

Note
Enabling the Force SSL option only ensures that the selected application refuses any request
that does not use HTTPS; it does not set up the Secure Sockets Layer (SSL) protocol for you.
The SAP HANA administrator must configure the SAP Web Dispatcher to accept (and forward)
HTTPS requests in addition.

3. Select the authentication method your applications must use.

Authentication settings are automatically inherited by applications further down the application hierarchy.
However, you can override the inherited authentication settings at any application level by modifying the
settings for a particular application. Applications below the application with the modified authentication
settings inherit the new, modified settings.

Note
Enabling an application-security option (for example, SAML2 or X509) only ensures that the selected
application uses the enabled authentication method when required; it does not perform any setup
operation for the authentication method itself. The SAP HANA administrator must maintain the selected
authentication infrastructure (SAML2, X509, or SAP logon tickets) in an additional step.

You can choose any selection of the following application-related authentication methods; if you enable
multiple authentication methods for your application, a priority applies depending on whether the
application logon is interactive or non-interactive:
a. Enable the SAML2 option.
The SAP HANA administrator must already have configured the authentication infrastructure, for
example, to enable the creation of SAML2 assertions to permit SSO in Web browsers.
b. Enable the X509 Authentication option
The SAP HANA administrator must already have configured the appropriate authentication
infrastructure, for example, to enable users to be authenticated by client certificates signed by a
trusted Certification Authority (CA).
c. Enable the SAP logon ticket option

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 79
 The SAP HANA administrator must already have configured the appropriate authentication
infrastructure, for example, to enable users to be be authenticated by a logon ticket that is issued when
the same user logs on to an SAP system that is configured to create logon tickets (for example, the
SAP Web Application Server or Portal).
d. Enable the Form-based authentication option
If the Public security option is disabled, the Form-based authentication option is enabled by default.
e. Enable the Basic authentication option
If the Public security option is disabled, the Basic authentication option is enabled by default.

Related Information

Set up Application Authentication [page 76]

The Application-Access File [page 52]

3.8 Maintaining HTTP Destinations

An HTTP destination defines connection details for services running on specific hosts whose details you want
to define and distribute. The definition can be referenced by an application.

Context

If you want to configure an SAP HANA XS application to access data on a specific server that offers a specific
service, for example, a service that is only available outside your network, it is recommended to configure the
HTTP connection parameters in an HTTP destination file that you store locally as a design-time artifact. You
can use an HTTP destination to call an external resource directly from a server-side JavaScript application. You
can also use an HTTP destination when configuring a transport route, for example, to automate the process of
exporting a delivery unit from one system and importing it into another. To create an HTTP destination
configuration for an SAP HANA XS application, you must perform the following high-level steps.

Procedure

1. Create a package for the SAP HANA XS application that will use the HTTP destination you define.
2. Define the details of the HTTP destination.
You define the details of an HTTP destination in a configuration file and using a specific syntax. The
configuration file containing the details of the HTTP destination must have the file extension .xshttpdest
and be located in the same package as the application that uses it or one of the application's subpackages.
3. Define any extensions to the HTTP destination configuration.

SAP HANA Developer Guide

80 PUBLIC Getting Started with Application Development
 You can extend a configured HTTP destination, for example, by providing additional details concerning
proxy servers and logon details. The details concerning the extensions to the HTTP destination must be
specified in a separate configuration file. Like the original HTTP destination that the extension modifies,
the configuration-file extension must have the file extension .xshttpdest and be located in the same
package as the HTTP destination configuration file it extends and the application that uses it.
4. Check the HTTP destination configuration using the SAP HANA XS Administration Tool.
The SAP HANA XS Administration Tool is available on the SAP HANA XS Web server at the following URL:
http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/admin/cockpit.

Note
Access to details of HTTP destinations in the SAP HANA XS Administration Tool requires the credentials
of an authenticated database user and one of the following SAP HANA roles:
○ HTTPDestViewer
○ HTTPDestAdministrator

Related Information

HTTP Destination Configuration Syntax [page 83]

3.8.1 Tutorial: Create an HTTP Destination

Create an HTTP destination defining connection details for services running on specific hosts. The definition
can be referenced by an application.

Prerequisites

● You have the privileges granted by the role sap.hana.ide.roles::EditorDeveloper; this role is included in the
parent role sap.hana.ide.roles::Developer.
● You have been assigned the HTTPDestViewer or HTTPDestAdministrator user role.

Context

An HTTP destination defines connection details for services running on specific hosts whose details you want
to define and distribute. HTTP destination configurations are defined in a text file and can be referenced by an
application. You can also provide more (or modified) connection details in additional files called “extensions”;
values specified in extensions overwrite values specified in the original HTTP destination configuration.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 81
Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the application package structure:
a. From the context menu of the Content folder, choose Create Application.
b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter a package name, for example, testApp, and choose Create.
The system creates the index.html, .xsaccess, and .xsapp files.
d. Delete the index.html file.
3. Define the details of the HTTP destination.
You define the details of an HTTP destination in a configuration file that requires a specific syntax. The
configuration file containing the details of the HTTP destination must have the file
extension .xshttpdest.

Caution
You must place the HTTP destination configuration and the XSJS application that uses it in the same
application package. An application cannot reference an HTTP destination configuration that is located
in another application package.

a. From the context menu of the testApp folder, choose New File .
b. Enter a file name, for example, yahoo.xshttpdest, and choose Create.
c. Enter the following code in the new file yahoo.xshttpdest.

host = "download.finance.yahoo.com";
port = 80;
description = "my stock-price checker";
useSSL = false;
pathPrefix = "/d/quotes.csv?f=a";
authType = none;
proxyType = none;
proxyHost = "";
proxyPort = 0;
timeout = 0;

d. If necessary, set proxyType to http and enter your proxy host and port number.
e. Save the file.
4. View the activated HTTP destination.
You can use the SAP HANA XS Administration Tool to check the contents of an HTTP destination
configuration.

Note
To make changes to the HTTP Destination configuration, you must use a text editor, save the changes
and reactivate the file.

To start the SAP HANA XS Administration Tool, select the yahoo.xshttpdest file and choose
(Maintain Credentials) in the toolbar. The details of the HTTP destination are displayed.

SAP HANA Developer Guide

82 PUBLIC Getting Started with Application Development
 If you are using the Web-based XS Administration Tool, you can only make limited changes to the displayed
HTTP destination configuration, as follows:
○ Save
Commit to the repository any modifications made to the HTTP destination configuration in the current
session.
○ Edit
Display details of the corresponding extension to the selected HTTP destination configuration. If no
extension exists, the Edit option is not available.
○ Extend
Enables you to create an extension to the selected XS HTTP destination and associate the extension
with another (new or existing) package.

Note
This option is only available if the selected HTTP destination is provided as part of a delivery unit, for
example, as a destination template.

Related Information

HTTP Destination Configuration Syntax [page 83]

The HTTP Destination Extension [page 91]

3.8.2 HTTP Destination Configuration Syntax

An HTTP destination defines connection details for services running on specific hosts whose details you want
to define and distribute. Syntax rules apply to the contents of the HTTP destination configuration are checked
when you activate the configuration in the repository.

Example
The .xshttpdest Configuration File

The following example shows all possible keyword combinations in the SAP HANA XS application-access
(.xshttpdest) file.

Note
In the form shown below, the .xshttpdest file is not a working model; it is used to illustrate the syntax
for all possible options.

host = "download.finance.yahoo.com";
port = 80;
//All of the following keywords are optional
description = "";
useSSL = false;
sslAuth = client;
sslHostCheck = true;

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 83
 pathPrefix = "/d/quotes.csv?f=a";
authType = none;
samlProvider = "";
samlACS = "header";
samlAttributes = "";
samlNameId = ["email"];
proxyType = none;
proxyHost = ""; //in-line comments are allowed
proxyPort = 0;
timeout = 0;
remoteSID = "Q7E";
remoteClient = "007";
oAuthAppConfigPackage = "sap.hana.test";
oAuthAppConfig = "abapTest";

When you are defining the HTTP destination, bear in mind the following important syntax rules:

● A semi-colon (;) is required at the end of each line in the HTTP destination configuration, including the last
line in the file.
● String values must be wrapped in quotes (""), for example:
host = "download.finance.yahoo.com";

Note
The host and port keywords are mandatory; all other keywords are optional.

host

host = "download.finance.yahoo.com";

The host keyword is mandatory: it enables you to specify the hostname of the HTTP destination providing the
service or data you want your SAP HANA XS application to access.

port

port = 80;

The port keyword is mandatory; it enables you to specify the port number to use for connections to the HTTP
destination hosting the service or data you want your SAP HANA XS application to access.

description

description = "my short description of the HTTP connection";

SAP HANA Developer Guide

84 PUBLIC Getting Started with Application Development
The optional keyword description enables you to provide a short description of the HTTP destination you want
to configure. If you do not want to provide a description, include the description but leave the entry between the
quotes empty, for example, “”.

useSSL

useSSL = [true | false];

The optional keyword useSSL is of type Boolean and enables you to specify if the outbound connections
between SAP HANA XS and the HTTP destination is secured with the Secure Sockets Layer (SSL) protocol
(HTTPS).

Note
Setting this option does not configure SSL; if you want to use SSL to secure connections to the configured
destination, you must ensure that SAP HANA is already set up to enable secure outbound connections using
SSL.

If useSSL = true, you can set the authentication type with the keyword sslAuth. You can also use the
sslHostCheck to enable a check which ensures that the certificate used for authentication is valid (matches
the host).

sslAuth

sslAuth = [client | anonymous];

If useSSL = true, you can use the keyword sslAuth to set the authentication type. The following values are
permitted:

● client
(Default setting). You must create a TRUST store entry in the SAP HANA XS Admin Tool's Trust manager (or
use an exisiting one that is known to the HTTP destination configuration) and maintain the trust
relationship with the SSL server, for example, by adding a certificate to the trust store that is used for the
authentication process.
● anonymous
A built-in key is used for SSL encryption; no TRUST store is needed.. No authentication via SSL is possible.

sslHostCheck

sslHostCheck = [true | false];

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 85
If useSSL = true, you can use the keyword sslHostCheck to enable a check which ensures that the
certificate used for authentication is valid (matches the host). The following values are permitted:

● true
(Default setting). The SSL certificate subject must match the host name. For example, if SSL server
certificate CN=server1.acme.com, then the host parameter must be server1.acme.com. If there is no
match, SSL terminates.
● false
No host check is performed. Note that if the SSL server certificate is CN=server1.acme.com, and you use
“localhost” as a connection parameter (because this certificate is installed on its own server), then this
works with sslHostCheck deactivated (sslHostCheck=false).

pathPrefix

pathPrefix = "";

The optional keyword pathPrefix enables you to specify a text element to add to the start of the URL used for
connections to the service specified in the HTTP destination configuration. For example, pathPrefix = "/d/
quotes.csv?f=a" inserts the specified path into the URL called by the connection.

authType

authType = [none | basic | AssertionTicket | SamlAssertion |

SamlAssertionPropagation];

The optional keyword authType enables you to specify the authentication method that must be used for
connection requests for the service located at the HTTP destination specified in the configuration, for example,
“basic”, which requires users to provide a user name and password as authentication credentials. Permitted
values for the authType are “none”, “basic”, and “AssertionTicket”. If no authentication type is specified, the
default setting “none” applies.

The AssertionTicket option is for use with XSJS applications that want to enable access to HTTP services
running on remote SAP servers using single sign-on (SSO) with SAP assertion tickets. If the AssertionTicket
option is enabled, a user with administration privileges in SAP HANA must use the parameter
saplogontickettruststore to specify the location of the trust store containing the assertion tickets.

Tip
The saplogontickettruststore parameter can be set in [indexserver | xsengine].ini authentication
saplogontickettruststore .

If authType = AssertionTicket is set you also need to set values for the keywords remoteSID and
remoteclient.

For authType = SamlAssertion;, you must also set the subproperties samlProvider, samlACS,
samlAttributes, and samlNameId.

SAP HANA Developer Guide

86 PUBLIC Getting Started with Application Development
samlProvider

samlProvider = "";

If you set authType = SamlAssertion, you must also set the subproperty samlProvider, which enables
you to specify the entityID of the remote SAML party.

samlACS

samlACS = "header";

If you set authType = SamlAssertion, you must also set the subproperty samlACS, which enables you to
specify the way in which SAML assertions or responses are sent. The following values are supported:

● "" (empty string)

A SAML response (including the SAML assertion) is sent to the HTTP destination end point as a POST
parameter.
● /saml/acs/sso
If you provide a URL path, the SAML response (including the SAML Assertion) is sent to the specified
endpoint in an additional Web connection to establish the authentication context (session).When the
outbound communication is being established, there are two connections: first to the specified end point
(for example, /saml/asc/sso) and then to the destination service end point.
● header
The SAML response (including the SAML assertion) is sent in the HTTP header authorization with the
following syntax: Authorization: SAML2.0 &lt;base-64-saml-response&gt;.
● parameter:assertion
The SAML Assertion is sent as a POST parameter. This flavor is needed for JAM integrations.

samlAttributes

samlAttributes = "name1=<property>&name2=<property>";

If you set authType = SamlAssertion, you must also set the subproperty samlAttributes, which enables
you to specify additional attributes for the SAML Assertion.

samlNameId

samlNameId = ["email", "unspecified"];

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 87
If you set authType = SamlAssertion, you must also set the subproperty samlNameId, which enables you
to define a list of name-ID mappings. The following values are supported:

● email
● unspecified

For example, if you have an e-mail maintained in SAP HANA User Self Services (USS), the SAML assertion
contains your e-mail address; if you do not have a e-mail address maintained in SAP HANA USS, the mapping
is “unspecified”.

proxyType

proxytype = none;

The optional keyword proxyType enables you to specify if a proxy server must be used to resolve the host name
specified in the HTTP destination configuration file, and if so, which type of proxy. The following values are
allowed:

● none
● http
● socks

Caution
proxyType replaces and extends the functionality previously provided with the keyword useProxy. For
backward compatibility, the useProxy is still allowed but should not be used any more.

To define the proxy host and the port to connect on, use the keywords proxyHost and proxyPort
respectively.

If you want to include the proxy-related information in a separate configuration (a so-called extension to the
original HTTP destination configuration), you must set proxyType = none in the original HTTP destination
configuration. In the HTTP destination extension that references and modifies the original HTTP destination,
you can change the proxy setting to proxyType = http. You must then provide the corresponding host name
of the proxy server and a port number to use for connections.

proxyHost

proxyHost = "";

If you use the keyword useProxy = true to specify that a proxy server must be used to resolve the target
host name specified in the HTTP destination configuration, you must use the proxyHost and proxyPort
keywords to specify the fully qualified name of the host providing the proxy service (and the port number to use
for connections). The name of the proxy host must be wrapped in quotes, as illustrated in the following
example,

proxyHost = "myproxy.hostname.com"

SAP HANA Developer Guide

88 PUBLIC Getting Started with Application Development
proxyPort

proxyPort = 8080;

If you use the keyword useProxy = true to indicate that a proxy server must be used to resolve the host
name specified in the HTTP destination configuration, you must also use the proxyPort keyword (in
combination with proxyHost =) to specify the port on which the proxy server accepts connections.

timeout

timeout = -1;

The optional keyword timeout enables you to specify for how long (in milliseconds) an application tries to
connect to the remote host specified in the HTTP destination configuration, for example, timeout = 5000;
(5 seconds). By default, the timeout interval is set to -1, which means that there is no limit to the time required
to connect to the server specified in the HTTP destination configuration. In the default setting, the application
keeps trying to connect to the destination server either until the server responds, however long this takes, or
the underlying request-session timeout (300 seconds) is reached. The default setting (-1) is intended to help in
situations where the destination server is slow to respond, for example, due to high load.

remoteSID

remoteSID = "Q7E";

The optional keyword remoteSID enables you to specify the SID of a remote ABAP system. You use this
keyword in combination with the remoteClient keyword, for example, to enable an application to log on to an
ABAP system that is configured to provide SAP assertion tickets. If the XSJS application service requires
access to remote services, you can create an HTTP destination that defines the logon details required by the
remote ABAP system and specifies SSO with SAP assertion tickets as the logon authentication method.

Note
In the XS Administration Tool, the value specified in an HTTP destination configuration file with the
remoteSID keyword is displayed in the SAP SID field in the AUTHENTICATION section of the application's
runtime configuration. The SAP SID option is only available if you select SAP Assertion Ticket as the
authentication type in the application's runtime configuration.

remoteClient

remoteClient = "007";

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 89
The optional keyword remoteClient enables you to specify the client number to use when logging on to a
remote ABAP system. You use this keyword in combination with the remoteSID keyword, for example, to
enable an application to logon to an ABAP system that is configured to provide SAP assertion tickets. If the
XSJS application service requires access to remote services, you can create an HTTP destination that defines
the logon details required by the remote ABAP system and specifies SSO with SAP assertion tickets as the
logon authentication method.

Note
In the XS Administration Tool, the value specified in an HTTP destination configuration file with the
remoteClient keyword is displayed in the SAP Client field in the AUTHENTICATION section of the
application's runtime configuration. The SAP Client option is only available if you select SAP Assertion Ticket
as the authentication type in the application's runtime configuration.

oAuthAppConfigPackage

oAuthAppConfigPackage = "sap.hana.test";

Use the optional keyword oAuthAppConfigPackage enables you to specify the location of the package that
contains the oAuth application configuration to be used by an HTTP destination configuration.

oAuthAppConfig

oAuthAppConfig = "abapTest";

Use the optional keyword oAuthAppConfig enables you to specify the name of the oAuth application
configuration to be used by an HTTP destination configuration. The OAuth application configuration is a file
describing the application-specific OAuth parameters that are used to enable access to a resource running on a
remote HTTP destination. The OAuth application configuration is defined in a design-time artifact with the
mandatory file suffix .xsoauthappconfig; the configuration file must be specified using the JSON format.

modifies

modifies pkg.path.testApp:yahoo.xshttpdest;

The keyword modifies can only be used in an HTTP extension file and enables you to reference an existing
HTTP destination (or extension) whose settings you want to further extend or modify. The settings in an HTTP
destination extension overwrite any identical settings in the original HTTP destination configuration. The HTTP
destination configuration referenced by the modifies keyword must already exist.

SAP HANA Developer Guide

90 PUBLIC Getting Started with Application Development
 Note
The HTTP destination extension does not have to be tied to a particular XSJS application; it can be located
in any application package or subpackage. For this reason, you must include the full package path to the
HTTP destination extension when using the modifies keyword.

Related Information

The HTTP Destination Extension [page 91]

3.8.3 The HTTP Destination Extension

An HTTP destination defines connection details for services running on specific hosts whose details you want
to define and distribute. An extension to an HTTP destination provides additional information or modifies
values set in the original configuration.

You can use one or more extension to an HTTP destination configuration; the extensions include additions to
the original settings or modifications to the values set in the original configuration. For example, you could
include basic configuration settings in an HTTP destination and provide details of any required proxy settings in
a separate, so-called “extension”.

You define an extension to an HTTP destination configuration in a text file that contains the details of the
modifications you want to apply to the connection details for the original HTTP destination. The HTTP
destination extension uses a mandatory syntax comprising a list of keyword=value pairs, for example, host =
"download.finance.myhoo.com";. The same syntax rules apply for the basic HTTP destination
configuration and any extensions. Both files must also have the file suffix .xshttpdest, for example,
myHTTPdestination.xshttpdest or myHTTPextension.xshttpdest.After creating and saving the HTTP
destination extension, you must activate it in the SAP HANA repository.

Note
The HTTP destination extension does not have to be tied to a particular XSJS application; it can be located
in any application package or subpackage. For this reason, you must include the full package path to the
HTTP destination extension.

The following configuration file for the HTTP destination yahooProxy.xshttpdest illustrates how to modify
the proxy settings specified in the HTTP destination yahoo.xshttpdest, located in the application package
pkg.path.testApp.

modifies pkg.path.testApp:yahoo.xshttpdest;
proxyType = http;
proxyHost = "proxy.host.name.com";
proxyPort = 8080;

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 91
 Note
For backward compatibility, the keyword userProxy still works; however, it has been replaced with the
keyword proxyType, which takes the values: [none | http | socks].

After activation, you can view the details of the new HTTP destination extension using the SAP HANA XS
Administration tool.

Note
Access to details of HTTP destinations in the SAP HANA XS Administration Tool requires the credentials of
an authenticated database user and one of the following SAP HANA roles:

● HTTPDestViewer
● HTTPDestAdministrator

3.8.4 Tutorial: Create an OAuth Configuration Package

Create the files required to enable a service that uses OAuth to authorize access to a resource running on a
remote HTTP destination.

Prerequisites

● An HTTP destination configuration (.xshttpdest)

● Your SAP HANA database user has the permissions granted by the following roles:
○ RuntimeConfAdministrator
○ HTTPDestAdministrator
○ oAuthAdmin

Context

An OAuth configuration package is a collection of configuration files that define the details of how an
application uses OAuth to enable logon to a resource running on a remote HTTP destination.

An HTTP destination defines connection details for services running on specific hosts whose details you want
to define and distribute. Additional syntax rules that apply to the contents of the HTTP destination
configuration are checked when you activate the configuration in the repository.

An OAuth configuration requires the following dependent configuration files:

● OAuth application configuration (<filename>.xsoauthappconfig)

Describes the configuration of the OAuth application parameters, including the name and package location
of the associated client configuration and any mandatory or optional scopes.

SAP HANA Developer Guide

92 PUBLIC Getting Started with Application Development
● OAuth client configuration (<filename>.xsoauthclientconfig)
Describes the configuration of the OAuth client, including the client ID, the client authentication type, and
the name and package location of the associated client flavor.
● OAuth client flavor configuration (<filename>.xsoauthclientflavor)
Describes the OAuth client flavor setup used by the XS OAuth client configuration, including the protocol
steps and the parameters to be set. Note that normally you do not need to change the OAuth client flavor
configuration.

Tip
You connect the OAuth configuration to the HTTP destination configuration in the HTTP destination's
runtime configuration. Access to the runtime configuration tools requires the permissions included in an
administrator role.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create an OAuth application configuration.

You need to create the base configuration for your OAuth application in a design-time file with the
mandatory file-extension .xsoauthappconfig. The application configuration is stored in the SAP HANA
repository and must be activated to create the corresponding catalog objects.

a. Create the design-time file that contains your OAuth application configuration, for example,
oauthDriveApp.xsoauthappconfig.
b. Define the details of the new OAuth application configuration, as follows:

{
"clientConfig" :
"sap.hana.xs.oAuth.lib.providerconfig.providermodel:abap_ac",
"mandatoryScopes" : ["OAUTH2_TEST_SCOPE1", "OAUTH2_TEST_SCOPE2"],
"description" : "ABAP Testapplication for OAuth"
}

Note
In this example, the OAuth client configuration is located in the package
sap.hana.xs.oAuth.lib.providerconfig.providermodel; you can change the path to suit
your own requirements.

3. Create an OAuth client configuration (optional).

You create the client configuration for your OAuth application in a design-time file with the mandatory file-
extension .xsoauthclientconfig. You can either use an existing client configuration from the package
sap.hana.xs.oAuth.lib.providerconfig.providermodel or create your own client configuration.
The application configuration is stored in the SAP HANA repository and must be activated to create the
corresponding catalog objects.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 93
 a. Create the design-time file that contains your OAuth client configuration, for example,
ABAPv1.xsoauthclientconfig.
b. Define the details of the new OAuth client configuration, as follows:

{
"clientFlavor" :
"sap.hana.xs.oAuth.lib.providerconfig.providermodel:abap_ac",
"clientID" : "<OAuth ClientId registered at ABAP>",
"clientAuthType" : "basic",
"authorizationEndpointURL" : "/sap/bc/sec/oauth2/authorize",
"tokenEndpointURL" : "/sap/bc/sec/oauth2/token",
"revocationEndpointURL" : "/sap/bc/sec/oauth2/revoke",
"redirectURL" : "<External_XS_HOST>:<PORT>/sap/hana/xs/
oAuth/lib/runtime/tokenRequest.xsjs",
"flow" : "authCode",
"scopeReq" : "maxScopes",
"description" : "OAuth Client for SAP Application Server
ABAP - Authorization Code Flow"
}

4. Create the OAuth client flavor (optional).

The OAuth client flavor file is a design-time artifact that provides details of the OAuth protocol for a client
application which uses the services provided by a corresponding OAuth application. The OAuth client flavor
steps are defined in a design-time artifact with the mandatory file suffix .xsoauthclientflavor; the
configuration file must be specified using the JSON format.

Tip
You do not have to create the OAuth client flavor from scratch; SAP HANA provides some example
OAuth client flavors which you can use. The example OAuth client flavors are located in the following
package: sap.hana.xs.oAuth.lib.providerconfig.providermodel.

The following example shows the required format and syntax for the contents of
the .xsoauthclientflavor artifact:

{ "parameters":[
{ "flavorStep":"1Aut", "paramLocation":"uri", "paramName":"client_id",
"paramValue":"client_id", "valueType":"eval",
"paramMandatory":"true" },
{ "flavorStep":"2Gra", "paramLocation":"head", "paramName":"Authorization",
"paramValue":"Basic Authentication", "valueType":"sec",
"paramMandatory":"true" },
{ "flavorStep":"3Prc", "paramLocation":"head", "paramName":"Bearer",
"paramValue":"access_token", "valueType":"sec",
"paramMandatory":"true" },
{ "flavorStep":"4Ref", "paramLocation":"head", "paramName":"Authorization",
"paramValue":"Basic Authentication", "valueType":"sec",
"paramMandatory":"true" },
{ "flavorStep":"5Rev", "paramLocation":"para", "paramName":"token",
"paramValue":"access_token", "valueType":"sec",
"paramMandatory":"true" },
] }

Note
The example above is not complete; it is intended for illustration purposes only.

5. Activate all the XS OAuth configuration files.

Activating the configuration files creates the corresponding catalog objects.

SAP HANA Developer Guide

94 PUBLIC Getting Started with Application Development
6. Add the OAuth configuration to the runtime configuration of the HTTP destination configuration that
requires it.

To start the SAP HANA XS Administration Tool, select the xshttpdest file and choose (Maintain
Credentials) in the toolbar. The details of the HTTP destination are displayed.
a. Choose the OAuth Details tab.
b. Choose Edit Browse OAuth App Configs .
c. Select an OAuth application configuration from the list displayed.
The name of the application configuration you choose and the absolute path to the package where it is
located are displayed in the appropriate fields, for example:
○ OAuth App Config Package: sap.hana.test
○ OAuth App Config Name: abapTest

Note
The values displayed here must also be present in the HTTP destination configuration to which the
OAuth configuration applies.

For example, the HTTP destination corresponding to the OAuth configuration you are setting up in this
task must also contain entries that describe the name and package location of the OAuth application
configuration to use:

oAuthAppConfigPackage = "sap.hana.test";
oAuthAppConfig = "abapTest";

d. Navigate to the OAuth client configuration and set the client secret.
e. Choose Save to update the runtime confguration for the HTTP destination.

Related Information

OAuth Application Configuration Syntax [page 95]

OAuth Client Configuration Syntax [page 97]
OAuth Client Flavor Syntax [page 102]

3.8.4.1 OAuth Application Configuration Syntax

The format and syntax required in a design-time artifact describing an OAuth application configuration.

The OAuth application configuration is a file describing the application-specific OAuth parameters that are
used to enable access to a resource running on a remote HTTP destination. The OAuth application
configuration is defined in a design-time artifact with the mandatory file suffix .xsoauthappconfig; the
configuration file must be specified using the JSON format.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 95
 Note
The following code example is not a working example; it is provided for illustration purposes, only.

{
"clientConfig":"sap.hana.xs.oAuth.lib.providerconfig.providermodel:abap_ac",
"description":"ABAP test application for OAuth",
"mandatoryScopes":["OAUTH2_TEST_SCOPE1", "OAUTH2_TEST_SCOPE2"],
"optionalScopes":["OAUTH2_TEST_SCOPE3", "OAUTH2_TEST_SCOPE4"],
"modifies":"sap.hana.test:abapTest"
}

An OAuth configuration requires the following dependent configuration files:

● OAuth application configuration (.xsoauthappconfig)

● OAuth client configuration (.xsoauthclientconfig)
● OAuth client flavor configuration (.xsoauthclientflavor)

clientConfig

Use the clientConfig keyword to specify the fully qualified name of the associated xsoauthclientconfig
artifact, using the format <path.to.package>:<XSOauthClientConfigObjectName>.

"clientConfig":"sap.hana.xs.oAuth.lib.providerconfig.providermodel:abap_ac",

Note
It is mandatory to specifiy the name and location of the package containing the associated OAuth client
configuration.

description

Use the description keyword to provide an optional short description of the contents of the OAuth
application configuration.

"description":"ABAP test application for OAuth",

mandatoryScopes

Use the mandatoryScopes keyword to specify one or more (in an array) of strings describing the mandatory
permissions requested by the client.

"mandatoryScopes":["OAUTH2_TEST_SCOPE1", "OAUTH2_TEST_SCOPE2"],

SAP HANA Developer Guide

96 PUBLIC Getting Started with Application Development
optionalScopes

Use the optionalScopes keyword to specify one or more (in an array) of strings describing the optional
permissions to be used by the client.

"optionalScopes":["OAUTH2_TEST_SCOPE3", "OAUTH2_TEST_SCOPE4"],

modifies

Use the modifies keyword to indicate that the current XS OAuth application configuration (for example,
abapTest2.xsoauthappconfig is based on (and extends) another SAP HANA XS OAuth application
configuration (for example, abapTest.xsoauthappconfig). You must specify the fully qualified name of the
associated SAP HANA XS OAuth application configuration artifact (xsoauthappconfig), using the format
<path.to.package>:<ObjectName>.

"modifies":"sap.hana.test:abapTest.xsoauthappconfig",

Related Information

OAuth Client Configuration Syntax [page 97]

OAuth Client Flavor Syntax [page 102]

3.8.4.2 OAuth Client Configuration Syntax

The format and syntax required in a design-time artifact describing the OAuth client configuration.

The OAuth client configuration is a file describing details of the client parameters for an application which uses
the services provided by a corresponding OAuth application that enables access to a resource running on a
remote HTTP destination. The OAuth client configuration is defined in a design-time artifact with the
mandatory file suffix .xsoauthclientconfig; the configuration file must be specified using the JSON
format. The following code example shows the contents of a typical OAuth client configuration.

Note
The following code example is not a working example; it is provided for illustration purposes, only.

{
"clientFlavor":"sap.hana.xs.oAuth.lib.providerconfig.providermodel:abap_ac",
"clientID":"<The OAuth ClientId you registered at ABAP>",
"clientAuthType":"basic",
"authorizationEndpointURL":"/sap/bc/sec/oauth2/authorize",
"tokenEndpointURL":"/sap/bc/sec/oauth2/token",
"revocationEndpointURL":"/sap/bc/sec/oauth2/revoke",
"flow":"authCode",

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 97
 "description":"OAuth Client for ABAP server",
"samlIssuer":"" ,
"redirectURL":"<HOST>:<PORT>/sap/hana/xs/oAuth/lib/runtime/tokenRequest.xsjs",
"scopeReq":"maxScopes",
"shared":"true",
"modifies":"sap.hana.xs.oAuth.lib.providerconfig.providermodel:abap_ac"
}

In this example, the OAuth client configuration is located in the package com.acme.oAuth.lib; change the
path specified in clientFlavor to suit your own requirements. You will also have to change the value
specified for clientID and redirectURL.

Tip
SAP HANA provides some example OAuth client configurations which you can use; you can find them in the
following package: sap.hana.xs.oAuth.lib.providerconfig.providermodel

clientFlavor

Use the clientFlavor keyword to specify the fully qualified name of the associated XS OAuth client flavor
configuration artifact, for example, ABAPv1.xsoauthclientfavor; you must use the format
<path.to.package>:<ObjectName> (no file extension is required).

"clientFlavor":"sap.hana.xs.oAuth.lib.providerconfig.providermodel:abap_ac",

Note
It is mandatory to specifiy the name and location of the package containing the associated OAuth client
flavor configuration.

clientID

Use the clientID keyword to define a string that specifies the customer's ID, which is used to identify the
client with the server. The clientID must be changed to suit your requirements. Typically, the client ID is
obtained by registering with a specific service provider.

"clientID" : "<The OAuth ClientId you registered at ABAP>",

Note
It is mandatory to define the clientID.

SAP HANA Developer Guide

98 PUBLIC Getting Started with Application Development
clientAuthType

Use the clientAuthType keyword to define a number that specifies the client authentication type, for
example, “cert” or “basic”.

"clientAuthType" : "basic",

Note
It is mandatory to define the clientAuthType.

The following values are permitted:

● basic (user and password)

● cert (authentication by client certificate)

authorizationEndpointURL

Use the authorizationEndpointURL keyword to specify a string that defines the authorization endpoint.
The authorization endpoint is the endpoint on the authorization server where the resource owner logs on and
grants authorization to the client application.

"authorizationEndpointURL" : "/sap/bc/sec/oauth2/authorize",

Note
It is mandatory to define the authorizationEndpointURL.

tokenEndpointURL

Use the tokenEndpointURL keyword to to specify a string that defines the token endpoint. The token
endpoint is the endpoint on the authorization server where the client application exchanges the authorization
code, the client ID, and the client secret for an access token.

"tokenEndpointURL" : "/sap/bc/sec/oauth2/token",

Note
It is mandatory to define the tokenEndpointURL.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 99
revocationEndpointURL

Use the revocationEndpointURL keyword to to specify a string that defines the token endpoint. The token
endpoint is the endpoint on the authorization server where the client application exchanges the authorization
code, the client ID, and the client secret for an access token.

"revocationEndpointURL" : "/sap/bc/sec/oauth2/revoke",

Note
It is mandatory to define a value for the revocationEndpointURL.

flow

Use the flow keyword to specify a number that defines the authorization flow used during the authentication
exchange, for example, saml2Bearer or authCode.

"flow" :"saml2Bearer",

Note
It is mandatory to define a value for flow.

The following values are permitted:

● saml2Bearer
● authCode

description

Use the optional description keyword to provide a short description of the OAuth client configuration.

"description": "OAuth Client for SAP App Server ABAP - Authorization Code Flow"

samlIssuer

Use the optional samlIssuer keyword to specify a string that defines the SAML issuer ID. The SAML issuer ID
describes the issuer of the SAML token. The SAML bearer extension enables the validation of SAML tokens as
part of granting the OAuth access token.

SAP HANA Developer Guide

100 PUBLIC Getting Started with Application Development
 Note
You set this parameter only if the parameter flow is set to saml2Bearer, for example,
"flow" :"saml2Bearer".

"samlIssuer" : "" ,

redirectURL

Use the redirectURL keyword to specify a string that defines the redirection endpoint. The redirection
endpoint is the endpoint in the client application where the resource owner is redirected to, after having
granted authorization at the authorization endpoint. The redirectURL must be changed to suit your
requirements.

"redirectURL" : "<HOST>:<PORT>/sap/hana/xs/oAuth/lib/runtime/tokenRequest.xsjs",

Note
If "flow" : "authCode", it is mandatory to define a value for the redirectURL.

scopeReq

Use the scopeReq keyword to specify whether the maximum available scope from all applications using this
client configuration is always requested or the scope set is specified iteratively.

"scopeReq" : "maxScopes",

The following values are permitted:

● maxScopes
● iterativeScopes

Note
Currently only maxScopes is implemented.

shared

Use the shared keyword to specify a number that defines whether the if the XS OAuth client configuration can
be shared between applications.

"shared" : "false",

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 101
The following values are permitted:

● true (shared)
● false (not shared)

Note
Currently only true is implemented.

modifies

Use the modifies keyword to indicate that the current XS OAuth client configuration, for example,
abap_ac1.xsoauthclientconfig, is based on (and extends) another SAP HANA XS OAuth client
configuration (for example, abap_ac.xsoauthclientconfig). You must specify the fully qualified name of
the associated OAuth client configuration artifact (<fileName>.xsoauthclientconfig), using the format
<path.to.package>:<ArtifactName>.xsoauthclientconfig.

"modifies":"sap.hana.xs.oAuth.lib.providerconfig.providermodel:abap_ac.xsoauthcli
entconfig",

Related Information

OAuth Client Flavor Syntax [page 102]

OAuth Application Configuration Syntax [page 95]

3.8.4.3 OAuth Client Flavor Syntax

The format and syntax required in a design-time artifact that describes the OAuth client flavors.

The OAuth client flavor file provides details of the OAuth protocol for a client application that uses the services
provided by a corresponding OAuth application. The OAuth client flavor steps are defined in a design-time
artifact with the mandatory file suffix .xsoauthclientflavor; the configuration file must be specified using
the JSON format.

Note
The following example of an OAuth client flavor configuration is incomplete; it is intended for illustration
purposes only.

{ "parameters":[
{ "flavorStep":"1Aut", "paramLocation":"uri", "paramName":"client_id",
"paramValue":"client_id", "valueType":"eval",
"paramMandatory":"true" },

SAP HANA Developer Guide

102 PUBLIC Getting Started with Application Development
 { "flavorStep":"1Aut", "paramLocation":"uri", "paramName":"redirect_uri",
"paramValue":"redirect_uri", "valueType":"eval",
"paramMandatory":"true" },
{ "flavorStep":"1Aut", "paramLocation":"uri", "paramName":"scope",
"paramValue":"scope", "valueType":"eval",
"paramMandatory":"true" },
{ "flavorStep":"1Aut", "paramLocation":"uri", "paramName":"response_type",
"paramValue":"code", "valueType":"litr",
"paramMandatory":"true" },
{ "flavorStep":"1Aut", "paramLocation":"uri", "paramName":"state",
"paramValue":"state", "valueType":"eval",
"paramMandatory":"true" },
{ "flavorStep":"2Gra", "paramLocation":"head", "paramName":"Authorization",
"paramValue":"Basic Authentication", "valueType":"sec",
"paramMandatory":"true" },
{ "flavorStep":"2Gra", "paramLocation":"head", "paramName":"Content-Type",
"paramValue":"application/x-www-form-urlencoded", "valueType":"litr",
"paramMandatory":"true" },
{ "flavorStep":"2Gra", "paramLocation":"para", "paramName":"code",
"paramValue":"code", "valueType":"eval",
"paramMandatory":"true" },
{ "flavorStep":"2Gra", "paramLocation":"para", "paramName":"grant_type",
"paramValue":"authorization_code", "valueType":"litr",
"paramMandatory":"true" },
{ "flavorStep":"2Gra", "paramLocation":"para", "paramName":"client_id",
"paramValue":"client_id", "valueType":"eval",
"paramMandatory":"true" },
{ "flavorStep":"2Gra", "paramLocation":"para", "paramName":"redirect_uri",
"paramValue":"redirect_uri", "valueType":"eval",
"paramMandatory":"true" },
{ "flavorStep":"3Prc", "paramLocation":"head", "paramName":"Bearer ",
"paramValue":"access_token", "valueType":"sec",
"paramMandatory":"true" },
{ "flavorStep":"4Ref", "paramLocation":"head", "paramName":"Authorization",
"paramValue":"Basic Authentication", "valueType":"sec",
"paramMandatory":"true" },
{ "flavorStep":"4Ref", "paramLocation":"head", "paramName":"Content-Type",
"paramValue":"application/x-www-form-urlencoded", "valueType":"litr",
"paramMandatory":"true" },
{ "flavorStep":"4Ref", "paramLocation":"para", "paramName":"grant_type",
"paramValue":"refresh_token", "valueType":"litr",
"paramMandatory":"true" },
{ "flavorStep":"4Ref", "paramLocation":"para", "paramName":"refresh_token",
"paramValue":"refresh_token", "valueType":"sec",
"paramMandatory":"true" },
{ "flavorStep":"5Rev", "paramLocation":"para", "paramName":"token",
"paramValue":"access_token", "valueType":"sec",
"paramMandatory":"true" },
] }

It is not necessary to create your own OAuth client flavor from scratch; SAP HANA provides some OAuth client
flavors for a selection of OAuth server scenarios, which you can use without modification.

Tip
The example OAuth client flavors are located in the package
sap.hana.xs.oAuth.lib.providerconfig.providermodel.

However, you do need to modify the OAuth client flavor artifact for the following scenarios:

● Modifications are required (or have already been made) to the API of an available OAuth server.
● A connection is required to a new OAuth server not covered by the scenarios included in the SAP HANA
configuration templates.

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 103
parameters

Use the parameters keyword to define a list of parameter-values pairs, for example,
"paramLocation":"uri" that support the specification defined in the OAuth client configuration file
<filename>.oxauthclientconfig.

flavorStep

Use the flavorStep keyword to specify a step in the procedure used by the client flavor, as illustrated in the
following example

"flavorStep":"saml",

The following values are permitted:

● IAut
● 2Gra
● 3Prc
● 4Ref
● 5Rev
● saml

paramLocation

Use the paramLocation keyword to specify the location of the parameter defined, as shown in the following
example:

"paramLocation":"uri",

The following values are permitted:

● uri
Universal resource indicator
● head
In the request header
● para
In the request body

SAP HANA Developer Guide

104 PUBLIC Getting Started with Application Development
paramName

Use the paramName keyword to specify the name of the parameter defined in “paramLocation”, as shown in
the following example:

"paramName":"token",

The parameter name depends on the local setup of your client configuration.

paramValue

Use the paramValue keyword to specify a value for the parameter name specified in “paramName”.

"paramValue":"access_token",

The parameter name depends on the local setup of your client configuration.

valueType

Use the valueType keyword to specify the type of value expected by the parameter defined in “paramValue”.

"valueType":"sec",

The following values are permitted:

● litr
Literal value
● eval
The value is evaluated by the OAuth client runtime
● sec
The value is evaluated by the OAuth client runtime in a secure way

paramMandatory

Use the paramMandatory keyword to specify if a parameter is required or not.

"paramMandatory":"true",

The following values are permitted:

● true
Required
● false
Not Required

SAP HANA Developer Guide

Getting Started with Application Development PUBLIC 105
Related Information

OAuth Client Configuration Syntax [page 97]

OAuth Application Configuration Syntax [page 95]

SAP HANA Developer Guide

106 PUBLIC Getting Started with Application Development
4 Setting up the Persistence Model

The persistence model defines the schema, tables, sequences, and views that specify what data to make
accessible for consumption by applications and how.

In SAP HANA Extended Application Services (SAP HANA XS), the persistence model is mapped to the
consumption model that is exposed to client applications and users, so that data can be analyzed and
displayed in the appropriate form in the client application interface.

SAP HANA XS enables you to create database schema, tables, views, and sequences as design-time files in the
repository. Repository files can be read by applications that you develop. When implementing the data
persistence model, you can use either the Core Data Services (CDS) syntax or HDBtable syntax (or both).
“HDBtable syntax” is a collective term; it includes the different configuration schema for each of the various
design-time data artifacts, for example: schema (.hdbschema), sequence (.hdbsequence), table
(.hdbtable), and view (.hdbview).

All repository files including your view definition can be transported (along with tables, schema, and
sequences) to other SAP HANA systems, for example, in a delivery unit. A delivery unit is the medium SAP
HANA provides to enable you to assemble all your application-related repository artifacts together into an
archive that can be easily exported to other systems.

Note
You can also set up data-provisioning rules and save them as design-time objects so that they can be
included in the delivery unit that you transport between systems.

The rules you define for a data-provisioning scenario enable you to import data from comma-separated values
(CSV) files directly into SAP HANA tables using the SAP HANA XS table-import feature. The complete data-
import configuration can be included in a delivery unit and transported between SAP HANA systems for reuse.

As part of the process of setting up the basic persistence model for SAP HANA XS, you create the following
Repository artifacts:

Data Persistence Artifacts by Language Syntax and File Suffix

Artifact Type CDS HDBTable

Schema .hdbschema * .hdbschema

Synonym .hdbsynonym* .hdbsynonym

Table .hdbdd .hdbtable

Table Type .hdbdd .hdbstructure

View .hdbdd .hdbview

Association .hdbdd -

Sequence .hdbsequence* .hdbsequence

Structured Types .hdbdd -

Data import .hdbti .hdbti

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 107
 Note
(*) To create a schema, a synonym, or a sequence, you must use the appropriate .hdbtable artifact, for
example, .hdbschema, .hdbsynonym, or .hdbsequence. You can reference both artifacts in a CDS
document.

On activation of a repository artifact, the file suffix (for example, .hdbdd or .hdb[table|view]) is used to
determine which runtime plug-in to call during the activation process. When you activate a design-time artifact
in the SAP HANA Repository, the plug-in corresponding to the artifact's file suffix reads the contents of
repository artifact selected for activation (for example, a table, a view, or a complete CDS document that
contains multiple artifact definitions), interprets the artifact definitions in the file, and creates the appropriate
corresponding runtime objects in the catalog.

Related Information

Data Persistence with CDS [page 108]

Data Persistence with HDBtable [page 217]
Data Provisioning using Table Import [page 203]

4.1 Creating the Persistence Model in Core Data Services

Core data services (CDS) is an infrastructure that can be used to define and consume semantically rich data
models in SAP HANA.

The model described in CDS enables you to use the Data Definition Language to define the artifacts that make
up the data-persistence model. You can save the data-persistence object definition as a CDS artifact, that is; a
design-time object that you manage in the SAP HANA repository and activate when necessary. Using a data
definition language (DDL), a query language (QL), and an expression language (EL), CDS enables write
operations, transaction semantics, and more.

You can use the CDS specification to create a CDS document which defines the following artifacts and
elements:

● Entities (tables)
● Views
● User-defined data types (including structured types)
● Contexts
● Associations
● Annotations

Note
To create a schema, a synonym, or a sequence, you must use the appropriate .hdbtable artifact, for
example, .hdbschema, .hdbsynonym, or .hdbsequence. You can reference these artifacts in a CDS
document.

SAP HANA Developer Guide

108 PUBLIC Setting up the Persistence Model
CDS artifacts are design-time definitions that are used to generate the corresponding run-time objects, when
the CDS document that contains the artifact definitions is activated in the SAP HANA repository. In CDS, the
objects can be referenced using the name of the design-time artifact in the repository; in SQL, only the name of
the catalog object can be used. The CDS document containing the design-time definitions that you create
using the CDS-compliant syntax must have the file extension .hdbdd, for example, MyCDSTable.hdbdd.

Related Information

CDS Annotations [page 123]

4.1.1 Tutorial: Get Started with CDS

You can use the Data Definition Language (DDL) to define a table, which is also referred to as an “entity” in SAP
HANA Core Data Services (CDS). The finished artifact is saved in the repository with the extension
(suffix) .hdbdd, for example, MyTable.hdbdd.

Prerequisites

● You have created a schema definition MYSCHEMA.hdbschema.

● You have SELECT and INSERT privileges on the schema so you can see the generated catalog objects and
insert data.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create a new CDS document; the document is used to define the details of the entity you want to create.
a. In the repository package structure, select the package where you want to create the new CDS
document and, from the context menu, choose New File .
b. Enter the name of the entity in the File Name field, for example, BOOK.hdbdd, and choose Create.

Note
If you are using a CDS document to define a single CDS-compliant entity, the name of the CDS
document must match the name of the entity defined in the CDS document, for example, with the
entity keyword. In the example in this tutorial, you would save the entity definition “BOOK” in the
CDS document BOOK.hdbdd.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 109
3. Define the table entity.
Add the entity-definition code.

Note

Choose (Insert Snippet) to insert a code template. The following mandatory keywords are, by default,
assigned the following values:
○ namespace = <Current package path>
○ context = <New DDL file name>
The name space declared in a CDS document must match the repository package in which the object
the document defines is located.

In this example, the CDS document BOOK.hdbdd that defines the CDS entity “BOOK” must reside in the
package mycompany.myapp1.

namespace mycompany.myapp1;
@Schema : 'MYSCHEMA'
@Catalog.tableType: #COLUMN
@Catalog.index: [ { name : 'MYINDEX1', unique : true, order : #DESC,
elementNames : ['ISBN'] } ]
entity BOOK {
key Author : String(100);
key BookTitle : String(100);
ISBN : Integer not null;
Publisher : String(100);
};

4. Save the CDS document BOOK.hdbdd.

The activation creates the following table in the schema MYSCHEMA, both of which are visible in the
catalog:

Catalog.MYSCHEMA.Tables.mycompany.myapp1::BOOK

The following public synonym is also created, which can be referenced using the standard CDS-compliant
query notation:

"mycompany.myapp1::BOOK"

5. In the catalog, add an entry to the BOOK entity.

a. Select the BOOK file under the MYSCHEMA Tables node.

The table definition is displayed, as shown in the example below:

b. Choose Open Content.

The data preview appears, displaying an empty table.

SAP HANA Developer Guide

110 PUBLIC Setting up the Persistence Model
 c. Choose (Insert).
d. In the new row, enter some test data and save your entries, as shown in the example below:

6. Run a simply query using the standard CDS-compliant query notation.

a. In the context menu of the Book file, choose Generate Select.
The table row you just created is displayed in the SQL result view.
b. In the SQL console, enter and execute the following query.

SELECT COUNT(*) FROM "mycompany.myapp1::BOOK" WHERE "Author" =

'Shakespeare';

4.1.2 Create a CDS Document

A CDS document is a design-time source file that contains definitions of the objects you want to create in the
SAP HANA catalog.

Prerequisites

● You have created a schema for the CDS catalog objects generated when the CDS document is activated in
the repository, for example, MYSCHEMA.
● You have SELECT privileges on the schema so you can see the generated catalog objects.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 111
Context

CDS documents are design-time source files that contain DDL code that describes a persistence model
according to rules defined in Core Data Services. CDS documents have the file suffix .hdbdd. Activating the
CDS document creates the corresponding catalog objects in the specified schema.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the CDS document that defines the entity you want to create.
a. In the package structure, select the package where you want to create the CDS document and from
the context menu choose New File .
b. Enter the name of the entity in the File Name field, for example, MyModel.hdbdd, and choose Create.
3. Define the details of the CDS artifacts.
In the CDS document you just created , for example, MyModel.hdbdd, add the CDS-definition code to the
file. The CDS code describes the CDS artifacts you want to add, for example, entity definitions, type
definitions, view definitions, and so on. Note that the following code examples are provided for illustration
purposes only:
a. Add a namespace and schema name.
The namespace is the name of the repository package in which you created the new CDS document,
for example, acme.com.hana.cds.data.

The @Schema annotation defines the name of the schema to use to store the artifacts that are
generated when the CDS document is activated. The schema name must be inserted before the top-
level element in the CDS document, which in this example is the context MyModel.

namespace acme.com.hana.cds.data;
@Schema: 'SAP_HANA_CDS'
context MyModel {

};

Note
If the schema you specify does not exist, you cannot activate the new CDS document.

b. Add structured types, if required.

Use the type keyword to define a type artifact in a CDS document. In this example, you add the user-
defined types and structured types to the top-level entry in the CDS document, the context MyModel.

namespace acme.com.hana.cds.data;
@Schema: 'SAP_HANA_CDS'
context MyModel {
type BusinessKey : String(10);
type SString : String(40);
type <[...]>

SAP HANA Developer Guide

112 PUBLIC Setting up the Persistence Model
 <[...]>
};

c. Add a new context, if required.

Contexts enable you to group together related artifacts. A CDS document can only contain one top-
level context, for example, MyModel {};. Any new context must be nested within the top-level entry
in the CDS document, as shown in the following example.

namespace acme.com.hana.cds.data;
@Schema: 'SAP_HANA_CDS'
context MyModel {
type BusinessKey : String(10);
type SString : String(40);
type <[...]>
context MasterData {
<[...]>
};
context Sales {
<[...]>
};
context Purchases {
<[...]>
};
};

d. Add new entities.

You can add the entities either to the top-level entry in the CDS document; in this example, the context
MyModel or to any other context, for example, MasterData, Sales, or Purchases. In this example,
the new entities are column-based tables in the MasterData context.

namespace acme.com.hana.cds.data;
@Schema: 'SAP_HANA_CDS'
context MyModel {
type BusinessKey : String(10);
type SString : String(40);
type <[...]>
context MasterData {
@Catalog.tableType : #COLUMN
Entity Addresses {
key AddressId: BusinessKey;
City: SString;
PostalCode: BusinessKey;
<[...]>
};
@Catalog.tableType : #COLUMN
Entity BusinessPartner {
key PartnerId: BusinessKey;
PartnerRole: String(3);
<[...]>
};
};
context Sales {
<[...]>
};
context Purchases {
<[...]>
};
};

4. Save the CDS document.

5. Check that a catalog object has been successfully created for each of the artifacts defined in the CDS
document.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 113
 When a CDS document is activated, the activation process generates a corresponding catalog object for
each of the artifacts defined in the document; the location in the catalog is determined by the type of
object generated.
a. Open the catalog.
b. Navigate to the catalog location where the new object has been created, for example:

Catalog Object Location

Entities Catalog <MYSCHEMA> Tables

Types Catalog <MYSCHEMA> Procedures Table Types

c. Select one of the new tables you have just created to display its definition.

4.1.2.1 CDS Documents

CDS documents are design-time source files that contain DDL code that describes a persistence model
according to rules defined in Core Data Services.

CDS documents have the file suffix .hdbdd. Each CDS document must contain the following basic elements:

● A name space declaration

The name space you define must be the first declaration in the CDS document and match the absolute
package path to the location of the CDS document in the repository. It is possible to enclose parts of the
name space in quotes (“”), for example, to solve the problem of illegal characters in name spaces.

Note
If you use the file-creation wizard to create a new CDS document, the name space is inserted
automatically; the inserted name space reflects the repository location you select to create the new
CDS document.

● A schema definition
The schema you specify is used to store the catalog objects that are defined in the CDS document, for
example: entities, structured types, and views. The objects are generated in the catalog when the CDS
document is activated in the SAP HANA repository.
● CDS artifact definitions
The objects that make up your persistence model, for example: contexts, entities, structured types, and
views

Each CDS document must contain one top-level artifact, for example: a context, a type, an entity, or a view. The
name of the top-level artifact in the CDS document must match the file name of the CDS document, without
the suffix. For example, if the top-level artifact is a context named MyModel, the name of the CDS document
must be MyModel.hdbdd.

Note
On activation of a repository file in, the file suffix, for example, .hdbdd, is used to determine which runtime
plug-in to call during the activation process. The plug-in reads the repository file selected for activation, in

SAP HANA Developer Guide

114 PUBLIC Setting up the Persistence Model
 this case a CDS-compliant document, parses the object descriptions in the file, and creates the appropriate
runtime objects in the catalog.

If you want to define multiple CDS artifacts within a single CDS document (for example, multiple types,
structured types, and entities), the top-level artifact must be a context. A CDS document can contain multiple
contexts and any number and type of artifacts. A context can also contain nested sub-contexts, each of which
can also contain any number and type of artifacts.

When a CDS document is activated, the activation process generates a corresponding catalog object for each
of the artifacts defined in the document; the location in the catalog is determined by the type of object
generated. The following table shows the catalog location for objects generated by the activation of common
CDS artifacts.

Catalog Location for CDS-generated Artifacts

CDS Artifact Catalog Location

Entity <SID> Catalog <MYSCHEMA> Tables

View <SID> Catalog <MYSCHEMA> Views

Structured type <SID> Catalog <MYSCHEMA> Procedures Table Types

The following example shows the basic structure of a single CDS document that resides in the package
acme.com.hana.cds.data in the SAP HANA repository. the CDS document defines the following CDS
artifacts:

● Types:
○ BusinessKey and SString
● Entities:
○ Addresses, BusinessPartners, Header, and Item
● Contexts:
○ MyModel, which contains the nested contexts: MasterData, Sales, and Purchases
● External references
The using keyword enables you to refer to artifacts defined in separate CDS documents, for example,
MyModelB.hdbdd. You can also assign an alias to the reference, for example, AS <alias>.
● Annotations
Built-in annotations, for example, @Catalog, @Schema, and @nokey, are important elements of the CDS
syntax used to define CDS-compliant catalog objects. You can define your own custom annotations, too.

Note
The following code snippet is incomplete [...]; it is intended for illustration purposes only.

Sample Code

namespace acme.com.hana.cds.data;
using acme.com.hana.cds.data::MyModelB.MyContextB1 as ic;
@Schema: 'SAP_HANA_CDS'
context MyModel {
type BusinessKey : String(10);
type SString : String(40);
type <[...]>
context MasterData {

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 115
 @Catalog.tableType : #COLUMN
Entity Addresses {
key AddressId: BusinessKey;
City: SString;
PostalCode: BusinessKey;
<[...]>
};
@Catalog.tableType : #COLUMN
Entity BusinessPartner {
key PartnerId: BusinessKey;
PartnerRole: String(3);
<[...]>
};
};
context Sales {
@Catalog.tableType : #COLUMN
Entity Header {
key SalesOrderId: BusinessKey;
<[...]>
};
@Catalog.tableType : #COLUMN
@MyAnnotation : 'foo'
Entity Item {
key SalesOrderId: BusinessKey;
key SalesOrderItem: BusinessKey;
<[...]>
};
};
context Purchases {
<[...]>
};
};

Related Information

CDS Namespaces [page 119]

CDS Annotations [page 123]
External Artifacts in CDS [page 116]

4.1.2.2 External Artifacts in CDS

You can define an artifact in one CDS document by referring to an artifact that is defined in another CDS
document.

The CDS syntax enables you to define a CDS artifact in one document by basing it on an “external” artifact - an
artifact that is defined in a separate CDS document. Each external artifact must be explicitly declared in the
source CDS document with the using keyword, which specifies the location of the external artifact, its name,
and where appropriate its CDS context.

Tip
The using declarations must be located in the header of the CDS document between the namespace
declaration and the beginning of the top-level artifact, for example, the context.

SAP HANA Developer Guide

116 PUBLIC Setting up the Persistence Model
The external artifact can be either a single object (for example, a type, an entity, or a view) or a context. You can
also include an optional alias in the using declaration, for example, ContextA.ContextA1 as ic. The alias
(ic) can then be used in subsequent type definitions in the source CDS document.

//Filename = Pack1/Distributed/ContextB.hdbdd
namespace Pack1.Distributed;
using Pack1.Distributed::ContextA.T1;
using Pack1.Distributed::ContextA.ContextAI as ic;
using Pack1.Distributed::ContextA.ContextAI.T3 as ict3;
using Pack1.Distributed::ContextA.ContextAI.T3.a as a; // error, is not an
artifact
context ContextB {
type T10 {
a : T1; // Integer
b : ic.T2; // String(20)
c : ic.T3; // structured
d : type of ic.T3.b; // String(88)
e : ict3; // structured
x : Pack1.Distributed::ContextA.T1; // error, direct reference not allowed
};
context ContextBI {
type T1 : String(7); // hides the T1 coming from the first using declaration
type T2 : T1; // String(7)
};
};

The CDS document ContextB.hdbdd shown above uses external artifacts (data types T1 and T3) that are
defined in the “target” CDS document ContextA.hdbdd shown below. Two using declarations are present in
the CDS document ContextB.hdbdd; one with no alias and one with an explictly specified alias (ic). The first
using declaration introduces the scalar type Pack1.Distributed::ContextA.T1. The second using
declaration introduces the context Pack1.Distributed::ContextA.ContextAI and makes it accessible by
means of the explicitly specified alias ic.

Note
If no explicit alias is specified, the last part of the fully qualified name is assumed as the alias, for example
T1.

The using keyword is the only way to refer to an externally defined artifact in CDS. In the example above, the
type x would cause an activation error; you cannot refer to an externally defined CDS artifact directly by using
its fully qualilfed name in an artifact definition.

//Filename = Pack1/Distributed/ContextA.hdbdd
namespace Pack1.Distributed;
context ContextA {
type T1 : Integer;
context ContextAI {
type T2 : String(20);
type T3 {
a : Integer;
b : String(88);
};
};
};

Note
Whether you use a single or multiple CDS documents to define your data-persistence model, each CDS
document must contain only one top-level artifact, and the name of the top-level artifact must correspond

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 117
 to the name of the CDS document. For example, if the top-level artifact in a CDS document is ContextA,
then the CDS document itself must be named ContextA.hdbdd.

4.1.2.3 CDS Naming Conventions

Rules and restrictions apply to the names of CDS documents and the package in which the CDS document
resides.

The rules that apply for naming CDS documents are the same as the rules for naming the packages in which
the CDS document is located. When specifying the name of a package or a CDS document (or referencing the
name of an existing CDS object, for example, within a CDS document), bear in mind the following rules:

● File suffix
The file suffix differs according to SAP HANA XS version:
○ XS classic
.hdbdd, for example, MyModel.hdbdd.
○ XS advanced
.hdbcds, for example, MyModel.hdbcds.
● Permitted characters
CDS object and package names can include the following characters:
○ Lower or upper case letters (aA-zZ) and the underscore character (_)
○ Digits (0-9)
● Forbidden characters
The following restrictions apply to the characters you can use (and their position) in the name of a CDS
document or a package:
○ You cannot use either the hyphen (-) or the dot (.) in the name of a CDS document.
○ You cannot use a digit (0-9) as the first character of the name of either a CDS document or a package,
for example, 2CDSobjectname.hdbdd (XS classic) or acme.com.1package.hdbcds (XS advanced).
○ The CDS parser does not recognize either CDS document names or package names that consist
exclusively of digits, for example, 1234.hdbdd (XS classic) or acme.com.999.hdbcds (XS
advanced).

Caution
Although it is possible to use quotation marks (“”) to wrap a name that includes forbidden characters, as a
general rule, it is recommended to follow the naming conventions for CDS documents specified here in order
to avoid problems during activation in the repository.

Related Information

CDS Documents [page 114]

CDS Namespaces [page 119]

SAP HANA Developer Guide

118 PUBLIC Setting up the Persistence Model
4.1.2.4 CDS Namespaces

The namespace is the path to the package in the SAP HANA Repository that contains CDS artifacts such as
entities, contexts, and views.

In a CDS document, the first statement must declare the namespace that contains the CDS elements which
the document defines, for example: a context, a type, an entity, or a view. The namespace must match the
package name where the CDS elements specified in the CDS document are located. If the package path
specified in a namespace declaration does not already exist in the SAP HANA Repository, the activation
process for the elements specified in the CDS document fails.

It is possible to enclose in quotation marks (“”) individual parts of the namespace identifier, for example,
"Pack1".pack2. Quotes enable the use of characters that are not allowed in regular CDS identifiers; in CDS, a
quoted identifier can include all characters except the dot (.) and the double colon (::). If you need to use a
reserved keyword as an identifier, you must enclose it in quotes, for example, “Entity”. However, it is
recommended to avoid the use of reserved keywords as identifiers.

Note
You can also use quotation marks (“”) to wrap the names of CDS artifacts (entities, views) and elements
(columns...).

The following code snippet applies to artifacts created in the Repository package /Pack1/pack2/ and shows
some examples of valid namespace declarations, including namespaces that use quotation marks (“”).

Note
A CDS document cannot contain more than one namespace declaration.

namespace Pack1.pack2;
namespace "Pack1".pack2;
namespace Pack1."pack2";
namespace "Pack1"."pack2";

The following code snippet applies to artifacts created in the Repository package /Pack1/pack2/ and shows
some examples of invalid namespace declarations.

namespace pack1.pack2; // wrong spelling

namespace "Pack1.pack2"; // incorrect use of quotes
namespace Pack1.pack2.MyDataModel; // CDS file name not allowed in namespace
namespace Jack.Jill; // package does not exist

The examples of namespace declarations in the code snippet above are invalid for the following reasons:

● pack1.pack2;
pack1 is spelled incorrectly; the namespace element requires a capital P to match the corresponding
location in the Repository, for example, Pack1.
● "Pack1.pack2";
You cannot quote the entire namespace path; only individual elements of the namespace path can be
quoted, for example, "Pack1".pack2; or Pack1."pack2";.
● Pack1.pack2.MyDataModel;
The namespace declaration must not include the names of elements specified in the CDS document itself,
for example, MyDataModel.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 119
● Jack.Jill;
The package path Jack.Jill; does not exist in the Repository.

Related Information

CDS Documents [page 114]

4.1.2.5 CDS Contexts

You can define multiple CDS-compliant entities (tables) in a single file by assigning them to a context.

The following example illustrates how to assign two simple entities to a context using the CDS-
compliant .hdbdd syntax; you store the context-definition file with a specific name and the file
extension .hdbdd, for example, MyContext.hdbdd.

Note
If you are using a CDS document to define a CDS context, the name of the CDS document must match the
name of the context defined in the CDS document, for example, with the “context” keyword.

In the example below, you must save the context definition “Books” in the CDS document Books.hdbdd. In
addition, the name space declared in a CDS document must match the repository package in which the object
the document defines is located.

The following code example illustrates how to use the CDS syntax to define multiple design-time entities in a
context named Books.

namespace com.acme.myapp1;
@Schema : 'MYSCHEMA'
context Books {
@Catalog.tableType: #COLUMN
@Catalog.index : [ { name : 'MYINDEX1', unique : true, order : #DESC,
elementNames : ['ISBN'] } ]
entity Book {
key AuthorID : String(10);
key BookTitle : String(100);
ISBN : Integer not null;
Publisher : String(100);
};
@Catalog.tableType: #COLUMN
@Catalog.index : [ { name: 'MYINDEX2', unique: true, order: #DESC,
elementNames: ['AuthorNationality'] } ]
entity Author {
key AuthorName : String(100);
AuthorNationality : String(20);
AuthorBirthday : String(100);
AuthorAddress : String(100);
};
};

Activation of the file Books.hdbdd containing the context and entity definitions creates the catalog objects
“Book” and “Author”.

SAP HANA Developer Guide

120 PUBLIC Setting up the Persistence Model
 Note
The namespace specified at the start of the file, for example, com.acme.myapp1 corresponds to the
location of the entity definition file (Books.hdbdd) in the application-package hierarchy .

Nested Contexts

The following code example shows you how to define a nested context called InnerCtx in the parent context
MyContext. The example also shows the syntax required when making a reference to a user-defined data type
in the nested context, for example, (field6 : type of InnerCtx.CtxType.b;).

The type of keyword is only required if referencing an element in an entity or in a structured type; types in
another context can be referenced directly, without the type of keyword. The nesting depth for CDS contexts
is restricted by the limits imposed on the length of the database identifier for the name of the corresponding
SAP HANA database artifact (for example, table, view, or type); this is currently limited to 126 characters
(including delimiters).

Note
The context itself does not have a corresponding artifact in the SAP HANA catalog; the context only
influences the names of SAP HANA catalog artifacts that are generated from the artifacts defined in a given
CDS context, for example, a table or a structured type.

namespace com.acme.myapp1;
@Schema: 'MySchema'
context MyContext {
// Nested contexts
context InnerCtx {

Entity MyEntity {
…
};
Type CtxType {
a : Integer;
b : String(59);
};
};
type MyType1 {
field1 : Integer;
field2 : String(40);
field3 : Decimal(22,11);
field4 : Binary(11);
};

type MyType2 {
field1 : String(50);
field2 : MyType1;
};

type MyType3 {
field1 : UTCTimestamp;
field2 : MyType2;
};

@Catalog.index : [{ name : 'IndexA', order : #ASC, unique: true,

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 121
 elementNames : ['field1'] }]
entity MyEntity1 {
key id : Integer;
field1 : MyType3 not null;
field2 : String(24);
field3 : LocalDate;
field4 : type of field3;
field5 : type of MyType1.field2;
field6 : type of InnerCtx.CtxType.b; // refers to nested context
field7 : InnerCtx.CtxType; // more context references
};
};

Name Resolution Rules

The sequence of definitions inside a block of CDS code (for example, entity or context) does not matter for
the scope rules; a binding of an artifact type and name is valid within the confines of the smallest block of code
containing the definition, except in inner code blocks where a binding for the same identifier remains valid. This
rules means that the definition of nameX in an inner block of code hides any definitions of nameX in outer code
blocks.

Note
An identifier may be used before its definition without the need for forward declarations.

context OuterCtx
{
type MyType1 : Integer;
type MyType2 : LocalDate;
context InnerCtx
{
type Use1 : MyType1; // is a String(20)
type Use2 : MyType2; // is a LocalDate
type MyType1 : String(20);
};
type invalidUse : Use1; // invalid: Use1 is not
// visible outside of InnerCtx
type validUse : InnerCtx.Use1; // ok
};

No two artifacts (including namespaces) can be defined whose absolute names are the same or are different
only in case (for example, MyArtifact and myartifact), even if their artifact type is different (entity and
view). When searching for artifacts, CDS makes no assumptions which artifact kinds can be expected at certain
source positions; it simply searches for the artifact with the given name and performs a final check of the
artifact type.

The following example demonstrates how name resolution works with multiple nested contexts, Inside context
NameB, the local definition of NameA shadows the definition of the context NameA in the surrounding scope. This
means that the definition of the identifier NameA is resolved to Integer, which does not have a sub-
component T1. The result is an error, and the compiler does not continue the search for a “better” definition of
NameA in the scope of an outer (parent) context.

context OuterCtx
{
context NameA

SAP HANA Developer Guide

122 PUBLIC Setting up the Persistence Model
 {
type T1 : Integer;
type T2 : String(20);
};
context NameB
{
type NameA : Integer;
type Use : NameA.T1; // invalid: NameA is an Integer
type Use2 : OuterCtx.NameA.T2; // ok
};
};

Related Information

CDS User-Defined Data Types [page 150]

4.1.2.6 CDS Annotations

CDS supports built-in annotations, for example, @Catalog, @Schema, and @nokey, which are important
elements of the CDS documents used to define CDS-compliant catalog objects. However, you can define your
own custom annotations, too.

Example

namespace mycompany.myapp1;
@Schema : 'MYSCHEMA'
context Books {
@Catalog.tableType: #COLUMN
@Catalog.index: [ { name : 'MYINDEX1', unique : true, order : #DESC,
elementNames : ['ISBN'] } ]
entity BOOK {
key Author : String(100);
key BookTitle : String(100);
ISBN : Integer not null;
Publisher : String(100);
};
@Catalog.tableType : #COLUMN
@nokey
entity MyKeylessEntity
{
element1 : Integer;
element2 : UTCTimestamp;
@SearchIndex.text: { enabled: true }
element3 : String(7);
};
@GenerateTableType : false
Type MyType1 {
field1 : Integer;
field2 : Integer;
field3 : Integer;
};
};

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 123
Overview

The following list indicates the annotations you can use in a CDS document:

● @Catalog
● @nokey
● @Schema
● @GenerateTableType
● @SearchIndex
● @WithStructuredPrivilegeCheck

@Catalog

The @Catalog annotation supports the following parameters, each of which is described in detail in a dedicated
section below:

● @Catalog.index
Specify the type and scope of index to be created for the CDS entity, for example: name, order, unique/
non-unique
● @Catalog.tableType
Specify the table type for the CDS entity, for example, column, row, global temporary.

You use the @Catalog.index annotation to define an index for a CDS entity. The @Catalog.index annotation used
in the following code example ensures that an index called Index1 is created for the entity MyEntity1 along
with the index fields fint and futcshrt. The order for the index is ascending (#ASC) and the index is unique.

namespace com.acme.myapp1;
@Catalog.tableType : #COLUMN
@Schema: 'MYSCHEMA'
@Catalog.index:[ { name:'Index1', unique:true, order:#ASC, elementNames:['fint',
'futcshrt' ] } ]
entity MyEntity1 {
key fint:Integer;
fstr :String(5000);
fstr15 :String(51);
fbin :Binary(4000);
fbin15 :Binary(51);
fint32 :Integer64;
fdec53 :Decimal(5,3);
fdecf :DecimalFloat;
fbinf :BinaryFloat;
futcshrt:UTCDateTime not null;
flstr :LargeString;
flbin :LargeBinary;
};

You can define the following values for the @Catalog.index annotation:

● elementNames : ['<name1>', '<name2>' ]

The names of the fields to use in the index; the elements are specified for the entity definition, for example,
elementNames:['fint', 'futcshrt' ]
● name : '<IndexName>'
The names of the index to be generated for the specified entity, for example, name:'myIndex'

SAP HANA Developer Guide

124 PUBLIC Setting up the Persistence Model
● order
Create a table index sorted in ascending or descending order. The order keywords #ASC and #DESC can be
only used in the BTREE index (for the maintenance of sorted data) and can be specified only once for each
index.
○ order : #ASC
Creates an index for the CDS entity and sorts the index fields in ascending logical order, for example: 1,
2, 3...
○ order : #DESC
Creates a index for the CDS entity and sorts the index fields in descending logical order, for example:
3, 2, 1...
● unique
Creates a unique index for the CDS entity. In a unique index, two rows of data in a table cannot have
identical key values.
○ unique : true
Creates a unique index for the CDS entity. The uniqueness is checked and, if necessary, enforced each
time a key is added to (or changed in) the index.
○ unique : false
Creates a non-unique index for the CDS entity. A non-unique index is intended primarily to improve
query performance, for example, by maintaining a sorted order of values for data that is queried
frequently.

You use the @Catalog.tableType annotation to define the type of CDS entity you want to create. The
@Catalog.tableType annotation determines the storage engine in which the underlying table is created.

namespace com.acme.myapp1;
@Schema: 'MYSCHEMA'
context MyContext1 {
@Catalog.tableType : #COLUMN
entity MyEntity1 {
key ID : Integer;
name : String(30);
};
@Catalog.tableType : #ROW
entity MyEntity2 {
key ID : Integer;
name : String(30);
};
@Catalog.tableType : #GLOBAL_TEMPORARY
entity MyEntity3 {
ID : Integer;
name : String(30);
};
};

You can define the following values for the @Catalog.tableType annotation:

● #COLUMN
Create a column-based table. If the majority of table access is through a large number of tuples, with only a
few selected attributes, use COLUMN-based storage for your table type.
● #ROW
Create a row-based table. If the majority of table access involves selecting a few records, with all attributes
selected, use ROW-based storage for your table type.
● #GLOBAL_TEMPORARY
Set the scope of the created table. Data in a global temporary table is session-specific; only the owner
session of the global temporary table is allowed to insert/read/truncate the data. A global temporary table

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 125
 exists for the duration of the session, and data from the global temporary table is automatically dropped
when the session is terminated. A global temporary table can be dropped only when the table does not
have any records in it.

Note
The SAP HANA database uses a combination of table types to enable storage and interpretation in both
ROW and COLUMN forms. If no table type is specified in the CDS entity definition, the default value
#COLUMN is applied to the table created on activation of the design-time entity definition.

@nokey

An entity usually has one or more key elements, which are flagged in the CDS entity definition with the key
keyword. The key elements become the primary key of the generated SAP HANA table and are automatically
flagged as “not null”. Structured elements can be part of the key, too. In this case, all table fields resulting from
the flattening of this structured field are part of the primary key.

Note

However, you can also define an entity that has no key elements. If you want to define an entity without a key,
use the @nokey annotation. In the following code example, the @nokey annotation ensures that the entity
MyKeylessEntity defined in the CDS document creates a column-based table where no key element is
defined.

namespace com.acme.myapp1;
@Schema: 'MYSCHEMA'
@Catalog.tableType : #COLUMN
@nokey
entity MyKeylessEntity
{
element1 : Integer;
element2 : UTCTimestamp;
element3 : String(7);
};

@Schema

The @Schema annotation is only allowed as a top-level definition in a CDS document. In the following code
example @Schema ensures that the schema MYSCHEMA is used to contain the entity MyEntity1, a column-
based table.

namespace com.acme.myapp1;
@Schema: 'MYSCHEMA'
@Catalog.tableType : #COLUMN
entity MyEntity1 {
key ID : Integer;
name : String(30);
};

SAP HANA Developer Guide

126 PUBLIC Setting up the Persistence Model
 Note
If the schema specified with the @Schema annotation does not already exist, an activation error is displayed
and the entity-creation process fails.

The schema name must adhere to the SAP HANA rules for database identifiers. In addition, a schema name
must not start with the letters SAP*; the SAP* namespace is reserved for schemas used by SAP products and
applications.

@GenerateTableType

For each structured type defined in a CDS document, an SAP HANA table type is generated, whose name is
built by concatenating the elements of the CDS document containing the structured-type definition and
separating the elements by a dot delimiter (.). The new SAP HANA table types are generated in the schema
that is specified in the schema annotation of the respective top-level artifact in the CDS document containing
the structured types.

Note
Table types are only generated for direct structure definitions; no table types are generated for derived
types that are based on structured types.

If you want to use the structured types inside a CDS document without generating table types in the catalog,
use the annotation @GenerateTableType : false.

@SearchIndex

The annotation @SearchIndex enables you to define which of the columns should be indexed for search
capabilities, for example, {enabled : true}. To extend the index search definition, you can use the
properties text or fuzzy to specify if the index should support text-based or fuzzy search, as illustrated in the
following example:

entity MyEntity100
{
element1 : Integer;
@SearchIndex.text: { enabled: true }
element2 : LargeString;
@SearchIndex.fuzzy: { enabled: true }
element3 : String(7);
};

Tip
For more information about setting up search features and using the search capability, see the SAP HANA
Search Developer Guide .

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 127
@WithStructuredPrivilegeCheck

The annotation @WithStructuredPrivilegeCheck enables you to control access to data (for example, in a
view) by means of privileges defined with the Data Control Language (DCL), as illustrated in the following
example:

@WithStructuredPrivilegeCheck
view MyView as select from Foo {
<select_list>
} <where_groupBy_Having_OrderBy>;

Related Information

User-Defined CDS Annotations [page 128]

CDS Structured Type Definition [page 153]

4.1.2.6.1 User-Defined CDS Annotations

In CDS, you can define your own custom annotations.

The built-in core annotations that SAP HANA provides, for example, @Schema, @Catalog, or @nokey, are
located in the namespace sap.cds; the same namespace is used to store all the primitive types, for example,
sap.cds::integer and sap.cds::SMALLINT.

However, the CDS syntax also enables you to define your own annotations, which you can use in addition to the
existing “core” annotations. The rules for defining a custom annotation in CDS are very similar way the rules
that govern the definition of a user-defined type. In CDS, an annotation can be defined either inside a CDS
context or as the single, top-level artifact in a CDS document. The custom annotation you define can then be
assigned to other artifacts in a CDS document, in the same way as the core annotations, as illustrated in the
following example:

@Catalog.tableType : #ROW
@MyAnnotation : 'foo'
entity MyEntity {
key Author : String(100);
key BookTitle : String(100);
ISBN : Integer not null;
Publisher : String(100);
}

CDS supports the following types of user-defined annotations:

● Scalar annotations
● Structured annotations
● Annotation arrays

SAP HANA Developer Guide

128 PUBLIC Setting up the Persistence Model
Scalar Annotations

The following example shows how to define a scalar annotation.

annotation MyAnnotation_1 : Integer;

annotation MyAnnotation_2 : String(20);

In annotation definitions, you can use both the enumeration type and the Boolean type, as illustrated in the
following example.

type Color : String(10) enum { red = 'rot'; green = 'grün'; blue = 'blau'; };
annotation MyAnnotation_3 : Color;
annotation MyAnnotation_4 : Boolean;

Structured Annotations

The following example shows how to define a structured annotation.

annotation MyAnnotation_5 {
a : Integer;
b : String(20);
c : Color;
d : Boolean;
};

The following example shows how to nest annotations in an anonymous annotation structure.

annotation MyAnnotation_7 {
a : Integer;
b : String(20);
c : Color;
d : Boolean;
s {
a1 : Integer;
b1 : String(20);
c1 : Color;
d1 : Boolean;
};
};

Array Annotations

The following example shows how to define an array-like annotation.

annotation MyAnnotation_8 : array of Integer;

annotation MyAnnotation_9 : array of String(12);
annotation MyAnnotation_10 : array of { a: Integer; b: String(10); };

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 129
4.1.2.6.2 CDS Annotation Usage Examples

Reference examples of the use of user-defined CDS annotations.

When you have defined an annotation, the user-defined annotation can be used to annotate other definitions. It
is possible to use the following types of user-defined annotations in a CDS document:

User-defined CDS Annotations

CDS Annotation Type Description

Scalar annotations [page 130] For use with simple integer or string annotations and enumeration or
Boolean types

Structured annotations [page 131] For use where you need to create a simple annotation structure or nest
an annotation in an anonymous annotation structure

Annotation arrays [page 131] For use where you need to assign the same annotation several times to
the same object.

Scalar Annotations

The following examples show how to use a scalar annotation:

@MyAnnotation_1 : 18
type MyType1 : Integer;
@MyAnnotation_2 : 'sun'
@MyAnnotation_1 : 77
type MyType2 : Integer;
@MyAnnotation_2 : 'sun'
@MyAnnotation_2 : 'moon' // error: assigning the same annotation twice is not
allowed.
type MyType3 : Integer;

Note
It is not allowed to assign an annotation to the same object more than once. If several values of the same
type are to be annotated to a single object, use an array-like annotation.

For annotations that have enumeration type, the enum values can be addressed either by means of their fully
qualified name, or by means of the shortcut notation (using the hash (#) sign. It is not allowed to use a literal
value, even if it matches a literal of the enum definition.

@MyAnnotation_3 : #red
type MyType4 : Integer;
@MyAnnotation_3 : Color.red
type MyType5 : Integer;
@MyAnnotation_3 : 'rot' // error: no literals allowed, use enum symbols
type MyType6 : Integer;

For Boolean annotations, only the values “true” or “false” are allowed, and a shortcut notation is available
for the value “true”, as illustrated in the following examples:

@MyAnnotation_4 : true
type MyType7 : Integer;

SAP HANA Developer Guide

130 PUBLIC Setting up the Persistence Model
 @MyAnnotation_4 // same as explicitly assigning the value “true”
type MyType8 : Integer;
@MyAnnotation_4 : false
type MyType9 : Integer;

Structured Annotations

Structured annotations can be assigned either as a complete unit or, alternatively, one element at a time. The
following example show how to assign a whole structured annotation:

@MyAnnotation_5 : { a : 12, b : 'Jupiter', c : #blue, d : false }

type MyType10 : Integer;
@MyAnnotation_5 : { c : #green } // not all elements need to be filled
type MyType11 : Integer;

The following example shows how to assign the same structured annotation element by element.

Note
It is not necessary to assign a value for each element.

@MyAnnotation_5.a : 12
@MyAnnotation_5.b : 'Jupiter'
@MyAnnotation_5.c : #blue
@MyAnnotation_5.d : false
type MyType12 : Integer;
@MyAnnotation_5.c : #green
type MyType13 : Integer;
@MyAnnotation_5.c : #blue
@MyAnnotation_5.d // shortcut notation for Boolean (true)
type MyType14 : Integer;

It is not permitted to assign the same annotation element more than once; assigning the same annotation
element more than once in a structured annotation causes an activation error.

@MyAnnotation_5 : { c : #green, c : #green } // error, assign an element once

only
type MyType15 : Integer;
@MyAnnotation_5.c : #green
@MyAnnotation_5.c : #blue // error, assign an element once only
type MyType16 : Integer;

Array-like Annotations

Although it is not allowed to assign the same annotation several times to the same object, you can achieve the
same effect with an array-like annotation, as illustrated in the following example:

@MyAnnotation_8 : [1,3,5,7]
type MyType30 : Integer;
@MyAnnotation_9 : ['Earth', 'Moon']
type MyType31 : Integer;
@MyAnnotation_10 : [{ a: 52, b: 'Mercury'}, { a: 53, b: 'Venus'}]

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 131
 type MyType32 : Integer;

Related Information

CDS Annotations [page 123]

CDS Documents [page 114]

4.1.2.7 CDS Comment Types

The Core Data Services (CDS) syntax enables you to insert comments into object definitions.

Example
Comment Formats in CDS Object Definitions

namespace com.acme.myapp1;

/**
* multi-line comment,
* for doxygen-style,
* comments and annotations
*/
type Type1 {
element Fstr: String( 5000 ); // end-of-line comment
Flstr: LargeString;
/*inline comment*/ Fbin: Binary( 4000 );
element Flbin: LargeBinary;
Fint: Integer;
element Fint64: Integer64;
Ffixdec: Decimal( 34, 34 /* another inline comment */);
element Fdec: DecimalFloat;
Fflt: BinaryFloat;
//complete line comment element Flocdat: LocalDate; LocalDate
temporarily switched off
//complete line comment Floctim: LocalTime;
element Futcdatim: UTCDateTime;
Futctstmp: UTCTimestamp;
};

Overview

You can use the forward slash (/) and the asterisk (*) characters to add comments and general information to
CDS object-definition files. The following types of comment are allowed:

● In-line comment
● End-of-line comment
● Complete-line comment
● Multi-line comment

SAP HANA Developer Guide

132 PUBLIC Setting up the Persistence Model
In-line Comments

The in-line comment enables you to insert a comment into the middle of a line of code in a CDS document. To
indicate the start of the in-line comment, insert a forward-slash (/) followed by an asterisk (*) before the
comment text. To signal the end of the in-line comment, insert an asterisk followed by a forward-slash
character (*/) after the comment text, as illustrated by the following example:.

element Flocdat: /*comment text*/ LocalDate;

End-of-Line Comment

The end-of-line comment enables you to insert a comment at the end of a line of code in a CDS document. To
indicate the start of the end-of-line comment, insert two forward slashes (//) before the comment text, as
illustrated by the following example:.

element Flocdat: LocalDate; // Comment text

Complete-Line Comment

The complete-line comment enables you to tell the parser to ignore the contents of an entire line of CDS code.
The comment out a complete line, insert two backslashes (//) at the start of the line, as illustrated in the
following example:

// element Flocdat: LocalDate; Additional comment text

Multi-Line Comments

The multi-line comment enables you to insert comment text that extends over multiple lines of a CDS
document. To indicate the start of the multi-line comment, insert a forward-slash (/) followed by an asterisk (*)
at the start of the group of lines you want to use for an extended comment (for example, /*). To signal the end
of the multi-line comment, insert an asterisk followed by a forward-slash character (*/). Each line between the
start and end of the multi-line comment must start with an asterisk (*), as illustrated in the following example:

/*
* multiline,
* doxygen-style
* comments and annotations
*/

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 133
4.1.3 Create an Entity in CDS
The entity is the core artifact for defining the persistence model using the CDS syntax. You create a database
entity as a design-time file in the SAP HANA repository.

Prerequisites

● You have created a schema for the CDS catalog objects, for example, MYSCHEMA.
● You have SELECT privileges on the schema so you can see the generated catalog objects.

Context

In the SAP HANA database, as in other relational databases, a CDS entity is a table with a set of data elements
that are organized using columns and rows. SAP HANA Extended Application Services (SAP HANA XS) enables
you to use the CDS syntax to create a database entity as a design-time file in the repository. Activating the CDS
entity creates the corresponding table in the specified schema.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the CDS entity-definition file.
a. In the package structure, select the package where you want to create the entity-definition file and
from the context menu choose New File .
b. Enter the name of the entity in the File Name field, for example, MyEntity.hdbdd, and choose Create.
3. Define the structure of the CDS entity.
Add the catalog- and entity-definition code to the new entity-definition file, as shown in the example below:

namespace acme.com.apps.myapp1;
@Schema : 'MYSCHEMA'
@Catalog.tableType : #COLUMN
@Catalog.index : [ { name : 'MYINDEX1', unique : true, order :#DESC,
elementNames : ['ISBN'] } ]
entity MyEntity {
key Author : String(100);
key BookTitle : String(100);
ISBN : Integer not null;
Publisher : String(100);
};

Note
If the schema you specify does not exist, you cannot activate the new CDS entity.

SAP HANA Developer Guide

134 PUBLIC Setting up the Persistence Model
4. Save the CDS entity-definition file.
5. Check that the new entity has been successfully created.
CDS entities are created in the Tables folder in the catalog.
a. Open the catalog.
b. Navigate to the catalog location where you created the new entity:
Catalog <MYSCHEMA> Tables
c. Select the new entity MyEntity to display its definition.

Related Information

Entity Element Modifiers [page 137]

CDS Entity Syntax Options [page 139]

4.1.3.1 CDS Entities

In the SAP HANA database, as in other relational databases, a CDS entity is a table with a set of data elements
that are organized using columns and rows.

A CDS entity has a specified number of columns, defined at the time of entity creation, but can have any
number of rows. Database entities also typically have meta-data associated with them; the meta-data might
include constraints on the entity or on the values within particular columns. SAP HANA Extended Application
Services (SAP HANA XS) enables you to create a database entity as a design-time file in the repository. All
repository files including your entity definition can be transported to other SAP HANA systems, for example, in
a delivery unit. You can define the entity using CDS-compliant DDL.

Note
A delivery unit is the medium SAP HANA provides to enable you to assemble all your application-related
repository artifacts together into an archive that can be easily exported to other systems.

The following code illustrates an example of a single design-time entity definition using CDS-compliant DDL. In
the example below, you must save the entity definition “MyTable” in the CDS document MyTable.hdbdd. In
addition, the name space declared in a CDS document must match the repository package in which the object
the document defines is located.

namespace com.acme.myapp1;
@Schema : 'MYSCHEMA'
@Catalog.tableType : #COLUMN
@Catalog.index : [ { name : 'MYINDEX1', unique : true, order :#DESC,
elementNames : ['ISBN'] } ]
entity MyTable {
key Author : String(100);
key BookTitle : String(100);
ISBN : Integer not null;
Publisher : String(100);
};

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 135
If you want to create a CDS-compliant database entity definition as a repository file, you must create the entity
as a flat file and save the file containing the DDL entity dimensions with the suffix .hdbdd, for example,
MyTable.hdbdd. The new file is located in the package hierarchy you establish in the SAP HANA repository.
The file location corresponds to the namespace specified at the start of the file, for example,
com.acme.myapp1 or sap.hana.xs.app2. You can activate the repository files at any point in time to create
the corresponding runtime object for the defined table.

Note
On activation of a repository file, the file suffix, for example, .hdbdd, is used to determine which runtime
plug-in to call during the activation process. The plug-in reads the repository file selected for activation, in
this case a CDS-compliant entity, parses the object descriptions in the file, and creates the appropriate
runtime objects.

When a CDS document is activated, the activation process generates a corresponding catalog object for each
of the artifacts defined in the document; the location in the catalog is determined by the type of object
generated. For example, the corresponding database table for a CDS entity definition is generated in the
following catalog location:

<SID> Catalog <MYSCHEMA> Tables

Entity Element Definition

You can expand the definition of an entity element beyond the element's name and type by using element
modifiers. For example, you can specify if an entity element is the primary key or part of the primary key. The
following entity element modifiers are available:

● key
Defines if the specified element is the primary key or part of the primary key for the specified entity.

Note
Structured elements can be part of the key, too. In this case, all table fields resulting from the flattening
of this structured field are part of the primary key.

● null
Defines if an entity element can (null) or cannot (not null) have the value NULL. If neither null nor
not null is specified for the element, the default value null applies (except for the key element).
● default <literal_value>
Defines the default value for an entity element in the event that no value is provided during an INSERT
operation. The syntax for the literals is defined in the primitive data-type specification.

entity MyEntity {
key MyKey : Integer;
key MyKey2 : Integer null; // illegal combination
key MyKey3 : Integer default 2;
elem2 : String(20) default 'John Doe';
elem3 : String(20) default 'John Doe' null;
elem4 : String default 'Jane Doe' not null;
};

SAP HANA Developer Guide

136 PUBLIC Setting up the Persistence Model
Spatial Data

CDS entities support the use of spatial data types such as hana.ST_POINT or hana.ST_GEOMETRY to store
geo-spatial coordinates. Spatial data is data that describes the position, shape, and orientation of objects in a
defined space; the data is represented as two-dimensional geometries in the form of points, line strings, and
polygons.

Related Information

CDS Primitive Data Types [page 158]

Entity Element Modifiers [page 137]
CDS Entity Syntax Options [page 139]

4.1.3.2 Entity Element Modifiers

Element modifiers enable you to expand the definition of an entity element beyond the element's name and
type. For example, you can specify if an entity element is the primary key or part of the primary key.

Example

entity MyEntity {
key MyKey : Integer;
elem2 : String(20) default 'John Doe';
elem3 : String(20) default 'John Doe' null;
elem4 : String default 'Jane Doe' not null;
};

key

key MyKey : Integer;

key MyKey2 : Integer null; // illegal combination
key MyKey3 : Integer default 2;

You can expand the definition of an entity element beyond the element's name and type by using element
modifiers. For example, you can specify if an entity element is the primary key or part of the primary key. The
following entity element modifiers are available:

● key
Defines if the element is the primary key or part of the primary key for the specified entity. You cannot use
the key modifier in the following cases:
○ In combination with a null modifier. The key element is non null by default because NULL cannot
be used in the key element.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 137
 Note
Structured elements can be part of the key, too. In this case, all table fields resulting from the flattening
of this structured field are part of the primary key.

null

elem3 : String(20) default 'John Doe' null;

elem4 : String default 'Jane Doe' not null;

null defines if the entity element can (null) or cannot (not null) have the value NULL. If neither null nor
not null is specified for the element, the default value null applies (except for the key element), which
means the element can have the value NULL. If you use the null modifier, note the following points:

Caution
The keywords nullable and not nullable are no longer valid; they have been replaced for SPS07 with
the keywords null and not null, respectively. The keywords null and not null must appear at the end
of the entity element definition, for example, field2 : Integer null;.

● The not null modifier can only be added if the following is true:
○ A default it also defined
○ no null data is already in the table
● Unless the table is empty, bear in mind that when adding a new not null element to an existing entity,
you must declare a default value because there might already be existing rows that do not accept NULL as
a value for the new element.
● null elements with default values are permitted
● You cannot combine the element key with the element modifier null.
● The elements used for a unique index must have the not null property.

entity WithNullAndNotNull
{
key id : Integer;
field1 : Integer;
field2 : Integer null; // same as field1, null is default
field3 : Integer not null;
};

default

default <literal_value>

For each scalar element of an entity, a default value can be specified. The default element identifier defines
the default value for the element in the event that no value is provided during an INSERT operation.

SAP HANA Developer Guide

138 PUBLIC Setting up the Persistence Model
 Note
The syntax for the literals is defined in the primitive data-type specification.

entity WithDefaults
{
key id : Integer;
field1 : Integer default -42;
field2 : Integer64 default 9223372036854775807;
field3 : Decimal(5, 3) default 12.345;
field4 : BinaryFloat default 123.456e-1;
field5 : LocalDate default date'2013-04-29';
field6 : LocalTime default time'17:04:03';
field7 : UTCDateTime default timestamp'2013-05-01 01:02:03';
field8 : UTCTimestamp default timestamp'2013-05-01 01:02:03';
field9 : Binary(32) default x'0102030405060708090a0b0c0d0e0[...]';
field10 : String(10) default 'foo';
};

Related Information

Create an Entity in CDS [page 134]

CDS Entity Syntax Options [page 139]

4.1.3.3 CDS Entity Syntax Options

The entity is the core design-time artifact for persistence model definition using the CDS syntax.

Example

Note
This example is not a working example; it is intended for illustration purposes only.

namespace Pack1."pack-age2";
@Schema: 'MySchema'
context MyContext {
entity MyEntity1
{
key id : Integer;
name : String(80);
};
@Catalog:
{ tableType : #COLUMN,
index : [
{ name:'Index1', order:#DESC, unique:true, elementNames:['x', 'y'] },
{ name:'Index2', order:#DESC, unique:false, elementNames:['x', 'a'] }
]
}
entity MyEntity2 {
key id : Integer;
x : Integer;

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 139
 y : Integer;
a : Integer;
field7 : Decimal(20,10) = power(ln(x)*sin(y), a);
};
entity MyEntity {
key id : Integer;
a : Integer;
b : Integer;
c : Integer;
s {
m : Integer;
n : Integer;
};
} technical configuration {
row store;
index MyIndex1 on (a, b) asc;
unique index MyIndex2 on (c, s) desc;
};
context MySpatialContext {
entity Address {
key id : Integer;
street_number : Integer;
street_name : String(100);
zip : String(10);
city : String(100);
loc : hana.ST_POINT(4326);
};
}
context MySeriesContext {
entity MySeriesEntity {
key setId : Integer;
t : UTCTimestamp;
value : Decimal(10,4);
series (
series key (setId)
period for series (t)
equidistant increment by interval 0.1 second
equidistant piecewise //increment or piecewise; not both
)
};
}
}

Note
For series data, you can use either equidistant or equidistant piecewise, but not both at the
same time. The example above is for illustration purposes only.

Overview

Entity definitions resemble the definition of structured types, but with the following additional features:

● Key definition [page 141]

● Index definition [page 141]
● Table type specification [page 142]
● Calculated Fields [page 143]
● Technical Configuration [page 144]

SAP HANA Developer Guide

140 PUBLIC Setting up the Persistence Model
● Spatial data * [page 146]
● Series Data * [page 147]

On activation in the SAP HANA repository, each entity definition in CDS generates a database table. The name
of the generated table is built according to the same rules as for table types, for example,
Pack1.Pack2::MyModel.MyContext.MyTable.

Note
The CDS name is restricted by the limits imposed on the length of the database identifier for the name of the
corresponding SAP HANA database artifact (for example, table, view, or type); this is currently limited to 126
characters (including delimiters).

Key Definition

type MyStruc2
{
field1 : Integer;
field2 : String(20);
};
entity MyEntity2
{
key id : Integer;
name : String(80);
key str : MyStruc2;
};

Usually an entity must have a key; you use the keyword key to mark the respective elements. The key elements
become the primary key of the generated SAP HANA table and are automatically flagged as not null. Key
elements are also used for managed associations. Structured elements can be part of the key, too. In this case,
all table fields resulting from the flattening of this structured element are part of the primary key.

Note
To define an entity without a key, use the @nokey annotation.

Index Definition

@Catalog:
{ tableType : #COLUMN,
index : [
{ name:'Index1', order:#DESC, unique:true, elementNames:['field1',
'field2'] },
{ name:'Index2', order:#ASC, unique:false, elementNames:['field1',
'field7'] }
]
}

You use the @Catalog.index or @Catalog: { index: [...]} annotation to define an index for a CDS
entity. You can define the following values for the @Catalog.index annotation:

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 141
● name : '<IndexName>'
The name of the index to be generated for the specified entity, for example, name:'myIndex'
● order
Create a table index sorted in ascending or descending order. The order keywords #ASC and #DESC can be
only used in the BTREE index (for the maintenance of sorted data) and can be specified only once for each
index.
○ order : #ASC
Creates an index for the CDS entity and sorts the index fields in ascending logical order, for example: 1,
2, 3...
○ order : #DESC
Creates a index for the CDS entity and sorts the index fields in descending logical order, for example:
3, 2, 1...
● unique
Creates a unique index for the CDS entity. In a unique index, two rows of data in a table cannot have
identical key values.
○ unique : true
Creates a unique index for the CDS entity. The uniqueness is checked and, if necessary, enforced each
time a key is added to (or changed in) the index and, in addition, each time a row is added to the table.
○ unique : false
Creates a non-unique index for the CDS entity. A non-unique index is intended primarily to improve
query performance, for example, by maintaining a sorted order of values for data that is queried
frequently.
● elementNames : ['<name1>', '<name2>' ]
The names of the fields to use in the index; the elements are specified for the entity definition, for example,
elementNames:['field1', 'field2' ]

Table-Type Definition

namespace com.acme.myapp1;
@Schema: 'MYSCHEMA'
context MyContext1 {
@Catalog.tableType : #COLUMN
entity MyEntity1 {
key ID : Integer;
name : String(30);
};
@Catalog.tableType : #ROW
entity MyEntity2 {
key ID : Integer;
name : String(30);
};
@Catalog.tableType : #GLOBAL_TEMPORARY
entity MyEntity3 {
ID : Integer;
name : String(30);
};
@Catalog.tableType : #GLOBAL_TEMPORARY_COLUMN
entity MyTempEntity {
a : Integer;
b : String(20);
};
};

SAP HANA Developer Guide

142 PUBLIC Setting up the Persistence Model
You use the @Catalog.tableType or @Catalog: { tableType: #<TYPE> } annotation to define the type
of CDS entity you want to create, for example: column- or row-based or global temporary. The
@Catalog.tableType annotation determines the storage engine in which the underlying table is created. The
following table lists and explains the permitted values for the @Catalog.tableType annotation:

Table-Type Syntax Options

Table-Type Option Description

#COLUMN @Catalog:Create a column-based table. If the majority of table access is through a

large number of tuples, with only a few selected attributes, use COLUMN-based
storage for your table type.

#ROW Create a row-based table. If the majority of table access involves selecting a few re­
cords, with all attributes selected, use ROW-based storage for your table type.

#GLOBAL_TEMPORARY Set the scope of the created table. Data in a global temporary table is session-spe­
cific; only the owner session of the global temporary table is allowed to insert/
read/truncate the data. A global temporary table exists for the duration of the ses­
sion, and data from the global temporary table is automatically dropped when the
session is terminated. Note that a temporary table cannot be changed when the ta­
ble is in use by an open session, and a global temporary table can only be dropped
if the table does not have any records.

#GLOBAL_TEMPORARY_COLUMN Set the scope of the table column. Global temporary column tables cannot have ei­
ther a key or an index.

Note
The SAP HANA database uses a combination of table types to enable storage and interpretation in both
ROW and COLUMN forms. If no table type is specified in the CDS entity definition, the default value
#COLUMN is applied to the table created on activation of the design-time entity definition.

Calculated Fields

The definition of an entity can contain calculated fields, as illustrated in type “z” the following example:

Sample Code

entity MyCalcField {
a : Integer;
b : Integer;
c : Integer = a + b;
s : String(10);
t : String(10) = upper(s);
x : Decimal(20,10);
y : Decimal(20,10);
z : Decimal(20,10) = power(ln(x)*sin(y), a);
};

The calculation expression can contain arbitrary expressions and SQL functions. The following restrictions
apply to the expression you include in a calculated field:

● The definition of a calculated field must not contain other calculated fields, associations, aggregations, or
subqueries.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 143
● A calculated field cannot be key.
● No index can be defined on a calculated field.
● A calculated field cannot be used as foreign key for a managed association.

In a query, calculated fields can be used like ordinary elements.

Note
In SAP HANA tables, you can define columns with the additional configuration “GENERATED ALWAYS AS”.
These columns are physically present in the table, and all the values are stored. Although these columns
behave for the most part like ordinary columns, their value is computed upon insertion rather than specified
in the INSERT statement. This is in contrast to calculated field, for which no values are actually stored; the
values are computed upon SELECT.

technical configuration

The definition of an entity can contain a section called technical configuration, which you use to define
the elements listed in the following table:

● Storage type
● Indexes
● Full text indexes

Note
The syntax in the technical configuration section is as close as possible to the corresponding clauses in the
SAP HANA SQL Create Table statement. Each clause in the technical configuration must end with a
semicolon.

Storage type

In the technical configuration for an entity, you can use the store keyword to specify the storage type (“row”
or “column”) for the generated table, as illustrated in the following example. If no store type is specified, a
“column” store table is generated by default.

Sample Code

entity MyEntity {
key id : Integer;
a : Integer;
b : Integer;
t : String(100);
s {
u : String(100);
};
} technical configuration {
row store;
};

SAP HANA Developer Guide

144 PUBLIC Setting up the Persistence Model
 Restriction
It is not possible to use both the @Catalog.tableType annotation and the technical configuration (for
example, row store) at the same time to define the storage type for an entity.

Indexes
In the technical configuration for an entity, you can use the index and unique index keywords to specify the
index type for the generated table. For example: “asc” (ascending) or “desc” (descending) describes the index
order, and unique specifies that the index is unique, where no two rows of data in the indexed entity can have
identical key values.

Sample Code

entity MyEntity {
key id : Integer;
a : Integer;
b : Integer;
t : String(100);
s {
u : String(100);
};
} technical configuration {
index MyIndex1 on (a, b) asc;
unique index MyIndex2 on (c, s) desc;
};

Restriction
It is not possible to use both the @Catalog.index annotation and the technical configuration (for example,
index) at the same time to define the index type for an entity.

Full text indexes

In the technical configuration for an entity, you can use the fulltext index keyword to specify the full-text
index type for the generated table, as illustrated in the following example.

Sample Code

entity MyEntity {
key id : Integer;
a : Integer;
b : Integer;
t : String(100);
s {
u : String(100);
};
} technical configuration {
row store;
index MyIndex1 on (a, b) asc;
unique index MyIndex2 on (a, b) asc;
fulltext index MYFTI1 on (t)
LANGUAGE COLUMN t
LANGUAGE DETECTION ('de', 'en')
MIME TYPE COLUMN s.u
FUZZY SEARCH INDEX off
PHRASE INDEX RATIO 0.721

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 145
 SEARCH ONLY off
FAST PREPROCESS off
TEXT ANALYSIS off;
fuzzy search index on (s.u);
};

The <fulltext_parameter_list> is identical to the standard SAP HANA SQL syntax for CREATE
FULLTEXT INDEX. A fuzzy search index in the technical configuration section of an entity definition
corresponds to the @SearchIndex annotation in XS classic and the statement "FUZZY SEARCH INDEX ON"
for a table column in SAP HANA SQL. It is not possible to specify both a full-text index and a fuzzy search index
for the same element.

Restriction
It is not possible to use both the @SearchIndex annotation and the technical configuration (for example,
fulltext index) at the same time. In addition, the full-text parameters CONFIGURATION and TEXT
MINING CONFIGURATION are not supported.

Spatial Types *

The following example shows how to use the spatial type ST_POINT in a CDS entity definition. In the example
entity Person, each person has a home address and a business address, each of which is accessible via the
corresponding associations. In the Address entity, the geo-spatial coordinates for each person are stored in
element loc using the spatial type ST_POINT (*).

Sample Code

context SpatialData {
entity Person {
key id : Integer;
name : String(100);
homeAddress : Association[1] to Address;
officeAddress : Association[1] to Address;
};
entity Address {
key id : Integer;
street_number : Integer;
street_name : String(100);
zip : String(10);
city : String(100);
loc : hana.ST_POINT(4326);
};
view CommuteDistance as select from Person {
name,
homeAddress.loc.ST_Distance(officeAddress.loc) as distance
};
};

SAP HANA Developer Guide

146 PUBLIC Setting up the Persistence Model
Series Data *

CDS enables you to create a table to store series data by defining an entity that includes a series () clause
as an table option and then defining the appropriate paremeters and options.

Note
The period for series must be unique and should not be affected by any shift in timestamps.

Sample Code

context SeriesData {
entity MySeriesEntity1 {
key setId : Integer;
t : UTCTimestamp;
value : Decimal(10,4);
series (
series key (setId)
period for series (t)
equidistant increment by interval 0.1 second
);
};
entity MySeriesEntity2 {
key setId : Integer;
t : UTCTimestamp;
value : Decimal(10,4);
series (
series key (setId)
period for series (t)
equidistant piecewise
);
};
};

CDS also supports the creation of a series table called equidistant piecewise using Formula-Encoded
Timestamps (FET). This enables support for data that is not loaded in an order that ensures good
compression. There is no a-priori restriction on the timestamps that are stored, but the data is expected to be
well approximated as piecewise linear with some jitter. The timestamps do not have a single slope/offset
throughout the table; rather, they can change within and among series in the table.

Restriction
The equidistant piecewise specification can only be used in CDS; it cannot be used to create a table
with the SQL command CREATE TABLE.

When a series table is defined as equidistant piecewise, the following restrictions apply:

1. The period includes one column (instant); there is no support for interval periods.
2. There is no support for missing elements. These could logically be defined if the period includes an
interval start and end. Missing elements then occur when we have adjacent rows where the end of the
interval does not equal the start of the interval.
3. The type of the period column must map to the one of the following types: DATE, SECONDDATE, or
TIMESTAMP.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 147
 Caution
(*) SAP HANA server software and tools can be used for several SAP HANA platform and options scenarios
as well as the respective capabilities used in these scenarios. The availability of these is based on the
available SAP HANA licenses and the SAP HANA landscape, including the type and version of the back-end
systems the SAP HANA administration and development tools are connected to. There are several types of
licenses available for SAP HANA. Depending on your SAP HANA installation license type, some of the
features and tools described in the SAP HANA platform documentation may only be available in the SAP
HANA options and capabilities, which may be released independently of an SAP HANA Platform Support
Package Stack (SPS). Although various features included in SAP HANA options and capabilities are cited in
the SAP HANA platform documentation, each SAP HANA edition governs the options and capabilities
available. Based on this, customers do not necessarily have the right to use features included in SAP HANA
options and capabilities. For customers to whom these license restrictions apply, the use of features
included in SAP HANA options and capabilities in a production system requires purchasing the
corresponding software license(s) from SAP. The documentation for the SAP HANA options is available in
SAP Help Portal. If you have additional questions about what your particular license provides, or wish to
discuss licensing features available in SAP HANA options, please contact your SAP account team
representative.

Related Information

Create an Entity in CDS [page 134]

CDS Annotations [page 123]
CDS Primitive Data Types [page 158]

4.1.4 Create a User-Defined Structured Type in CDS

A structured type is a data type comprising a list of attributes, each of which has its own data type. You create a
user-defined structured type as a design-time file in the SAP HANA repository.

Prerequisites

● You have created a schema for the CDS catalog objects, for example, MYSCHEMA.
● You have SELECT privileges on the schema so you can see the generated catalog objects.

Context

SAP HANA Extended Application Services (SAP HANA XS) enables you to use the CDS syntax to create a user-
defined structured type as a design-time file in the repository. Repository files are transportable. Activating the
CDS entity creates the corresponding table in the specified schema.

SAP HANA Developer Guide

148 PUBLIC Setting up the Persistence Model
Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the CDS definition file for the user-defined structured type.
a. In the package structure, select the package where you want to create the CDS definition file for the
new user-defined structured type and from the context menu choose New File .
b. Enter the name of the entity in the File Name field, for example, MyStructuredType.hdbdd, and
choose Create.
3. Define the user-defined structured type in CDS.
Add the definition code for the user-defined structured type to the file, as shown in the example below:

namespace Package1.Package2;
@Schema: 'MYSCHEMA'
type MyStructuredType
{
aNumber : Integer;
someText : String(80);
otherText : String(80);
};

Note
If the schema you specify does not exist, you cannot activate the new CDS entity.

4. Save the definition file for the CDS user-defined structured type.
5. Check that the new structured type has been successfully created.
CDS user-defined structured types are created in the Table Types folder in the catalog.
a. Open the catalog.
b. Navigate to the catalog location where you created the new structured type:
Catalog <MYSCHEMA> Procedures Table Types
c. Select the new structured type MyStructuredType to display its definition.

Related Information

CDS User-Defined Data Types [page 150]

CDS Structured Type Definition [page 153]
CDS Structured Types [page 156]
CDS Primitive Data Types [page 158]

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 149
4.1.4.1 CDS User-Defined Data Types

User-defined data types reference existing structured types (for example, user-defined) or the individual types
(for example, field, type, or context) used in another data-type definition.

You can use the type keyword to define a new data type in CDS-compliant DDL syntax. You can define the data
type in the following ways:

● Using allowed structured types (for example, user-defined)

● Referencing another data type

In the following example, the element definition field2 : MyType1; specifies a new element field2 that is
based on the specification in the user-defined data type MyType1.

Note
If you are using a CDS document to define a single CDS-compliant user-defined data type, the name of the
CDS document must match the name of the top-level data type defined in the CDS document, for example,
with the type keyword.

In the following example, you must save the data-type definition “MyType1” in the CDS document
MyType1.hdbdd. In addition, the name space declared in a CDS document must match the repository
package in which the object the document defines is located.

namespace com.acme.myapp1;
@Schema: 'MYSCHEMA' // user-defined structured data types
type MyType1 {
field1 : Integer;
field2 : String(40);
field3 : Decimal(22,11);
field4 : Binary(11);
};

In the following example, you must save the data-type definition “MyType2” in the CDS document
MyType2.hdbdd; the document contains a using directive pointing to the data-type “MyType1” defined in CDS
document MyType1.hdbdd.

namespace com.acme.myapp1;
using com.acme.myapp1::MyType1;
@Schema: 'MYSCHEMA' // user-defined structured data types
type MyType2 {
field1 : String(50);
field2 : MyType1;
};

In the following example, you must save the data-type definition “MyType3” in the CDS document
MyType3.hdbdd; the document contains a using directive pointing to the data-type “MyType2” defined in CDS
document MyType2.hdbdd.

namespace com.acme.myapp1;
using com.acme.myapp1::MyType2;
@Schema: 'MYSCHEMA' // user-defined structured data types
type MyType3 {
field1 : UTCTimestamp;
field2 : MyType2;
};

SAP HANA Developer Guide

150 PUBLIC Setting up the Persistence Model
The following code example shows how to use the type of keyword to define an element using the definition
specified in another user-defined data-type field. For example, field4 : type of field3; indicates that,
like field3, field4 is a LocalDate data type.

namespace com.acme.myapp1;
using com.acme.myapp1::MyType1;
@Schema: 'MYSCHEMA' // Simple user-defined data types
entity MyEntity1 {
key id : Integer;
field1 : MyType3;
field2 : String(24);
field3 : LocalDate;
field4 : type of field3;
field5 : type of MyType1.field2;
field6 : type of InnerCtx.CtxType.b; // context reference
};

You can use the type of keyword in the following ways:

● Define a new element (field4) using the definition specified in another user-defined element field3:
field4 : type of field3;
● Define a new element field5 using the definition specified in a field (field2) that belongs to another
user-defined data type (MyType1):
field5 : type of MyType1.field2;
● Define a new element (field6) using an existing field (b) that belongs to a data type (CtxType) in another
context (InnerCtx):
field6 : type of InnerCtx.CtxType.b;

The following code example shows you how to define nested contexts (MyContext.InnerCtx) and refer to
data types defined by a user in the specified context.

namespace com.acme.myapp1;
@Schema: 'MYSCHEMA'
context MyContext {
// Nested contexts
context InnerCtx {

Entity MyEntity {
…
};
Type CtxType {
a : Integer;
b : String(59);
};
};
type MyType1 {
field1 : Integer;
field2 : String(40);
field3 : Decimal(22,11);
field4 : Binary(11);
};
type MyType2 {
field1 : String(50);
field2 : MyType1;
};
type MyType3 {
field1 : UTCTimestamp;
field2 : MyType2;
};

@Catalog.index : [{ name : 'IndexA', order : #ASC, unique: true,

elementNames : ['field1'] }]

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 151
 entity MyEntity1 {
key id : Integer;
field1 : MyType3 not null;
field2 : String(24);
field3 : LocalDate;
field4 : type of field3;
field5 : type of MyType1.field2;
field6 : type of InnerCtx.CtxType.b; // refers to nested context
field7 : InnerCtx.CtxType; // more context references
};
};

Restrictions

CDS name resolution does not distinguish between CDS elements and CDS types. If you define a CDS
element based on a CDS data type that has the same name as the new CDS element, CDS displays an error
message and the activation of the CDS document fails.

Caution
In an CDS document, you cannot define a CDS element using a CDS type of the same name; you must
specify the context where the target type is defined, for example, MyContext.doobidoo.

The following example defines an association between a CDS element and a CDS data type both of which are
named doobidoo. The result is an error when resolving the names in the CDS document; CDS expects a type
named doobidoo but finds an CDS entity element with the same name that is not a type.

context MyContext2 {
type doobidoo : Integer;
entity MyEntity {
key id : Integer;
doobidoo : doobidoo; // error: type expected; doobidoo is not a type
};
};

The following example works, since the explicit reference to the context where the type definition is located
(MyContext.doobidoo) enables CDS to resolve the definition target.

context MyContext {
type doobidoo : Integer;
entity MyEntity {
key id : Integer;
doobidoo : MyContext.doobidoo; // OK
};
};

Note
To prevent name clashes between artifacts that are types and those that have a type assigned to them,
make sure you keep to strict naming conventions. For example, use an uppercase first letter for MyEntity,
MyView and MyType; use a lowercase first letter for elements myElement.

SAP HANA Developer Guide

152 PUBLIC Setting up the Persistence Model
Related Information

Create a User-Defined Structured Type in CDS [page 148]

CDS Structured Type Definition [page 153]
CDS Primitive Data Types [page 158]

4.1.4.2 CDS Structured Type Definition

A structured type is a data type comprising a list of attributes, each of which has its own data type. The
attributes of the structured type can be defined manually in the structured type itself and reused either by
another structured type or an entity.

SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database structured type as
a design-time file in the repository. All repository files including your structured-type definition can be
transported to other SAP HANA systems, for example, in a delivery unit. You can define the structured type
using CDS-compliant DDL.

Note
A delivery unit is the medium SAP HANA provides to enable you to assemble all your application-related
repository artifacts together into an archive that can be easily exported to other systems.

When a CDS document is activated, the activation process generates a corresponding catalog object for each
of the artifacts defined in the document; the location in the catalog is determined by the type of object
generated. For example, the corresponding table type for a CDS type definition is generated in the following
catalog location:

<SID> Catalog <MYSCHEMA> Procedures Table Types

Structured User-Defined Types

In a structured user-defined type, you can define original types (aNumber in the following example) or
reference existing types defined elsewhere in the same type definition or another, separate type definition
(MyString80). If you define multiple types in a single CDS document, for example, in a parent context, each
structure-type definition must be separated by a semi-colon (;).

The type MyString80 is defined in the following CDS document:

namespace Package1.Package2;
@Schema: 'MySchema'
type MyString80: String(80);

A using directive is required to resolve the reference to the data type specified in otherText :
MyString80;, as illustrated in the following example:

namespace Package1.Package2;
using Package1.Package2::MyString80; //contains definition of MyString80

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 153
 @Schema: 'MySchema'
type MyStruct
{
aNumber : Integer;
someText : String(80);
otherText : MyString80; // defined in a separate type
};

Note
If you are using a CDS document to specify a single CDS-compliant data type, the name of the CDS
document (MyStruct.hdbdd) must match the name of the top-level data type defined in the CDS
document, for example, with the type keyword.

Nested Structured Types

Since user-defined types can make use of other user-defined types, you can build nested structured types, as
illustrated in the following example:

namespace Package1.Package2;
using Package1.Package2::MyString80;
using Package1.Package2::MyStruct;
@Schema: 'MYSCHEMA'
context NestedStructs {
type MyNestedStruct
{
name : MyString80;
nested : MyStruct; // defined in a separate type
};
type MyDeepNestedStruct
{
text : LargeString;
nested : MyNestedStruct;
};
type MyOtherInt : type of MyStruct.aNumber; // => Integer
type MyOtherStruct : type of MyDeepNestedStruct.nested.nested; // => MyStruct
};

You can also define a type based on an existing type that is already defined in another user-defined structured
type, for example, by using the type of keyword, as illustrated in the following example:

type MyOtherInt : type of MyStruct.aNumber; // => Integer

type MyOtherStruct : type of MyDeepNestedStruct.nested.nested; // => MyStruct

Generated Table Types

For each structured type, a SAP HANA table type is generated, whose name is built by concatenating the
following elements of the CDS document containing the structured-type definition and separating the
elements by a dot delimiter (.):

● the name space (for example, Pack1.Pack2)

SAP HANA Developer Guide

154 PUBLIC Setting up the Persistence Model
● the names of all artifacts that enclose the type (for example, MyModel)
● the name of the type itself (for example, MyNestedStruct)

create type "Pack1.Pack2::MyModel.MyNestedStruct" as table (

name nvarchar(80),
nested.aNumber integer,
nested.someText nvarchar(80),
nested.otherText nvarchar(80)
);

The new SAP HANA table types are generated in the schema that is specified in the schema annotation of the
respective top-level artifact in the CDS document containing the structured types.

Note
To view the newly created objects, you must have the required SELECT privilege for the schema object in
which the objects are generated.

The columns of the table type are built by flattening the elements of the type. Elements with structured types
are mapped to one column per nested element, with the column names built by concatenating the element
names and separating the names by dots ".".

Tip
If you want to use the structured types inside a CDS document without generating table types in the catalog,
use the annotation @GenerateTableType : false.

Table types are only generated for direct structure definitions; in the following example, this would include:
MyStruct, MyNestedStruct, and MyDeepNestedStruct. No table types are generated for derived types
that are based on structured types; in the following example, the derived types include: MyS, MyOtherInt,
MyOtherStruct.

Example

namespace Pack1."pack-age2";
@Schema: 'MySchema'
context MyModel
{
type MyInteger : Integer;
type MyString80 : String(80);
type MyDecimal : Decimal(10,2);
type MyStruct
{
aNumber : Integer;
someText : String(80);
otherText : MyString80; // defined in example above
};
type MyS : MyStruct;
type MyOtherInt : type of MyStruct.aNumber;
type MyOtherStruct : type of MyDeepNestedStruct.nested.nested;
type MyNestedStruct
{
name : MyString80;
nested : MyS;
};
type MyDeepNestedStruct
{
text : LargeString;
nested : MyNestedStruct;

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 155
 };
};

Related Information

Create a User-Defined Structured Type in CDS [page 148]

CDS User-Defined Data Types [page 150]
CDS Structured Types [page 156]
CDS Primitive Data Types [page 158]

4.1.4.3 CDS Structured Types

A structured type is a data type comprising a list of attributes, each of which has its own data type. The
attributes of the structured type can be defined manually in the structured type itself and reused either by
another structured type or an entity.

Example

namespace examples;
@Schema: 'MYSCHEMA'
context StructuredTypes {
type MyOtherInt : type of MyStruct.aNumber; // => Integer
type MyOtherStruct : type of MyDeepNestedStruct.nested.nested; // =>
MyStruct
@GenerateTableType: false
type EmptyStruct { };
type MyStruct
{
aNumber : Integer;
aText : String(80);
anotherText : MyString80; // defined in a separate type
};
entity E {
a : Integer;
s : EmptyStruct;
};
type MyString80 : String(80);
type MyS : MyStruct;
type MyNestedStruct
{
name : MyString80;
nested : MyS;
};
type MyDeepNestedStruct
{
text : LargeString;
nested : MyNestedStruct;
};
};

SAP HANA Developer Guide

156 PUBLIC Setting up the Persistence Model
type

In a structured user-defined type, you can define original types (aNumber in the following example) or
reference existing types defined elsewhere in the same type definition or another, separate type definition, for
example, MyString80 in the following code snippet. If you define multiple types in a single CDS document,
each structure definition must be separated by a semi-colon (;).

type MyStruct
{
aNumber : Integer;
aText : String(80);
anotherText : MyString80; // defined in a separate type
};

You can define structured types that do not contain any elements, for example, using the keywords type
EmptyStruct { };. In the example, below the generated table for entity “E” contains only one column: “a”.

Tip
It is not possible to generate an SAP HANA table type for an empty structured type. This means you must
disable the generation of the table type in the Repository, for example, with the @GenerateTableType
annotation.

@GenerateTableType : false
type EmptyStruct { };
entity E {
a : Integer;
s : EmptyStruct;
};

type of

You can define a type based on an existing type that is already defined in another user-defined structured type,
for example, by using the type of keyword, as illustrated in the following example:

Context StructuredTypes
{
type MyOtherInt : type of MyStruct.aNumber; // => Integer
type MyOtherStruct : type of MyDeepNestedStruct.nested.nested; // => MyStruct
};

Related Information

Create a User-Defined Structured Type in CDS [page 148]

CDS Primitive Data Types [page 158]
CDS User-Defined Data Types [page 150]
CDS Structured Type Definition [page 153]

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 157
4.1.4.4 CDS Primitive Data Types

In the Data Definition Language (DDL), primitive (or core) data types are the basic building blocks that you use
to define entities or structure types with DDL.

When you are specifying a design-time table (entity) or a view definition using the CDS syntax, you use data
types such as String, Binary, or Integer to specify the type of content in the entity columns. CDS supports the
use of the following primitive data types:

● DDL data types [page 158]

● Native SAP HANA data types [page 160]

The following table lists all currently supported simple DDL primitive data types. Additional information
provided in this table includes the SQL syntax required as well as the equivalent SQL and EDM names for the
listed types.

Supported SAP HANA DDL Primitive Types

Name Description SQL Literal Syntax SQL Name EDM Name

String (n) Variable-length Unicode string with a 'text with “quote”' NVARCHAR String
specified maximum length of
n=1-1333 characters (5000 for SAP
HANA specific objects). Default =
maximum length. String length (n) is
mandatory.

LargeString Variable length string of up to 2 GB 'text with “quote”' NCLOB String

(no comparison)

Binary(n) Variable length byte string with user- x'01Cafe', X'01Cafe' VARBINARY Binary
defined length limit of up to 4000
bytes. Binary length (n) is mandatory.

LargeBinary Variable length byte string of up to 2 x'01Cafe', X'01Cafe' BLOB Binary

GB (no comparison)

Integer Respective container's standard 13, -1234567 INTEGER Int64

signed integer. Signed 32 bit integers
in 2's complement, -2**31 .. 2**31-1.
Default=NULL

Integer64 Signed 64-bit integer with a value 13, -1234567 BIGINT Int64
range of -2^63 to 2^63-1. De­
fault=NULL.

Decimal( p, s ) Decimal number with fixed precision 12.345, -9.876 DECIMAL( p, s ) Decimal
(p) in range of 1 to 34 and fixed scale
(s) in range of 0 to p. Values for preci­
sion and scale are mandatory.

DecimalFloat Decimal floating-point number (IEEE 12.345, -9.876 DECIMAL Decimal

754-2008) with 34 mantissa digits;
range is roughly ±1e-6143 through
±9.99e+6144

BinaryFloat Binary floating-point number (IEEE 1.2, -3.4, 5.6e+7 DOUBLE Double
754), 8 bytes (roughly 16 decimal dig­
its precision); range is roughly
±2.2207e-308 through ±1.7977e+308

SAP HANA Developer Guide

158 PUBLIC Setting up the Persistence Model
 Name Description SQL Literal Syntax SQL Name EDM Name

LocalDate Local date with values ranging from date'1234-12-31' DATE DateTimeOffset
0001-01-01 through 9999-12-31
Combines date
and time; with
time zone must
be converted to
offset

LocalTime Time values (with seconds precision) time'23:59:59', time'12:15' TIME Time
and values ranging from 00:00:00
For duration/
through 24:00:00
period of time
(==xsd:dura­
tion). Use Date­
TimeOffset if
there is a date,
too.

UTCDateTime UTC date and time (with seconds pre­ timestamp'2011-12-31 SECONDDATE DateTimeOffset
cision) and values ranging from 23:59:59'
Values ending
0001-01-01 00:00:00 through
9999-12-31 23:59:59 with “Z” for
UTC. Values be­
fore
1753-01-01T00:
00:00 are not
supported;
transmitted as
NULL.

UTCTimestamp UTC date and time (with a precision timestamp'2011-12-31 TIMESTAMP DateTimeOffset
of 0.1 microseconds) and values rang­ 23:59:59.7654321'
With Precision
ing from 0001-01-01 00:00:00
through 9999-12-31 = “7”
23:59:59.9999999, and a special ini­
tial value

Boolean Represents the concept of binary-val­ true, false, unknown (null) BOOLEAN Boolean
ued logic

The following table lists all the native SAP HANA primitive data types that CDS supports. The information
provided in this table also includes the SQL syntax required (where appropriate) as well as the equivalent SQL
and EDM names for the listed types.

Note
* In CDS, the name of SAP HANA data types are prefixed with the word “hana”, for example,
hana.ALPHANUM, or hana.SMALLINT, or hana.TINYINT.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 159
Supported Native SAP HANA Data Types
Data Type * Description SQL Literal Syntax SQL Name EDM Name

ALPHANUM Variable-length char­ - ALPHANUMERIC -

acter string with spe­
cial comparison

SMALLINT Signed 16-bit integer -32768, 32767 SMALLINT Int16

TINYINT Unsigned 8-bit integer 0, 255 TINYINT Byte

REAL 32-bit binary floating- - REAL Single

point number

SMALLDECIMAL 64-bit decimal float- - SMALLDECIMAL Decimal

ing-point number

VARCHAR Variable-length ASCII - VARCHAR String

character string with
user-definable length
limit n

CLOB Large variable-length - CLOB String

ASCII character string,
no comparison

BINARY Byte string of fixed - BINARY Blob

length n

ST_POINT 0-dimensional geome­ - - -

try representing a sin­
gle location

ST_GEOMETRY Maximal supertype of - - -

the geometry type hi­
erarchy; includes
ST_POINT

The following example shows the native SAP HANA data types that CDS supports; the code example also
illustrates the mandatory syntax.

Note
Support for the geo-spatial types ST_POINT and ST_GEOMETRY is limited: these types can only be used for
the definition of elements in types and entities. It is not possible to define a CDS view that selects an
element based on a geo-spatial type from a CDS entity.

@nokey
entity SomeTypes {
a : hana.ALPHANUM(10);
b : hana.SMALLINT;
c : hana.TINYINT;
d : hana.SMALLDECIMAL;
e : hana.REAL;
h : hana.VARCHAR(10);
i : hana.CLOB;
j : hana.BINARY(10);
k : hana.ST_POINT;
l : hana.ST_GEOMETRY;
};

SAP HANA Developer Guide

160 PUBLIC Setting up the Persistence Model
4.1.5 Create an Association in CDS

Associations define relationships between entities. You create associations in a CDS entity definition, which is a
design-time file in the SAP HANA repository.

Prerequisites

● You have created a schema for the CDS catalog objects, for example, MYSCHEMA.
● You have SELECT privileges on the schema so you can see the generated catalog objects.

Context

SAP HANA Extended Application Services (SAP HANA XS) enables you to use the CDS syntax to create
associations between entities. The associations are defined as part of the entity definition, which are design-
time files in the repository. Repository files are transportable. Activating the CDS entity creates the
corresponding catalog objects in the specified schema.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the CDS entity-definition file which will contain the associations you define.
a. In the package structure, select the package where you want to create the CDS definition file for the
new CDS entity-definition file and from the context menu choose New File .
b. Enter the name of the entity-definition file in the File Name field, for example, MyEntity1.hdbdd, and
choose Create.
3. Define the underlying CDS entities and structured types.
Add the code for the entity definitions and structured types to the file, as shown in the example below:

namespace com.acme.myapp1;
@Schema : 'MYSCHEMA'
context MyEntity1 {
type StreetAddress {
name : String(80);
number : Integer;
};
type CountryAddress {
name : String(80);
code : String(3);
};
entity Address {
key id : Integer;
street : StreetAddress;

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 161
 zipCode : Integer;
city : String(80);
country : CountryAddress;
type : String(10); // home, office
};
};

Note
If the schema you specify does not exist, you cannot activate the new CDS entity.

4. Define a one-to-one association between CDS entities.

In the same entity-definition file you edited in the previous step, for example, add the code for the one-to-
one association between the entity Person and the entity Address. Note that this example does not
specify cardinality or foreign keys, so the cardinality is set to the default 0..1, and the target entity's primary
key (the element id) is used as the foreign key:

entity Person
{
key id : Integer;
address1 : Association to Address;
};

5. Define an association with cardinality one-to-many between CDS entities.

Add the code for the one-to-many association between the entity Person and the entity Address to the
code you added in the previous step. Note that this example uses only zipCode as the foreign key. Since
zipCode is not a unique key for the entity Address, this association has cardinality "one-to-many":

entity Person
{
key id : Integer;
address1 : Association to Address;
address4 : Association[0..*] to Address { zipCode };
}

6. Save the CDS entity-definition file containing the new associations.

Related Information

CDS Associations [page 162]

CDS Association Syntax Options [page 168]

4.1.5.1 CDS Associations

Associations define relationships between entities.

Associations are specified by adding an element to a source entity with an association type that points to a
target entity, complemented by optional information defining cardinality and which keys to use.

SAP HANA Developer Guide

162 PUBLIC Setting up the Persistence Model
 Note
CDS supports both managed and unmanaged associations.

SAP HANA Extended Application Services (SAP HANA XS) enables you to use associations in CDS entities or
CDS views. The syntax for simple associations in a CDS document is illustrated in the following example:

namespace samples;
@Schema: 'MYSCHEMA' // XS classic *only*
context SimpleAssociations {
type StreetAddress {
name : String(80);
number : Integer;
};
type CountryAddress {
name : String(80);
code : String(3);
};
entity Address {
key id : Integer;
street : StreetAddress;
zipCode : Integer;
city : String(80);
country : CountryAddress;
type : String(10); // home, office
};
entity Person
{
key id : Integer;
// address1,2,3 are to-one associations
address1 : Association to Address;
address2 : Association to Address { id };
address3 : Association[1] to Address { zipCode, street, country };
// address4,5,6 are to-many associations
address4 : Association[0..*] to Address { zipCode };
address5 : Association[*] to Address { street.name };
address6 : Association[*] to Address { street.name AS streetName,
country.name AS countryName };
};
};

Cardinality in Associations

When using an association to define a relationship between entities in a CDS document, you use the
cardinality to specify the type of relation, for example, one-to-one (to-one) or one-to-many (to-n); the
relationship is with respect to both the source and the target of the association.

The target cardinality is stated in the form of [ min .. max ], where max=* denotes infinity. If no cardinality
is specified, the default cardinality setting [ 0..1 ] is assumed. It is possible to specify the maximum
cardinality of the source of the association in the form [ maxs, min .. max], too, where maxs = * denotes
infinity.

Tip
The information concerning the maximum cardinality is only used as a hint for optimizing the execution of
the resulting JOIN.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 163
The following examples illustrate how to express cardinality in an association definition:

namespace samples;
@Schema: 'MYSCHEMA' // XS classic *only*
context AssociationCardinality {
entity Associations {
// To-one associations
assoc1 : Association[0..1] to target; // has no or one target instance
assoc2 : Association to target; // as assoc1, uses the default
[0..1]
assoc3 : Association[1] to target; // as assoc1; the default for
min is 0
assoc4 : Association[1..1] to target; // association has one target
instance
// To-many associations
assoc5 : Association[0..*] to target{id1};
assoc6 : Association[] to target{id1}; // as assoc4, [] is short
for [0..*]
assoc7 : Association[2..7] to target{id1}; // any numbers are
possible; user provides
assoc8 : Association[1, 0..*] to target{id1}; // additional info. about
source cardinality
};
// Required to make the example above work
entity target {
key id1 : Integer;
key id2 : Integer;
};
};

Target Entities in Associations

You use the to keyword in a CDS view definition to specify the target entity in an association, for example, the
name of an entity defined in a CDS document. A qualified entity name is expected that refers to an existing
entity. A target entity specification is mandatory; a default value is not assumed if no target entity is specified
in an association relationship.

The entity Address specified as the target entity of an association could be expressed in any of the ways
illustrated the following examples:

address1 : Association to Address;

address2 : Association to Address { id };
address3 : Association[1] to Address { zipCode, street, country };

Filter Conditions and Prefix Notation

When following an association (for example, in a view), it is now possible to apply a filter condition; the filter is
merged into the ON-condition of the resulting JOIN. The following example shows how to get a list of customers
and then filter the list according to the sales orders that are currently “open” for each customer. In the
example, the infix filter is inserted after the association orders to get only those orders that satisfy the
condition [status='open'].

SAP HANA Developer Guide

164 PUBLIC Setting up the Persistence Model
 Sample Code

view C1 as select from Customer {

name,
orders[status='open'].id as orderId
};

The association orders is defined in the entity definition illustrated in the following code example:

Sample Code

entity Customer {
key id : Integer;
orders : Association[*] to SalesOrder on orders.cust_id = id;
name : String(80);
};
entity SalesOrder {
key id : Integer;
cust_id : Integer;
customer: Association[1] to Customer on customer.id = cust_id;
items : Association[*] to Item on items.order_id = id;
status: String(20);
date : LocalDate;
};
entity Item {
key id : Integer;
order_id : Integer;
salesOrder : Association[1] to SalesOrder on salesOrder.id = order_id;
descr : String(100);
price : Decimal(8,2);
};

Tip
For more information about filter conditions and prefixes in CDS views, see CDS Views and CDS View Syntax
Options.

Foreign Keys in Associations

For managed associations, the relationship between source and target entity is defined by specifying a set of
elements of the target entity that are used as a foreign key. If no foreign keys are specified explicitly, the
elements of the target entity’s designated primary key are used. Elements of the target entity that reside inside
substructures can be addressed via the respective path. If the chosen elements do not form a unique key of the
target entity, the association has cardinality to-many. The following examples show how to express foreign keys
in an association.

namespace samples;
using samples::SimpleAssociations.StreetAddress;
using samples::SimpleAssociations.CountryAddress;
using samples::SimpleAssociations.Address;
@Schema: 'MYSCHEMA' // XS classic *only*
context ForeignKeys {
entity Person
{

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 165
 key id : Integer;
// address1,2,3 are to-one associations
address1 : Association to Address;
address2 : Association to Address { id };
address3 : Association[1] to Address { zipCode, street, country };
// address4,5,6 are to-many associations
address4 : Association[0..*] to Address { zipCode };
address5 : Association[*] to Address { street.name };
address6 : Association[*] to Address { street.name AS streetName,
country.name AS countryName };
};
entity Header {
key id : Integer;
toItems : Association[*] to Item on toItems.head.id = id;
};
entity Item {
key id : Integer;
head : Association[1] to Header { id };
// <...>
};
};

● address1
No foreign keys are specified: the target entity's primary key (the element id) is used as foreign key.
● address2
Explicitly specifies the foreign key (the element id); this definition is similar to address1.
● address3
The foreign key elements to be used for the association are explicitly specified, namely: zipcode and the
structured elements street and country.
● address4
Uses only zipcode as the foreign key. Since zipcode is not a unique key for entity Address, this
association has cardinality “to-many”.
● address5
Uses the subelement name of the structured element street as a foreign key. This is not a unique key and,
as a result, address4 has cardinality “to-many”.
● address6
Uses the subelement name of both the structured elements street and country as foreign key fields.
The names of the foreign key fields must be unique, so an alias is required here. The foreign key is not
unique, so address6 is a “to-many” association.

You can use foreign keys of managed associations in the definition of other associations. In the following
example, the appearance of association head in the ON condition is allowed; the compiler recognizes that the
field head.id is actually part of the entity Item and, as a result, can be obtained without following the
association head.

Sample Code

entity Header {
key id : Integer;
toItems : Association[*] to Item on toItems.head.id = id;
};

entity Item {
key id : Integer;
head : Association[1] to Header { id };
...

SAP HANA Developer Guide

166 PUBLIC Setting up the Persistence Model
 };

Restrictions

CDS name resolution does not distinguish between CDS associations and CDS entities. If you define a
CDS association with a CDS entity that has the same name as the new CDS association, CDS displays an error
message and the activation of the CDS document fails.

Caution
In an CDS document, to define an association with a CDS entity of the same name, you must specify the
context where the target entity is defined, for example, Mycontext.Address3.

The following code shows some examples of associations with a CDS entity that has the same (or a similar)
name. Case sensitivity ("a", "A") is important; in CDS documents, address is not the same as Address. In the
case of Address2, where the association name and the entity name are identical, the result is an error; when
resolving the element names, CDS expects an entity named Address2 but finds a CDS association with the
same name instead. MyContext.Address3 is allowed, since the target entity can be resolved due to the
absolute path to its location in the CDS document.

context MyContext {
entity Address {…}
entity Address1 {…}
entity Address2 {…}
entity Address3 {…}
entity Person
{
key id : Integer;
address : Association to Address; // OK: "address" ≠ "Address”
address1 : Association to Address1; // OK: "address1" ≠ "Address1”
Address2 : Association to Address2; // Error: association name =
entity name
Address3 : Association to MyContext.Address3; //OK: full path to Address3

};
};

Example
Complex (One-to-Many) Association

The following example shows a more complex association (to-many) between the entity “Header” and the
entity “Item”.

namespace samples;
@Schema: 'MYSCHEMA' // XS classic *only*
context ComplexAssociation {
Entity Header {
key PurchaseOrderId: BusinessKey;
Items: Association [0..*] to Item on
Items.PurchaseOrderId=PurchaseOrderId;
"History": HistoryT;
NoteId: BusinessKey null;
PartnerId: BusinessKey;
Currency: CurrencyT;

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 167
 GrossAmount: AmountT;
NetAmount: AmountT;
TaxAmount: AmountT;
LifecycleStatus: StatusT;
ApprovalStatus: StatusT;
ConfirmStatus: StatusT;
OrderingStatus: StatusT;
InvoicingStatus: StatusT;
} technical configuration {
column store;
};
Entity Item {
key PurchaseOrderId: BusinessKey;
key PurchaseOrderItem: BusinessKey;
ToHeader: Association [1] to Header on
ToHeader.PurchaseOrderId=PurchaseOrderId;
ProductId: BusinessKey;
NoteId: BusinessKey null;
Currency: CurrencyT;
GrossAmount: AmountT;
NetAmount: AmountT;
TaxAmount: AmountT;
Quantity: QuantityT;
QuantityUnit: UnitT;
DeliveryDate: SDate;
} technical configuration {
column store;
};
define view POView as SELECT from Header {
Items.PurchaseOrderId as poId,
Items.PurchaseOrderItem as poItem,
PartnerId,
Items.ProductId
};
// Missing types from the example above
type BusinessKey: String(50);
type HistoryT: LargeString;
type CurrencyT: String(3);
type AmountT: Decimal(15, 2);
type StatusT: String(1);
type QuantityT: Integer;
type UnitT: String(5);
type SDate: LocalDate;
};

4.1.5.2 CDS Association Syntax Options

Associations define relationships between entities.

Example
Managed Associations

Association [ <cardinality> ] to <targetEntity> [ <forwardLink> ]

SAP HANA Developer Guide

168 PUBLIC Setting up the Persistence Model
 Example
Unmanaged Associations

Association [ <cardinality> ] to <targetEntity> <unmanagedJoin>

Overview

Associations are specified by adding an element to a source entity with an association type that points to a
target entity, complemented by optional information defining cardinality and which keys to use.

Note
CDS supports both managed and unmanaged associations.

SAP HANA Extended Application Services (SAP HANA XS) enables you to use associations in the definition of a
CDS entity or a CDS view. When defining an association, bear in mind the following points:

● <Cardinality> [page 169]

The relationship between the source and target in the association, for example, one-to-one, one-to-many,
many-to-one
● <targetEntity> [page 171]
The target entity for the association
● <forwardLink> [page 171]
The foreign keys to use in a managed association, for example, element names in the target entity
● <unmanagedJoin> [page 173]
Unmanaged associations only; the ON condition specifies the elements of the source and target elements
and entities to use in the association

Association Cardinality

When using an association to define a relationship between entities in a CDS view; you use the cardinality to
specify the type of relation, for example:

● one-to-one (to-one)
● one-to-many (to-n)

The relationship is with respect to both the source and the target of the association. The following code
example illustrates the syntax required to define the cardinality of an association in a CDS view:

[ [ ( maxs | * ) , ] // source cardinality

[ min .. ] ( max | * ) // target cardinality
]

In the most simple form, only the target cardinality is stated using the syntax [ min .. max ], where max=*
denotes infinity. Note that [] is short for [ 0..* ]. If no cardinality is specified, the default cardinality setting

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 169
[ 0..1 ] is assumed. It is possible to specify the maximum cardinality of the source of the association in the
form [ maxs, min .. max], where maxs = * denotes infinity.

The following examples illustrate how to express cardinality in an association definition:

namespace samples;
@Schema: 'MYSCHEMA' // XS classic *only*
context AssociationCardinality {
entity Associations {
// To-one associations
assoc1 : Association[0..1] to target;
assoc2 : Association to target;
assoc3 : Association[1] to target;
assoc4 : Association[1..1] to target; // association has one target
instance
// To-many associations
assoc5 : Association[0..*] to target{id1};
assoc6 : Association[] to target{id1}; // as assoc4, [] is short
for [0..*]
assoc7 : Association[2..7] to target{id1}; // any numbers are
possible; user provides
assoc8 : Association[1, 0..*] to target{id1}; // additional info. about
source cardinality
};
// Required to make the example above work
entity target {
key id1 : Integer;
key id2 : Integer;
};
};

The following table describes the various cardinality expressions illustrated in the example above:

Association Cardinality Syntax Examples

Association Cardinality Explanation

assoc1 [0..1] The association has no or one target instance

assoc2 Like assoc1, this association has no or one target instance and uses the de­
fault [0..1]

assoc3 [1] Like assoc1, this association has no or one target instance; the default for
min is 0

assoc4 [1..1] The association has one target instance

assoc5 [0..*] The association has no, one, or multiple target instances

assoc6 [] Like assoc4, [] is short for [0..*] (the association has no, one, or multiple tar­
get instances)

assoc7 [2..7] Any numbers are possible; the user provides

assoc8 [1, 0..*] The association has no, one, or multiple target instances and includes addi­
tional information about the source cardinality

When an infix filter effectively reduces the cardinality of a “to-N” association to “to-1”, this can be expressed
explicitly in the filter, for example:

assoc[1: <cond> ]

Specifying the cardinality in the filter in this way enables you to use the association in the WHERE clause, where
“to-N” associations are not normally allowed.

SAP HANA Developer Guide

170 PUBLIC Setting up the Persistence Model
 Sample Code

namespace samples;
@Schema: 'MYSCHEMA' // XS classic *only*
context CardinalityByInfixFilter {
entity Person {
key id : Integer;
name : String(100);
address : Association[*] to Address on address.personId = id;
};
entity Address {
key id : Integer;
personId : Integer;
type : String(20); // home, business, vacation, ...
street : String(100);
city : String(100);
};
view V as select from Person {
name
} where address[1: type='home'].city = 'Accra';
};

Association Target

You use the to keyword in a CDS view definition to specify the target entity in an association, for example, the
name of an entity defined in a CDS document. A qualified entity name is expected that refers to an existing
entity. A target entity specification is mandatory; a default value is not assumed if no target entity is specified
in an association relationship.

Association[ <cardinality> ] to <targetEntity> [ <forwardLink> ]

The target entity Address specified as the target entity of an association could be expressed as illustrated the
following examples:

address1 : Association to Address;

address2 : Association to Address { id };
address3 : Association[1] to Address { zipCode, street, country };

Association Keys

In the relational model, associations are mapped to foreign-key relationships. For managed associations, the
relation between source and target entity is defined by specifying a set of elements of the target entity that are
used as a foreign key, as expressed in the forwardLink element of the following code example:

Association[ <cardinality> ] to <targetEntity> [ <forwardLink> ]

The forwardLink element of the association could be expressed as follows:

<forwardLink> = { <foreignKeys> }
<foreignKeys> = <targetKeyElement> [ AS <alias> ] [ , <foreignKeys> ]
<targetKeyElement> = <elementName> ( . <elementName> )*

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 171
If no foreign keys are specified explicitly, the elements of the target entity’s designated primary key are used.
Elements of the target entity that reside inside substructures can be addressed by means of the respective
path. If the chosen elements do not form a unique key of the target entity, the association has cardinality to-
many. The following examples show how to express foreign keys in an association.

entity Person
{
key id : Integer;
// address1,2,3 are to-one associations
address1 : Association to Address;
address2 : Association to Address { id };
address3 : Association[1] to Address { zipCode, street, country };
// address4,5,6 are to-many associations
address4 : Association[0..*] to Address { zipCode };
address5 : Association[*] to Address { street.name };
address6 : Association[*] to Address { street.name AS streetName,
country.name AS countryName };
};

Association Syntax Options

Association Keys Explanation

address1 No foreign keys are specified: the target entity's primary key (the element id) is
used as foreign key.

address2 { id } Explicitly specifies the foreign key (the element id); this definition is identical to
address1.

address3 { zipCode, The foreign key elements to be used for the association are explicitly specified,
street, namely: zipcode and the structured elements street and country.
country }

address4 { zipCode } Uses only zipcode as the foreign key. Since zipcode is not a unique key for
entity Address, this association has cardinality “to-many”.

address5 { street.name Uses the sub-element name of the structured element street as a foreign key.
} This is not a unique key and, as a result, address4 has cardinality “to-many”.

address6 { street.name Uses the sub-element name of both the structured elements street and
AS country as foreign key fields. The names of the foreign key fields must be
streetName, unique, so an alias is required here. The foreign key is not unique, so address6
country.name is a “to-many” association.
AS
countryName }

You can now use foreign keys of managed associations in the definition of other associations. In the following
example, the compiler recognizes that the field toCountry.cid is part of the foreign key of the association
toLocation and, as a result, physically present in the entity Company.

Sample Code

namespace samples;
@Schema: 'MYSCHEMA' // XS classic *only*
context AssociationKeys {
entity Country {
key c_id : String(3);
// <...>
};

SAP HANA Developer Guide

172 PUBLIC Setting up the Persistence Model
 entity Region {
key r_id : Integer;
key toCountry : Association[1] to Country { c_id };
// <...>
};
entity Company {
key id : Integer;
toLocation : Association[1] to Region { r_id, toCountry.c_id };
// <...>
};
};

Unmanaged Associations

Unmanaged associations are based on existing elements of the source and target entity; no fields are
generated. In the ON condition, only elements of the source or the target entity can be used; it is not possible to
use other associations. The ON condition may contain any kind of expression - all expressions supported in
views can also be used in the ON condition of an unmanaged association.

Note
The names in the ON condition are resolved in the scope of the source entity; elements of the target entity
are accessed through the association itself .

In the following example, the association inhabitants relates the element id of the source entity Room with
the element officeId in the target entity Employee. The target element officeId is accessed through the
name of the association itself.

namespace samples;
@Schema: 'MYSCHEMA' // XS classic *only*
context UnmanagedAssociations {
entity Employee {
key id : Integer;
officeId : Integer;
// <...>
};
entity Room {
key id : Integer;
inhabitants : Association[*] to Employee on inhabitants.officeId = id;
// <...>
};
entity Thing {
key id : Integer;
parentId : Integer;
parent : Association[1] to Thing on parent.id = parentId;
children : Association[*] to Thing on children.parentId = id;
// <...>
};
};

The following example defines two related unmanaged associations:

● parent
The unmanaged association parent uses a cardinality of [1] to create a relation between the element
parentId and the target element id. The target element id is accessed through the name of the
association itself.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 173
● children
The unmanaged association children creates a relation between the element id and the target element
parentId. The target element parentId is accessed through the name of the association itself.

entity Thing {
key id : Integer;
parentId : Integer;
parent : Association[1] to Thing on parent.id = parentId;
children : Association[*] to Thing on children.parentId = id;
...
};

Constants in Associations

The usage of constants is no longer restricted to annotation assignments and default values for entity
elements. With SPS 11, you can use constants in the “ON”-condition of unmanaged associations, as illustrated
in the following example:

Sample Code

context MyContext {
const MyIntConst : Integer = 7;
const MyStringConst : String(10) = 'bright';
const MyDecConst : Decimal(4,2) = 3.14;
const MyDateTimeConst : UTCDateTime = '2015-09-30 14:33';
entity MyEntity {
key id : Integer;
a : Integer;
b : String(100);
c : Decimal(20,10);
d : UTCDateTime;
your : Association[1] to YourEntity on your.a - a < MyIntConst;
};
entity YourEntity {
key id : Integer;
a : Integer;
};
entity HerEntity {
key id : Integer;
t : String(20);
};
view MyView as select from MyEntity
inner join HerEntity on locate (b, :MyStringConst) > 0
{
a + :MyIntConst as x,
b || ' is ' || :MyStringConst as y,
c * sin(:MyDecConst) as z
} where d < :MyContext.MyDateTimeConst;
};

Related Information

CDS Associations [page 162]

SAP HANA Developer Guide

174 PUBLIC Setting up the Persistence Model
4.1.6 Create a View in CDS

A view is a virtual table based on the dynamic results returned in response to an SQL statement. SAP HANA
Extended Application Services (SAP HANA XS) enables you to use CDS syntax to create a database view as a
design-time file in the repository.

Prerequisites

● You have created a schema for the CDS catalog objects, for example, MYSCHEMA.
● You have SELECT privileges on the schema so you can see the generated catalog objects.

Context

SAP HANA Extended Application Services (SAP HANA XS) enables you to use the CDS syntax to create a
database view as a design-time file in the repository. Repository files are transportable. Activating the CDS view
definition creates the corresponding catalog object in the specified schema.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the CDS entity-definition file that will contain the view you define.
a. In the package structure, select the package where you want to create the new CDS definition file and
from the context menu choose New File .
b. Enter the name of the view-definition file in the File Name field, for example, MyEntity2.hdbdd, and
choose Create.
3. Define the underlying CDS entities and structured types.
Add the code for the entity definitions and structured types to the file, as shown in the example below:

namespace com.acme.myapp1;
@Schema : 'MYSCHEMA'
context MyEntity2 {
type StreetAddress {
name : String(80);
number : Integer;
};
type CountryAddress {
name : String(80);
code : String(3);
};
@Catalog.tableType : #COLUMN
entity Address {
key id : Integer;

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 175
 street : StreetAddress;
zipCode : Integer;
city : String(80);
country : CountryAddress;
type : String(10); // home, office
};
};

4. Define a view as a projection of a CDS entity.

In the same entity-definition file you edited in the previous step, add the code for the view AddressView
below the entity Address in the CDS document. Note that in CDS, a view is an entity without its own
persistence; it is defined as a projection of other entities.

view AddressView as select from Address

{
id,
street.name,
street.number
};

5. Save the CDS-definition file containing the new view.

6. Check that the new view has been successfully created.
Views are created in the Views folder in the catalog.
a. Open the catalog.
b. Navigate to the catalog location where you created the new view:
Catalog <MYSCHEMA> Views
c. Select the new entity <package.path>::MyEntity2.AddressView to display its definition.

Related Information

CDS Views [page 176]

CDS View Syntax Options [page 184]
Spatial Types and Functions [page 196]

4.1.6.1 CDS Views

A view is an entity that is not persistent; it is defined as the projection of other entities. SAP HANA Extended
Application Services (SAP HANA XS) enables you to create a CDS view as a design-time file in the repository.

SAP HANA Extended Application Services (SAP HANA XS) enables you to define a view in a CDS document,
which you store as design-time file in the repository. Repository files can be read by applications that you
develop. In addition, all repository files including your view definition can be transported to other SAP HANA
systems, for example, in a delivery unit.

If your application refers to the design-time version of a view from the repository rather than the runtime
version in the catalog, for example, by using the explicit path to the repository file (with suffix), any changes to
the repository version of the file are visible as soon as they are committed to the repository. There is no need to
wait for the repository to activate a runtime version of the view.

SAP HANA Developer Guide

176 PUBLIC Setting up the Persistence Model
To define a transportable view using the CDS-compliant view specifications, use something like the code
illustrated in the following example:

context Views {
VIEW AddressView AS SELECT FROM Address {
id,
street.name,
street.number
};
<...>
}

When a CDS document is activated, the activation process generates a corresponding catalog object for each
of the artifacts defined in the document; the location in the catalog is determined by the type of object
generated. For example, in SAP HANA XS classic the corresponding catalog object for a CDS view definition is
generated in the following location:

<SID> Catalog <MYSCHEMA> Views

Views defined in a CDS document can make use of the following SQL features:

● CDS Type definition [page 177]

● Expressions [page 178]
● A selection of functions [page 178]
● Aggregates [page 178]
● Group by [page 178]
● Having [page 178]
● Associations [page 179] (including filters and prefixes)
● Order by [page 181]
● Case [page 182]
● Union [page 182]
● Join [page 182]
● Select Distinct [page 183]
● Spatial Data [page 183]

Type Definition

In a CDS view definition, you can explicitly specify the type of a select item, as illustrated in the following
example:

Sample Code

type MyInteger : Integer;

entity E {
a : MyInteger;
b : MyInteger;
};
view V as select from E {
a,
a+b as s1,
a+b as s2 : MyInteger
};

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 177
In the example of different type definitions, the following is true:

● a,
Has type “MyInteger”
● a+b as s1,
Has type “Integer” and any information about the user-defined type is lost
● a+b as s2 : MyInteger
Has type “MyInteger”, which is explicitly specified

Note
If necessary, a CAST function is added to the generated view in SAP HANA; this ensures that the select
item's type in the SAP HANA view is the SAP HANA “type” corresponding to the explicitly specified CDS
type.

Expressions and Functions

CDS support the use of functions and expressions in a view. For example, you can specify a value calculated as
the sum of multiple values, as illustrated in the following example:

VIEW MyView AS SELECT FROM UnknownEntity

{
a + b AS theSum
};

Note
When expressions are used in a view element, an alias must be specified.

Aggregates, Group by, and Having

The following example shows how to use aggregates (count, sum) in a CDS view definition. In this example, the
view to is used to collect information about headcount and salary per organizational unit for all employees
hired from 2011 up till now.

VIEW MyView2 AS SELECT FROM Employee

{
orgUnit,
count(id) AS headCount,
sum(salary) AS totalSalary,
max(salary) AS maxSalary
}
WHERE joinDate > date'2011-01-01'
GROUP BY orgUnit;

Note
Expressions are not allowed in the GROUP BY clause.

SAP HANA Developer Guide

178 PUBLIC Setting up the Persistence Model
Associations in Views

In a CDS view definition, associations can be used to gather information from the specified target entities. In
SQL, associations are mapped to joins.

In the context of a CDS view definition, you can use associations in the following places:

● The SELECT list

● The WHERE clause
● The FROM clause
● The GROUP BY clause
● With filters
● With the prefix notation

In the following example of an association in a SELECT list, a view is used to compile a list of all employees; the
list includes the employee's name, the capacity of the employee's office, and the color of the carpet in the
office. The association follows the to-one association office from entity Employee to entity Room to assemble
the information about the office.

Note
To-n (many) associations are not supported in the WHERE clause.

VIEW MyView3 AS SELECT FROM Employee

{
name.last,
office.capacity,
office.carpetColor
};

The following example shows how associations can also be used in the WHERE clause to restrict the result set
returned by the view to information located in the association's target.

VIEW EmployeesInRoom_ABC_3_4 AS SELECT FROM Employee

{
name.last
} WHERE office.building = 'ABC'
AND office.floor = 3
AND office.number = 4;

The following example shows how to use an association in the FROM clause to list the license plates of all
company cars.

VIEW CompanyCarLicensePlates AS SELECT FROM Employee.companyCar

{
licensePlate
};

The following example shows how to use an association in the GROUP BY clause to compile a list of all offices
that are less than 50% occupied.

VIEW V11 AS SELECT FROM Employee

{
officeId.building,
officeId.floor,
officeId.roomNumber,
office.capacity,

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 179
 count(id) AS seatsTaken,
count(id)/office.capacity AS occupancyRate
} GROUP BY officeId.building,
officeId.floor,
officeId.roomNumber,
office.capacity,
office.type
HAVING office.type = 'office' AND count(id)/capacity < 0.5;

When following an association in a view, it is now possible to apply a filter condition; the filter is merged into the
ON-condition of the resulting JOIN. The following example shows how to get a list of customers and then filter
the list according to the sales orders that are currently “open” for each customer. In the example, the filter is
inserted after the association orders; this ensures that the list displayed by the view only contains those
orders that satisfy the condition [status='open'].

Sample Code

view C1 as select from Customer {

name,
orders[status='open'].id as orderId
};

If an additional element date is included in the filter, a corresponding (and separate) JOIN is created.
Associations with multiple separate filters are never combined, so in this case two JOINS are created.

Sample Code

view C2 as select from Customer {

name,
orders[status='open'].id as orderId,
orders[status='open'].date as orderDate
};

To ensure that the compiler understands that there is only one association (orders) to resolve but with
multiple elements (id and date), use the prefix notation illustrated in the following example:

Sample Code

view C3 as select from Customer {

name,
orders[status='open'].{ id as orderId,
date as orderDate
}
};

Tip
Filter conditions and prefixes can be nested.

The following example shows how to use the associations orders and items in a view that displays a list of
customers with open sales orders for items with a price greater than 200.

SAP HANA Developer Guide

180 PUBLIC Setting up the Persistence Model
 Sample Code

view C4 as select from Customer {

name,
orders[status='open'].{ id as orderId,
date as orderDate,
items[price>200].{ descr,
price
}
}
};

You can define an association as a view element, for example, by definining an ad-hoc association in the mixin
clause and then adding the association to the SELECT list, as illustrated in the following example:

Sample Code
Associations as View Elements

entity E {
a : Integer;
b : Integer;
};
entity F {
x : Integer;
y : Integer;
};
view VE as select from E mixin {
f : Association[1] to VF on f.vy = $projection.vb;
} into {
a as va,
b as vb,
f as vf
};
view VF as select from F {
x as vx,
y as vy
};

In the ON condition of this type of association in a view, it is necessary to use the pseudo-identifier
$projection to specify that the following element name must be resolved in the select list of the view
(“VE”) rather than in the entity (“E”) in the FROM clause

Order by

The ORDER BY operator enables you to list results according to an expression or position, for example salary.
In the same way as with plain SQL, the ASC and DESC operators enable you to specify if the results list is sorted
in ascending or descending order, respectively.

VIEW MyView4 AS SELECT FROM Employee

{
orgUnit,
salary
} ORDER BY salary DESC;

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 181
Case

In the same way as in plain SQL, you can use the case expression in a CDS view definition to introduce IF-
THEN-ELSE conditons without the need to use procedures.

entity MyEntity {
key id : Integer;
a : Integer;
color : String(1);
};

VIEW MyView5 AS SELECT FROM MyEntity {

id,
CASE color // defined in MyEntity
WHEN 'R' THEN 'red'
WHEN 'G' THEN 'green'
WHEN 'B' THEN 'blue'
ELSE 'black'
END AS color,
CASE
WHEN a < 10 then 'small'
WHEN 10 <= a AND a < 100 THEN 'medium'
ELSE 'large'
END AS size
};

Union

Enables multiple select statements to be combined but return only one result set. UNION selects all unique
records from all select statements by removing duplicates found from different select statements.

Note
UNION has the same function as UNION DISTINCT.

Join

You can include a JOIN clause in a CDS view definition; the following JOIN types are supported:

● [ INNER ] JOIN
● LEFT [ OUTER ] JOIN
● RIGHT [ OUTER ] JOIN
● FULL [ OUTER ] JOIN
● CROSS JOIN

Sample Code

entity E {
key id : Integer;
a : Integer;

SAP HANA Developer Guide

182 PUBLIC Setting up the Persistence Model
 };
entity F {
key id : Integer;
b : Integer;
};
entity G {
key id : Integer;
c : Integer;
};
view V_join as select from E join (F as X full outer join G on X.id = G.id) on
E.id = c {
a, b, c
};

Select Distinct

CDS now supports the SELECT DISTINCT semantic. Note the position of the DISTINCT keyword directly in
front of the curly brace:

Sample Code

view V_dist as select from E distinct { a };

Spatial Data

Spatial data is data that describes the position, shape, and orientation of objects in a defined space; the data is
represented as two-dimensional geometries in the form of points, line strings, and polygons. The following
examples shows how to use the spatial function ST_Distance in a CDS view. The spatial function populates
the CDS view with information (stored using the spatial data type ST_POINT) indicating the distance between
each person's home and business address (distanceHomeToWork) as well as the distance between the
designated home address and the building SAP03 (distFromSAP03).

Sample Code

view GeoView1 as select from Person {

name,
homeAddress.street_name || ', ' || homeAddress.city as home,
officeAddress.street_name || ', ' || officeAddress.city as office,
round( homeAddress.loc.ST_Distance(officeAddress.loc, 'meter')/1000, 1) as
distanceHomeToWork,
round( homeAddress.loc.ST_Distance(NEW ST_POINT(8.644072, 49.292910),
'meter')/1000, 1) as distFromSAP03
};

Caution
(*) SAP HANA server software and tools can be used for several SAP HANA platform and options scenarios
as well as the respective capabilities used in these scenarios. The availability of these is based on the

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 183
 available SAP HANA licenses and the SAP HANA landscape, including the type and version of the back-end
systems the SAP HANA administration and development tools are connected to. There are several types of
licenses available for SAP HANA. Depending on your SAP HANA installation license type, some of the
features and tools described in the SAP HANA platform documentation may only be available in the SAP
HANA options and capabilities, which may be released independently of an SAP HANA Platform Support
Package Stack (SPS). Although various features included in SAP HANA options and capabilities are cited in
the SAP HANA platform documentation, each SAP HANA edition governs the options and capabilities
available. Based on this, customers do not necessarily have the right to use features included in SAP HANA
options and capabilities. For customers to whom these license restrictions apply, the use of features
included in SAP HANA options and capabilities in a production system requires purchasing the
corresponding software license(s) from SAP. The documentation for the SAP HANA options is available in
SAP Help Portal. If you have additional questions about what your particular license provides, or wish to
discuss licensing features available in SAP HANA options, please contact your SAP account team
representative.

Related Information

Create a View in CDS [page 175]

CDS Associations [page 162]
CDS View Syntax Options [page 184]

4.1.6.2 CDS View Syntax Options

SAP HANA XS includes a dedicated, CDS-compliant syntax, which you must adhere to when using a CDS
document to define a view as a design-time artifact.

Example

Note
The following example is intended for illustration purposes only and might contain syntactical errors. For
further details about the keywords illustrated, click the links provided.

context views {
const x : Integer = 4;
const y : Integer = 5;
const Z : Integer = 6;
VIEW MyView1 AS SELECT FROM Employee
{
a + b AS theSum
};
VIEW MyView2 AS SELECT FROM Employee
{ officeId.building,
officeId.floor,
officeId.roomNumber,
office.capacity,
count(id) AS seatsTaken,
count(id)/office.capacity as occupancyRate

SAP HANA Developer Guide

184 PUBLIC Setting up the Persistence Model
 } WHERE officeId.building = 1
GROUP BY officeId.building,
officeId.floor,
officeId.roomNumber,
office.capacity,
office.type
HAVING office.type = 'office' AND count(id)/office.capacity < 0.5;
VIEW MyView3 AS SELECT FROM Employee
{ orgUnit,
salary
} ORDER BY salary DESC;
VIEW MyView4 AS SELECT FROM Employee {
CASE
WHEN a < 10 then 'small'
WHEN 10 <= a AND a < 100 THEN 'medium'
ELSE 'large'
END AS size
};
VIEW MyView5 AS
SELECT FROM E1 { a, b, c}
UNION
SELECT FROM E2 { z, x, y};
VIEW MyView6 AS SELECT FROM Customer {
name,
orders[status='open'].{ id as orderId,
date as orderDate,
items[price>200].{ descr,
price } }
};
VIEW V_join as select from E join (F as X full outer join G on X.id = G.id) on
E.id = c {
a, b, c
};
VIEW V_dist as select from E distinct { a };
VIEW V_type as select from E {
a,
a+b as s1,
a+b as s2 : MyInteger
};
view VE as select from E mixin {
f : Association[1] to VF on f.vy = $projection.vb;
} into {
a as va,
b as vb,
f as vf
};
VIEW SpatialView1 as select from Person {
name,
homeAddress.street_name || ', ' || homeAddress.city as home,
officeAddress.street_name || ', ' || officeAddress.city as office,
round( homeAddress.loc.ST_Distance(officeAddress.loc, 'meter')/1000, 1) as
distanceHomeToWork,
round( homeAddress.loc.ST_Distance(NEW ST_POINT(8.644072, 49.292910),
'meter')/1000, 1) as distFromSAP03
};
}

Expressions and Functions

In a CDS view definition you can use any of the functions and expressions listed in the following example:

View MyView9 AS SELECT FROM SampleEntity

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 185
 {
a + b AS theSum,
a - b AS theDifference,
a * b AS theProduct,
a / b AS theQuotient,
-a AS theUnaryMinus,
c || d AS theConcatenation
};

Note
When expressions are used in a view element, an alias must be specified, for example, AS theSum.

Aggregates

In a CDS view definition, you can use the following aggregates:

● AVG
● COUNT
● MIN
● MAX
● SUM
● STDDEV
● VAR

The following example shows how to use aggregates and expressions to collect information about headcount
and salary per organizational unit for all employees hired from 2011 to now.

VIEW MyView10 AS SELECT FROM Employee

{
orgUnit,
count(id) AS headCount,
sum(salary) AS totalSalary,
max(salary) AS maxSalary
}
WHERE joinDate > date'2011-01-01'
GROUP BY orgUnit;

Note
Expressions are not allowed in the GROUP BY clause.

Constants in Views

With SPS 11, you can use constants in the views, as illustrated in “MyView” at the end of the following example:

Sample Code

context MyContext {

SAP HANA Developer Guide

186 PUBLIC Setting up the Persistence Model
 const MyIntConst : Integer = 7;
const MyStringConst : String(10) = 'bright';
const MyDecConst : Decimal(4,2) = 3.14;
const MyDateTimeConst : UTCDateTime = '2015-09-30 14:33';
entity MyEntity {
key id : Integer;
a : Integer;
b : String(100);
c : Decimal(20,10);
d : UTCDateTime;
your : Association[1] to YourEntity on your.a - a < MyIntConst;
};
entity YourEntity {
key id : Integer;
a : Integer;
};
entity HerEntity {
key id : Integer;
t : String(20);
};
view MyView as select from MyEntity
inner join HerEntity on locate (b, :MyStringConst) > 0
{
a + :MyIntConst as x,
b || ' is ' || :MyStringConst as y,
c * sin(:MyDecConst) as z
} where d < :MyContext.MyDateTimeConst;
};

When constants are used in a view definition, their name must be prefixed with the scope operator “:”. Usually
names that appear in a query are resolved as alias or element names. The scope operator instructs the
compiler to resolve the name outside of the query.

Sample Code

context NameResolution {
const a : Integer = 4;
const b : Integer = 5;
const c : Integer = 6;
entity E {
key id : Integer;
a : Integer;
c : Integer;
};
view V as select from E {
a as a1,
b,
:a as a2,
E.a as a3,
:E,
:E.a as a4,
:c
};
}

The following table explains how the constants used in view “V” are resolved.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 187
Constant Declaration and Result

Constant Expression Result Comments

a as a1, Success “a” is resolved in the space of alias and element names, for example, ele­
ment “a” of entity “E”.

b, Error There is no alias and no element with name “b” in entity “E”

:a as a2, Success Scope operator “:” instructs the compiler to search for element “a” out­
side of the query (finds the constant “a”).

E.a as a3, Success “E” is resolved in the space of alias and element names, so this matches
element “a” of entity “Entity” .

:E, Success Error: no access to “E” via “:”

:E.a as a4, Error Error; no access to “E” (or any of its elements) via “:”

:c Error Error: there is no alias for “c”.

SELECT

In the following example of an association in a SELECT list, a view compiles a list of all employees; the list
includes the employee's name, the capacity of the employee's office, and the color of the carpet in the office.
The association follows the to-one association office from entity Employee to entity Room to collect the
relevant information about the office.

VIEW MyView11 AS SELECT FROM Employee

{
name.last,
office.capacity,
office.carpetColor
};

WHERE

The following example shows how the syntax required in the WHERE clause used in a CDS view definition. In this
example, the WHERE clause is used in an association to restrict the result set according to information located
in the association's target. Further filtering of the result set can be defined with the AND modifier.

VIEW EmployeesInRoom_ABC_3_4 AS SELECT FROM Employee

{
name.last
} WHERE officeId.building = 'ABC'
AND officeId.floor = 3
AND officeId.number = 4;

SAP HANA Developer Guide

188 PUBLIC Setting up the Persistence Model
FROM

The following example shows the syntax required when using the FROM clause in a CDS view definition. This
example shows an association that lists the license plates of all company cars.

VIEW CompanyCarLicensePlates AS SELECT FROM Employee.companyCar

{
licensePlate
};

In the FROM clause, you can use the following elements:

● an entity or a view defined in the same CDS source file

● a native SAP HANA table or view that is available in the schema specified in the schema annotation
(@Schema in the corresponding CDS document)

If a CDS view references a native SAP HANA table, the table and column names must be specified using their
effective SAP HANA names.

create table foo (

bar : Integer,
"gloo" : Integer
)

This means that if a table (foo) or its columns (bar and “gloo” were created without using quotation marks
(""), the corresponding uppercase names for the table or columns must be used in the CDS document, as
illustrated in the following example.

VIEW MyViewOnNative as SELECT FROM FOO

{
BAR,
gloo
};

GROUP BY

The following example shows the syntax required when using the GROUP BY clause in a CDS view definition.
This example shows an association in a view that compiles a list of all offices that are less than 50% occupied.

VIEW V11 AS SELECT FROM Employee

{
officeId.building,
officeId.floor,
officeId.roomNumber,
office.capacity,
count(id) as seatsTaken,
count(id)/office.capacity as occupancyRate
} GROUP BY officeId.building,
officeId.floor,
officeId.roomNumber,
office.capacity,
office.type
HAVING office.type = 'office' AND count(id)/capacity < 0.5;

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 189
HAVING

The following example shows the syntax required when using the HAVING clause in a CDS view definition. This
example shows a view with an association that compiles a list of all offices that are less than 50% occupied.

VIEW V11 AS SELECT FROM Employee

{
officeId.building,
officeId.floor,
officeId.roomNumber,
office.capacity,
count(id) as seatsTaken,
count(id)/office.capacity as occupancyRate
} GROUP BY officeId.building,
officeId.floor,
officeId.roomNumber,
office.capacity,
office.type
HAVING office.type = 'office' AND count(id)/capacity < 0.5;

ORDER BY

The ORDER BY operator enables you to list results according to an expression or position, for example salary.

VIEW MyView3 AS SELECT FROM Employee

{
orgUnit,
salary
} ORDER BY salary DESC;

In the same way as with plain SQL, the ASC and DESC operators enable you to sort the list order as follows.

● ASC
Display the result set in ascending order
● DESC
Display the result set in descending order

CASE

In the same way as in plain SQL, you can use the case expression in a CDS view definition to introduce IF-
THEN-ELSE conditons without the need to use procedures.

entity MyEntity12 {
key id : Integer;
a : Integer;
color : String(1);
};

VIEW MyView12 AS SELECT FROM MyEntity12 {

id,
CASE color // defined in MyEntity12
WHEN 'R' THEN 'red'

SAP HANA Developer Guide

190 PUBLIC Setting up the Persistence Model
 WHEN 'G' THEN 'green'
WHEN 'B' THEN 'blue'
ELSE 'black'
END AS color,
CASE
WHEN a < 10 then 'small'
WHEN 10 <= a AND a < 100 THEN 'medium'
ELSE 'large'
END AS size
};

In the first example of usage of the CASE operator, CASE color shows a “switched” CASE (one table column
and multiple values). The second example of CASE usage shows a “conditional” CASE with multiple arbitrary
conditions, possibly referring to different table columns.

UNION

Enables multiple select statements to be combined but return only one result set. UNION works in the same
way as the SAP HANA SQL command of the same name; it selects all unique records from all select statements
by removing duplicates found from different select statements.The signature of the result view is equal to the
signature of the first SELECT in the union.

Note
View MyView5 has elements a, b, and c.

entity E1 {
key a : Integer;
b : String(20);
c : LocalDate;
};
entity E2 {
key x : String(20);
y : LocalDate;
z : Integer;
};
VIEW MyView5 AS
SELECT FROM E1 { a, b, c}
UNION
SELECT FROM E2 { z, x, y};

JOIN

You can include a JOIN clause in a CDS view definition; the following JOIN types are supported:

● [ INNER ] JOIN
● LEFT [ OUTER ] JOIN
● RIGHT [ OUTER ] JOIN
● FULL [ OUTER ] JOIN
● CROSS JOIN

The following example shows a simple join.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 191
 Sample Code

entity E {
key id : Integer;
a : Integer;
};
entity F {
key id : Integer;
b : Integer;
};
entity G {
key id : Integer;
c : Integer;
};
view V_join as select from E join (F as X full outer join G on X.id = G.id) on
E.id = c {
a, b, c
};

SELECT DISTINCT

CDS now supports the SELECT DISTINCT semantic. The position of the DISTINCT keyword is important; it
must appear directly in front of the curly brace, as illustrated in the following example:

Sample Code

entity E {
key id : Integer;
a : Integer;
};
entity F {
key id : Integer;
b : Integer;
};
entity G {
key id : Integer;
c : Integer;
};
view V_dist as select from E distinct { a };

Associations, Filters, and Prefixes

You can define an association as a view element, for example, by definining an ad-hoc association in the mixin
clause and then adding the association to the SELECT list, as illustrated in the following example:

Sample Code
Associations as View Elements

entity E {
a : Integer;

SAP HANA Developer Guide

192 PUBLIC Setting up the Persistence Model
 b : Integer;
};
entity F {
x : Integer;
y : Integer;
};
view VE as select from E mixin {
f : Association[1] to VF on f.vy = $projection.vb;
} into {
a as va,
b as vb,
f as vf
};
view VF as select from F {
x as vx,
y as vy
};

In the ON condition of this type of association in a view, it is necessary to use the pseudo-identifier
$projection to specify that the following element name must be resolved in the select list of the view
(“VE”) rather than in the entity (“E”) in the FROM clause

Filter Conditions

It is possible to apply a filter condition when resolving associations between entities; the filter is merged into
the ON-condition of the resulting JOIN. The following example shows how to get a list of customers and then
filter the list according to the sales orders that are currently “open” for each customer. In the example, the filter
is inserted after the association orders; this ensures that the list displayed by the view only contains those
orders that satisfy the condition [status='open'].

Sample Code

view C1 as select from Customer {

name,
orders[status='open'].id as orderId
};

The following example shows how to use the prefix notation to ensure that the compiler understands that there
is only one association (orders) to resolve but with multiple elements (id and date):

Sample Code

view C1 as select from Customer {

name,
orders[status='open'].{ id as orderId,
date as orderDate
}
};

Tip
Filter conditions and prefixes can be nested.

The following example shows how to use the associations orders and items in a view that displays a list of
customers with open sales orders for items with a price greater than 200.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 193
 Sample Code

view C2 as select from Customer {

name,
orders[status='open'].{ id as orderId,
date as orderDate,
items[price>200].{ descr,
price
}
}
};

Prefix Notation
The prefix notation can also be used without filters. The following example shows how to get a list of all
customers with details of their sales orders. In this example, all uses of the association orders are combined
so that there is only one JOIN to the table SalesOrder. Similarly, both uses of the association items are
combined, and there is only one JOIN to the table Item.

Sample Code

view C3 as select from Customer {

name,
orders.id as orderId,
orders.date as orderDate,
orders.items.descr as itemDescr,
orders.items.price as itemPrice
};

The example above can be expressed more elegantly by combining the associations orders and items using
the following prefix notation:

Sample Code

view C1 as select from Customer {

name,
orders.{ id as orderId,
date as orderDate,
items. { descr as itemDescr,
price as itemPrice
}
}
};

Type Definition

In a CDS view definition, you can explicitly specify the type of a select item, as illustrated in the following
example:

Sample Code

type MyInteger : Integer;

SAP HANA Developer Guide

194 PUBLIC Setting up the Persistence Model
 entity E {
a : MyInteger;
b : MyInteger;
};
view V as select from E {
a,
a+b as s1,
a+b as s2 : MyInteger
};

In the example of different type definitions, the following is true:

● a,
Has type “MyInteger”
● a+b as s1,
Has type “Integer” and any information about the user-defined type is lost
● a+b as s2 : MyInteger
Has type “MyInteger”, which is explicitly specified

Note
If necessary, a CAST function is added to the generated view in SAP HANA; this ensures that the select
item's type in the SAP HANA view is the SAP HANA “type” corresponding to the explicitly specified CDS
type.

Spatial Functions

The following view (SpatialView1) displays a list of all persons selected from the entity Person and uses the
spatial function ST_Distance (*) to include information such as the distance between each person's home
and business address (distanceHomeToWork), and the distance between their home address and the
building SAP03 (distFromSAP03). The value for both distances is measured in kilometers, which is rounded
up and displayed to one decimal point.

Sample Code

view SpatialView1 as select from Person {

name,
homeAddress.street_name || ', ' || homeAddress.city as home,
officeAddress.street_name || ', ' || officeAddress.city as office,
round( homeAddress.loc.ST_Distance(officeAddress.loc, 'meter')/1000, 1) as
distanceHomeToWork,
round( homeAddress.loc.ST_Distance(NEW ST_POINT(8.644072, 49.292910),
'meter')/1000, 1) as distFromSAP03
};

Caution
(*) SAP HANA server software and tools can be used for several SAP HANA platform and options scenarios
as well as the respective capabilities used in these scenarios. The availability of these is based on the
available SAP HANA licenses and the SAP HANA landscape, including the type and version of the back-end
systems the SAP HANA administration and development tools are connected to. There are several types of

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 195
 licenses available for SAP HANA. Depending on your SAP HANA installation license type, some of the
features and tools described in the SAP HANA platform documentation may only be available in the SAP
HANA options and capabilities, which may be released independently of an SAP HANA Platform Support
Package Stack (SPS). Although various features included in SAP HANA options and capabilities are cited in
the SAP HANA platform documentation, each SAP HANA edition governs the options and capabilities
available. Based on this, customers do not necessarily have the right to use features included in SAP HANA
options and capabilities. For customers to whom these license restrictions apply, the use of features
included in SAP HANA options and capabilities in a production system requires purchasing the
corresponding software license(s) from SAP. The documentation for the SAP HANA options is available in
SAP Help Portal. If you have additional questions about what your particular license provides, or wish to
discuss licensing features available in SAP HANA options, please contact your SAP account team
representative.

Related Information

Create a View in CDS [page 175]

Spatial Types and Functions [page 196]

4.1.6.3 Spatial Types and Functions

CDS supports the use of Geographic Information Systems (GIS) functions and element types in CDS-
compliant entities and views.

Spatial data is data that describes the position, shape, and orientation of objects in a defined space; the data is
represented as two-dimensional geometries in the form of points, line strings, and polygons. The following
examples shows how to use the spatial function ST_Distance in a CDS view. The underlying spatial data used
in the view is defined in a CDS entity using the type ST_POINT.

Tip
For more information about spatial types and functions, see the SAP HANA Spatial Reference on the SAP
Help Portal.

The following example, the CDS entity Address is used to store geo-spatial coordinates in element loc of type
ST_POINT:

Sample Code

namespace samples;
@Schema: 'MYSCHEMA'
context Spatial {
entity Person {
key id : Integer;
name : String(100);
homeAddress : Association[1] to Address;
officeAddress : Association[1] to Address;
};
entity Address {

SAP HANA Developer Guide

196 PUBLIC Setting up the Persistence Model
 key id : Integer;
street_number : Integer;
street_name : String(100);
zip : String(10);
city : String(100);
loc : hana.ST_POINT(4326);
};
view GeoView1 as select from Person {
name,
homeAddress.street_name || ', ' || homeAddress.city as home,
officeAddress.street_name || ', ' || officeAddress.city as office,
round( homeAddress.loc.ST_Distance(officeAddress.loc, 'meter')/1000,
1) as distanceHomeToWork,
round( homeAddress.loc.ST_Distance(NEW ST_POINT(8.644072, 49.292910),
'meter')/1000, 1) as distFromSAP03
};
};

The view GeoView1 is used to display a list of all persons using the spatial function ST_Distance to include
information such as the distance between each person's home and business address
(distanceHomeToWork), and the distance between their home address and the building SAP03
(distFromSAP03). The value for both distances is measured in kilometers.

Caution
(*) SAP HANA server software and tools can be used for several SAP HANA platform and options scenarios
as well as the respective capabilities used in these scenarios. The availability of these is based on the
available SAP HANA licenses and the SAP HANA landscape, including the type and version of the back-end
systems the SAP HANA administration and development tools are connected to. There are several types of
licenses available for SAP HANA. Depending on your SAP HANA installation license type, some of the
features and tools described in the SAP HANA platform documentation may only be available in the SAP
HANA options and capabilities, which may be released independently of an SAP HANA Platform Support
Package Stack (SPS). Although various features included in SAP HANA options and capabilities are cited in
the SAP HANA platform documentation, each SAP HANA edition governs the options and capabilities
available. Based on this, customers do not necessarily have the right to use features included in SAP HANA
options and capabilities. For customers to whom these license restrictions apply, the use of features
included in SAP HANA options and capabilities in a production system requires purchasing the
corresponding software license(s) from SAP. The documentation for the SAP HANA options is available in
SAP Help Portal. If you have additional questions about what your particular license provides, or wish to
discuss licensing features available in SAP HANA options, please contact your SAP account team
representative.

Related Information

Create a View in CDS [page 175]

CDS View Syntax Options [page 184]
CDS Entity Syntax Options [page 139]
CDS Primitive Data Types [page 158]

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 197
4.1.7 Modifications to CDS Artifacts

Changes to the definition of a CDS artifact result in changes to the corresponding catalog object. The resultant
changes to the catalog object are made according to strict rules.

Reactivating a CDS document which contains changes to the original artifacts results in changes to the
corresponding objects in the catalog. Before making change to the design-time definition of a CDS artifact, it is
very important to understand what the consequences of the planned changes will be in the generated catalog
objects.

● Removing an artifact from a CDS document [page 198]

● Changing the definition of an artifact in a CDS document [page 198]
● Modifying a catalog object generated by CDS [page 200]
● Transporting a DU that contains modified CDS documents [page 201]

Removing an Artifact from a CDS Document

If a CDS design-time artifact (for example, a table or a view) defined in an old version of a CDS document is no
longer present in the new version, the corresponding runtime object is dropped from the catalog.

Note
Renaming a CDS artifact results in the deletion of the artifact with the old name (with all the corresponding
consequences) and the creation of a new CDS artifact with the new name.

Changing the Definition of an Artifact in a CDS Document

If a CDS design-time artifact is present in both the old and the new version of a CDS document, a check is
performed to establish what, if any, changes have occurred. This applies to changes made either directly to a
CDS artifact or indirectly, for example, as a result of a change to a dependent artifact. If changes have been
made to the CDS document, changes are implemented in the corresponding catalog objects according to the
following rules:

● Views
Views in the SAP HANA catalog are dropped and recreated according to the new design-time specification
for the artifact in the CDS document.
● Element types
Changing the type of an element according to the implicit conversion rules described in the SAP HANA
SQL documentation (SAP HANA SQL Data Type Conversion). Note: For some type conversions the
activation will succeed only if the data in the corresponding DB table is valid for the target type (for
example the conversion of String to Integer will succeed only if the corresponding DB table column
contains only numbers that match the Integer type)
● Element modifier: Null/NOT NULL
Adding, removing or changing element modifiers “Null” and “not null” to make an element nullable ot
not nullable respectively can lead to problems when activating the resulting artifact; the activation will

SAP HANA Developer Guide

198 PUBLIC Setting up the Persistence Model
 succeed only if the data in the database table corresponding to the CDS entity matches the new modifier.
For example, you cannot make an element not nullable, if in the corresponding column in the database
table some null values exist for which there is no default value defined.
● Element modifier: Default Value
If the default value modifier is removed, this has no effect on the existing data in the corresponding
database table, and no default value will be used for any subsequently inserted record. If the default value
is modified or newly added, the change will be applicable to all subsequent inserts in the corresponding
database table. In addition, if the element is not nullable (irrespective of whether it was defined previously
as such or within the same activation), the existing null values in the corresponding table will be replaced
with the new default value.
● Element modifier: Primary Key
You can add an element to (or remove it from) the primary key by adding or removing the “key” modifier.

Note
Adding the “key” modifier to an element will also make the column in the corresponding table not
nullable. If column in the corresponding database table contains null values and there is no default
value defined for the element, the activation of the modified CDS document will fail.

● Column or row store (@Catalog.tableType)

It is possible to change the Catalog.tableType annotation that defines the table type, for example, to
transform a table from the column store (#COLUMN) to row store (#ROW), and vice versa.
● Index types (@Catalog.index)
Is is possible to change the “Catalog.index” annotation, as long as the modified index is valid for the
corresponding CDS entity.

For changes to individual elements of a CDS entity, for example, column definitions, the same logic applies as
for complete artifacts in a CDS document.

● Since the elements of a CDS entity are identified by their name, changing the order of the elements in the
entity definition will have no effect; the order of the columns in the generated catalog table object remains
unchanged.
● Renaming an element in a CDS entity definition is not recognized; the rename operation results in the
deletion of the renamed element and the creation of a new one.
● If a new element is added to a CDS entity definition, the order of the columns in the table generated in the
catalog after the change cannot be guaranteed.

Note
If an existing CDS entity definition is changed, the order of the columns in the generated database tables
may be different from the order of the corresponding elements in the CDS entity definition.

In the following example of a simple CDS document, the context OuterCtx contains a CDS entity Entity1 and
the nested context InnerCtx, which contains the CDS entity definition Entity2.

namespace pack;
@Schema: 'MYSCHEMA'
context OuterCtx
{
entity Entity1
{
key a : Integer;
b : String(20);
};

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 199
 context InnerCtx
{
entity Entity2
{
key x : Integer;
y : String(10);
z : LocalDate;
};
};
};

To understand the effect of the changes made to this simple CDS document in the following example, it is
necessary to see the changes not only from the perspective of the developer who makes the changes but also
the compiler which needs to interpret them.

From the developer's perspective, the CDS entity Entity1 has been moved from context OuterCtx to
InnerCtx. From the compiler's perspective, however, the entity pack::OuterCtx.Entity1 has disappeared
and, as a result, will be deleted (and the corresponding generated table with all its content dropped), and a new
entity named pack::OuterCtx.InnerCtx.Entity1 has been defined.

namespace pack;
@Schema: 'MYSCHEMA'
context OuterCtx
{
context InnerCtx
{
entity Entity1
{
key a : Integer;
b : String(20);
};
entity Entity2
{
key x : Integer;
q : String(10);
z : LocalDate;
};
};
};

Similarly, renaming the element y: String; to q: String; in Entity2 results in the deletion of column y
and the creation of a new column q in the generated catalog object. As a consequence, the content of column y
is lost.

Modifying a Catalog Object Generated from CDS

CDS does not support modifications to catalog objects generated from CDS documents. You must never
modify an SAP HANA catalog object (in particular a table) that has been generated from a CDS document. The
next time you activate the CDS document that contains the original CDS object definition and the
corresponding catalog objects are generated, all modifications made to the catalog object are lost or activation
might even fail due to inconsistencies.

SAP HANA Developer Guide

200 PUBLIC Setting up the Persistence Model
Transporting a DU that Contains Modified CDS Documents

If the definition of a CDS entity has already been transported to another system, do not enforce activation of
any illegal changes to this entity, for example, by means of an intermediate deletion.

Restrictions apply to changes that can be made to a CDS entity if the entity has been activated and a
corresponding catalog object exists. If changes to a CDS entity on the source system produce an error during
activation of the CDS document, for example, because you changed an element type in a CDS entity from
Binary to LocalDate, you could theoretically delete the original CDS entity and then create a new CDS entity
with the same name as the original entity but with the changed data type. However, if this change is
transported to another system, where the old version of the entity already exists, the import will fail, because
the information that the entity has been deleted and recreated is not available either on the target system or in
the delivery unit.

Related Information

SAP HANA to CDS Data-Type Mapping [page 216]

SAP HANA SQL Data Type Conversion

4.1.8 Tutorial: Import Data with CDS Table Import

The table-import function is a data-provisioning tool that enables you to import data from comma-separated
values (CSV) files into SAP HANA tables.

Context

In this tutorial, you import data from a CSV file into a table generated from a design-time definition that uses
the .hdbdd syntax, which complies with the Core Data Services (CDS) specifications. Note that the names
used are just examples; where necessary, replace the names of the schema, tables, files, and so on with your
own names.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create a root package for your table-import application.
a. In the structure, select the package (for example, mycompany.tests) where you want to create a new
package for your table-import configuration and from the context menu choose New Package .

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 201
 b. Enter a package name, for example, TiTest, and choose Create.

Note
Naming conventions exist for package names, for example, a package name must not start with
either a dot (.) or a hyphen (-) and cannot contain two or more consecutive dots (..). In addition, the
name must not exceed 190 characters.

3. If it does not already exist, create a schema named AMT directly in the catalog; the AMT schema is where
the target table for the table-import operation resides.
4. Create a set of table-import files.
For the purposes of this tutorial, you create all files in the same package, for example, a package called
TiTest. Note, however, that the table-import feature also allows you to use files distributed in different
packages.

The following files are required for the table import scenario:
○ The table-import configuration file, for example, inhabitants.hdbti
Specifies the source file containing the data values to import and the target table in SAP HANA into
which the data will be inserted.
○ A CSV file, for example, inhabitants.csv
Contains the data to be imported into the SAP HANA table during the table-import operation; values in
the .csv file can be separated either by a comma (,) or a semi-colon (;).
○ A target table, for example, inhabitants.hdbdd
The target table can be either a runtime table in the catalog or a table definition, for example, a table
defined using the .hdbtable syntax (TiTable.hdbtable) or the CDS-compliant .hdbdd syntax
(TiTable.hdbdd).

Note
In this tutorial, the target table for the table-import operation is inhabitants.hdbdd, a design-
time table defined using the CDS-compliant .hdbdd syntax.

When all the necessary files are available, you can import data from the source CSV file into the desired
target table.
5. Create or open the table-definition file for the target import table (inhabitants.hdbdd) and enter the
following lines of text; this example uses the .hdbdd syntax:

namespace mycompany.tests.TiTest;

@Schema : 'AMT'
@Catalog.tableType : #COLUMN
entity inhabitants {
key ID : Integer;
surname : String(30);
name : String(30);
city : String(30);
};

Note
In the CDS-compliant .hdbdd syntax, the namespace keyword denotes the path to the package
containing the table-definition file.

SAP HANA Developer Guide

202 PUBLIC Setting up the Persistence Model
6. Open the CSV file containing the data to import, for example, inhabitants.csv, in a text editor and enter
the values shown in the following example:

0,Annan,Kofi,Accra
1,Essuman,Wiredu,Tema
2,Tetteh,Kwame,Kumasi
3,Nterful,Akye,Tarkwa
4,Acheampong,Kojo,Tamale
5,Assamoah,Adjoa,Takoradi
6,Mensah,Afua,Cape Coast

Note
You can import data from multiple .csv files in a single, table-import operation. However, each .csv file
must be specified in a separate code block ({table= ...}) in the table-import configuration file.

7. Create or open the table-import configuration file (inhabitants.hdbti) and enter the following lines of
text (make sure the paths point to the correct locations in your environment):

import = [
{
table = "mycompany.tests.TiTest::inhabitants";
schema = "AMT";
file = "mycompany.tests.TiTest:inhabitants.csv";
header = false;
}
];

8. Save all files.

This activates all the repository objects. The data specified in the CSV file inhabitants.csv is imported
into the SAP HANA table inhabitants using the data-import configuration defined in the
inhabitants.hdbti table-import configuration file.
9. In the catalog, check the contents of the runtime table inhabitants to ensure that the correct data was
imported into the correct columns.

Expand the AMT Tables node, select the table mycompany.tests.TiTest::inhabitants, and
from the context menu choose Open Content.

4.1.8.1 Data Provisioning Using Table Import

You can import data from comma-separated values (CSV) into the SAP HANA tables using the SAP HANA
Extended Application Services (SAP HANA XS) table-import feature.

In SAP HANA XS, you create a table-import scenario by setting up an table-import configuration file and one or
more comma-separated value (CSV) files containing the content you want to import into the specified SAP
HANA table. The import-configuration file links the import operation to one or more target tables. The table
definition (for example, in the form of a .hdbdd or .hdbtable file) can either be created separately or be
included in the table-import scenario itself.

To use the SAP HANA XS table-import feature to import data into an SAP HANA table, you need to understand
the following table-import concepts:

● Table-import configuration

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 203
 You define the table-import model in a configuration file that specifies the data fields to import and the
target tables for each data field.

Note
The table-import file must have the .hdbti extension, for example, myTableImport.hdbti.

CSV Data File Constraints

The following constraints apply to the CSV file used as a source for the table-import feature in SAP HANA XS:

● The number of table columns must match the number of CSV columns.
● There must not be any incompatibilities between the data types of the table columns and the data types of
the CSV columns.
● Overlapping data in data files is not supported.
● The target table of the import must not be modified (or appended to) outside of the data-import operation.
If the table is used for storage of application data, this data may be lost during any operation to re-import
or update the data.

Related Information

Table-Import Configuration [page 204]

Table-Import Configuration-File Syntax [page 207]

4.1.8.2 Table-Import Configuration

You can define the elements of a table-import operation in a design-time file; the configuration includes
information about source data and the target table in SAP HANA.

SAP HANA Extended Application Services (SAP HANA XS) enables you to perform data-provisioning
operations that you define in a design-time configuration file. The configuration file is transportable, which
means you can transfer the data-provisioning between SAP HANA systems quickly and easily.

The table-import configuration enables you to specify how data from a comma-separated-value (.csv) file is
imported into a target table in SAP HANA. The configuration specifies the source file containing the data values
to import and the target table in SAP HANA into which the data must be inserted. As further options, you can
specify which field delimiter to use when interpreting data in the source .csv file and if keys must be used to
determine which columns in the target table to insert the imported data into.

Note
If you use multiple table import configurations to import data into a single target table, the keys keyword is
mandatory. This is to avoid problems relating to the overwriting or accidental deletion of existing data.

SAP HANA Developer Guide

204 PUBLIC Setting up the Persistence Model
The following example of a table-import configuration shows how to define a simple import operation which
inserts data from the source files myData.csv and myData2.csv into the table myTable in the schema
mySchema.

import = [
{
table = "myTable";
schema = "mySchema";
file = "sap.ti2.demo:myData.csv";
header = false;
delimField = ";";
keys = [ "GROUP_TYPE" : "BW_CUBE"];
},
{
table = "sap.ti2.demo::myTable";
file = "sap.ti2.demo:myData2.csv";
header = false;
delimField = ";";
keys = [ "GROUP_TYPE" : "BW_CUBE"];
}
];

In the table import configuration, you can specify the target table using either of the following methods:

● Public synonym (“sap.ti2.demo::myTable”)

If you use the public synonym to reference a target table for the import operation, you must use either the
hdbtable or cdstable keyword, for example, hdbtable = "sap.ti2.demo::myTable";
● Schema-qualified catalog name (“mySchema”.“MyTable”
If you use the schema-qualified catalog name to reference a target table for the import operation, you must
use the table keyword in combination with the schema keyword, for example, table = "myTable";
schema = "mySchema";

Note
Both the schema and the target table specified in the table-import operation must already exist. If either the
specified table or the schema does not exist, SAP HANA XS displays an error message during the activation
of the configuration file, for example: Table import target table cannot be found. or Schema
could not be resolved.

You can also use one table-import configuration file to import data from multiple .csv source files. However,
you must specify each import operation in a new code block introduced by the [hdb | cds]table keyword, as
illustrated in the example above.

By default, the table-import operation assumes that data values in the .csv source file are separated by a
comma (,). However, the table-import operation can also interpret files containing data values separated by a
semi-colon (;).

● Comma (,) separated values

,,,BW_CUBE,,40000000,2,40000000,all

● Semi-colon (;) separated values

;;;BW_CUBE;;40000000;3;40000000;all

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 205
 Note
If the activated .hdbti configuration used to import data is subsequently deleted, only the data that was
imported by the deleted .hdbti configuration is dropped from the target table. All other data including any
data imported by other .hdbti configurations remains in the table. If the target CDS entity has no key
(annotated with @nokey) all data that is not part of the CSV file is dropped from the table during each table-
import activation.

You can use the optional keyword keys to specify the key range taken from the source .csv file for import into
the target table. If keys are specified for an import in a table import configuration, multiple imports into same
target table are checked for potential data collisions.

Note
The configuration-file syntax does not support wildcards in the key definition; the full value of a selectable
column value has to be specified.

Security Considerations

In SAP HANA XS, design-time artifacts such as tables (.hdbtable or .hdbdd) and table-import
configurations (.hdbti) are not normally exposed to clients via HTTP. However, design-time artifacts
containing comma-separated values (.csv) could be considered as potential artifacts to expose to users
through HTTP. For this reason, it is essential to protect these exposed .csv artifacts by setting the appropriate
application privileges; the application privileges prevents data leakage, for example, by denying access to data
by users, who are not normally allowed to see all the records in such tables.

Tip
Place all the .csv files used to import content to into tables together in a single package and set the
appropriate (restrictive) application-access permissions for that package, for example, with a
dedicated .xsaccess file.

Related Information

Table-Import Configuration-File Syntax [page 207]

SAP HANA Developer Guide

206 PUBLIC Setting up the Persistence Model
4.1.8.3 Table-Import Configuration-File Syntax

The design-time configuration file used to define a table-import operation requires the use of a specific syntax.
The syntax comprises a series of keyword=value pairs.

If you use the table-import configuration syntax to define the details of the table-import operation, you can use
the keywords illustrated in the following code example. The resulting design-time file must have the .hdbti file
extension, for example, myTableImportCfg.hdbti.

import = [
{
table = "myTable";
schema = "mySchema";
file = "sap.ti2.demo:myData.csv";
header = false;
useHeaderNames = false;
delimField = ";";
delimEnclosing=“\““;
distinguishEmptyFromNull = true;
keys = [ "GROUP_TYPE" : "BW_CUBE", "GROUP_TYPE" : "BW_DSO", "GROUP_TYPE" :
"BW_PSA"];
}
];

table

In the table-import configuration, the table, cdstable, and hdbtable keywords enable you to specify the
name of the target table into which the table-import operation must insert data. The target table you specify in
the table-import configuration can be a runtime table in the catalog or a design-time table definition, for
example, a table defined using either the .hdbtable or the .hdbdd (Core Data Services) syntax.

Note
The target table specified in the table-import configuration must already exist. If the specified table does not
exist, SAP HANA XS displays an error message during the activation of the configuration file, for example:
Table import target table cannot be found.

Use the table keyword in the table-import configuration to specify the name of the target table using the
qualified name for a catalog table.

table = "target_table";
schema = "mySchema";

Note
You must also specify the name of the schema in which the target catalog table resides, for example, using
the schema keyword.

The hdbtable keyword in the table-import configuration enables you to specify the name of a target table using
the public synonym for a design-time table defined with the .hdbtable syntax.

hdbtable = "sap.ti2.demo::target_table";

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 207
The cdstable keyword in the table-import configuration enables you to specify the name of a target table using
the public synonym for a design-time table defined with the CDS-compliant .hdbdd syntax.

cdstable = "sap.ti2.demo::target_table";

Caution
There is no explicit check if the addressed table is created using the .hdbtable or CDS-compliant .hdbdd
syntax.

If the table specified with the cdstable or hdbtable keyword is not defined with the corresponding syntax,
SAP HANA displays an error when you try to activate the artifact, for example,Invalid combination of
table declarations found, you may only use [cdstable | hdbtable | table] .

schema

The following code example shows the syntax required to specify a schema in a table-import configuration.

schema = "TI2_TESTS";

Note
The schema specified in the table-import configuration file must already exist.

If the schema specified in a table-import configuration file does not exist, SAP HANA XS displays an error
message during the activation of the configuration file, for example:

● Schema could not be resolved.

● If you import into a catalog table, please provide schema.

The schema is only required if you use a table's schema-qualified catalog name to reference the target table for
an import operation, for example, table = "myTable"; schema = "mySchema";. The schema is not
required if you use a public synonym to reference a table in a table-import configuration, for example,
hdbtable = "sap.ti2.demo::target_table";.

file

Use the file keyword in the table-import configuration to specify the source file containing the data that the
table-import operation imports into the target table. The source file must be a .csv file with the data values
separated either by a comma (,) or a semi-colon (;). The file definition must also include the full package path
in the SAP HANA repository.

file = "sap.ti2.demo:myData.csv";

SAP HANA Developer Guide

208 PUBLIC Setting up the Persistence Model
header

Use the header keyword in the table-import configuration to indicate if the data contained in the
specified .csv file includes a header line. The header keyword is optional, and the possible values are true or
false.

header = false;

useHeaderNames

Use the useHeaderNames keyword in the table-import configuration to indicate if the data contained in the
first line of the specified .csv file must be interpreted. The useHeaderNames keyword is optional; it is used in
combination with theheader keyword. The useHeaderNames keyword is boolean: possible values are true or
false.

Note
The useHeaderNames keyword only works if header is also set to “true”.

useHeaderNames = false;

The table-import process considers the order of the columns; if the column order specified in the .csv, file
does not match the order used for the columns in the target table, an error occurs on activation.

delimField

Use the delimField keyword in the table-import configuration to specify which character is used to separate
the values in the data to be imported. Currently, the table-import operation supports either the comma (,) or
the semi-colon (;). The following example shows how to specify that values in the .csv source file are
separated by a semi-colon (;).

delimField = ";";

Note
By default, the table-import operation assumes that data values in the .csv source file are separated by a
comma (,). If no delimiter field is specified in the .hdbti table-import configuration file, the default setting
is assumed.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 209
delimEnclosing

Use the delimEnclosing keyword in the table-import configuration to specify a single character that
indicates both the start and end of a set of characters to be interpreted as a single value in the .csv file, for
example “This is all one, single value”. This feature enables you to include in data values in a .CSV file even the
character defined as the field delimiter (in delimField), for example, a comma (,) or a semi-colon (;).

Tip
If the value used to separate the data fields in your .csv file (for example, the comma (,)) is also used inside
the data values themselves ("This, is, a, value"), you must declare and use a delimiter enclosing
character and use it to enclose all data values to be imported.

The following example shows how to use the delimEnclosing keyword to specify the quote (") as the
delimiting character that indicates both the start and the end of a value in the .csv file. Everything enclosed
between the delimEnclosing characters (in this example, “”) is interpreted by the import process as one,
single value.

delimEnclosing=“\““;

Note
Since the hdbti syntax requires us to use the quotes (“”) to specify the delimiting character, and the
delimiting character in this example is, itself, also a quote ("), we need to use the backslash character (\) to
escape the second quote (").

In the following example of values in a .csv file, we assume that delimEnclosing“\““, and
delimField=",". This means that imported values in the .csv file are enclosed in the quote character
("value”) and multiple values are separated by the comma ("value1”,"value 2”). Any commas inside the
quotes are interpreted as a comma and not as a field delimiter.

"Value 1, has a comma","Value 2 has, two, commas","Value3"

You can use other characters as the enclosing delimiter, too, for example, the hash (#). In the following
example, we assume that delimEnclosing="#" and delimField=";". Any semi-colons included inside the
hash characters are interpreted as a semi-colon and not as a field delimiter.

#Value 1; has a semi-colon#;#Value 2 has; two; semi-colons#;#Value3#

distinguishEmptyFromNull

Use the distinguishEmptyFromNull keyword in combination with delimEnclosing to ensure that the
table-import process correctly interprets any empty value in the .CSV file, which is enclosed with the value
defined in the delimEnclosing keyword, for example, as an emtpy space. This ensures that an emtpy space
is imported “as is” into the target table. If the empty space in incorrectly interpreted, it is imported as NULL.

distinguishEmptyFromNull = true;

SAP HANA Developer Guide

210 PUBLIC Setting up the Persistence Model
 Note
The default setting for distinguishEmptyFromNull is false.

If distinguishEmptyFromNull=false is used in combination with delimEnclosing, then an empty value

in the .CSV (with or without quotes “”) is interpreted as NULL.

"Value1",,"",Value2

The table-import process would add the values shown in the example .csv above into the target table as
follows:

Value1 | NULL | NULL | Value2

keys

Use the keys keyword in the table-import configuration to specify the key range to be considered when
importing the data from the .csv source file into the target table.

keys = [ "GROUP_TYPE" : "BW_CUBE", "GROUP_TYPE" : "BW_DSO", "GROUP_TYPE" :

"BW_PSA"];

In the example above, all the lines in the .csv source file where the GROUP_TYPE column value matches one of
the given values (BW_CUBE, BW_DSO, or BW_PSA) are imported into the target table specified in the table-import
configuration.

;;;BW_CUBE;;40000000;3;40000000;slave
;;;BW_DSO;;40000000;3;40000000;slave
;;;BW_PSA;;2000000000;1;2000000000;slave

In the following example, the GROUP_TYPE column is specified as empty(“”).

keys = [ "GROUP_TYPE" : ""];

All the lines in the .csv source file where the GROUP_TYPE column is empty are imported into the target table
specified in the table-import configuration.

;;;;;40000000;2;40000000;all

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 211
4.1.8.4 Table-Import Configuration Error Messages

During the course of the activation of the table-import configuration and the table-import operation itself, SAP
HANA checks for errors and displays the following information in a brief message.

Table-Import Error Messages

Message Number Message Text Message Reason

40200 Invalid combination of table 1. The table keyword is specified in a table-

import configuration that references a ta­
declarations found, you may only
ble defined using the .hdbtable
use [cdstable | hdbtable | table]
(or .hdbdd) syntax.
2. The hdbtable keyword is specified in a ta­
ble-import configuration that references a
table defined using another table-defini-
tion syntax, for example, the .hdbdd syn­
tax.
3. The cdstable keyword is specified in a ta­
ble-import configuration that references a
table defined using another table-defini-
tion syntax, for example, the .hdbtable
syntax.

40201 If you import into a catalog table, 1. You specified a target table with the table
keyword but did not specify a schema with
please provide schema
the schema keyword.

40202 Schema could not be resolved 1. The schema specified with the schema
keyword does not exist or could not be
found (wrong name).
2. The public synonym for an .hdbtable
or .hdbdd (CDS) table definition cannot
be resolved to a catalog table.

40203 Schema resolution error 1. The schema specified with the schema
keyword does not exist or could not be
found (wrong name).
2. The database could not complete the
schema-resolution process for some rea­
son - perhaps unrelated to the table-im­
port configuration (.hdbti), for exam­
ple, an inconsistent database status.

40204 Table import target table cannot be 1. The table specified with the table keyword
does not exist or could not be found
found
(wrong name or wrong schema name).

40210 Table import syntax error 1. The table-import configuration file

(.hdbti) contains one or more syntax
errors.

SAP HANA Developer Guide

212 PUBLIC Setting up the Persistence Model
 Message Number Message Text Message Reason

40211 Table import constraint checks 1. The same key is specified in multiple ta­
ble-import configurations (.hdbti files),
failed
which leads to overlaps in the range of
data to import.
2. If keys are specified for an import in a ta­
ble-import configuration, multiple imports
into the same target table are checked for
potential data collisions

40212 Importing data into table failed 1. Either duplicate keys were written (due to
duplicates in the .CSV source file) or
2. An (unexpected) error occurred on the
SQL level.

40213 CSV table column count mismatch 1. Either the number of columns in the .CSV
record is higher than the number of col­
umns in the table, or
2. The number of columns in the .CSV re­
cord is higher than the number of columns
in its header.

40214 Column type mismatch The csv file does not match the target table for
either of the following reasons:

1. Data are missing for some not-null

columns
2. Some columns specified in the .CSV re­
cord do not exist in the table

40216 Key does not match to table header For some key columns of the table no data are
provided.

4.1.9 Migrate an Entity from HDBTable to CDS (hdbdd)

Migrate a design-time representation of a table from the .hdbtable syntax to the CDS-compliant .hdbdd
syntax while retaining the underlying catalog table.

Prerequisites

● You have created a schema for the CDS catalog objects, for example, MYSCHEMA.
● You have SELECT privileges on the schema so you can see the generated catalog objects.
● You have a design-time definition of the hdbtable entity you want to migrate to CDS.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 213
Context

In this procedure you replace a design-time representation of a database table that was defined using the
hdbtable syntax with a CDS document that describes the same table (entity) with the CDS-compliant hdbdd
syntax. To migrate an hdbtable artifact to CDS, you delete the inactive version of the hdbtable object and
create a new hdbdd artifact with the same name and structure.

You need to define the target CDS entity manually. The name of the entity and the names of the elements can
be reused from the hdbtable definition. The same applies for the element modfifiers, for example, NULL/NOT
NULL, and the default values.

Note
In CDS, there is no way to reproduce the column-comments defined in an hdbtable artifact. You can use
source code comments, for example, '/* */' or '//', however, the comments do not appear in the
catalog table after activation of the new CDS artifact.

Procedure

1. Use CDS syntax to create a duplicate of the table you originally defined using the hdbtable syntax.

Note
The new CDS document must have the same name as the original hdbtable artifact, for example,
Employee.hdbdd and Employee.hdbtable.

The following code shows a simple table Employee.hdbtable that is defined using the hdbtable syntax.
This is the “source” table for the migration. When you have recreated this table in CDS using the .hdbdd
syntax, you can delete the artifact Employee.hdbtable.

table.schemaName = "MYSCHEMA";
table.tableType = COLUMNSTORE;
table.columns = [
{name = "firstname"; sqlType = NVARCHAR; nullable = false; length = 20;},
{name = "lastname"; sqlType = NVARCHAR; nullable = true; length = 20;
defaultValue = "doe";},
{name = "age"; sqlType = INTEGER; nullable = false;},
{name = "salary"; sqlType = DECIMAL; nullable = false; precision = 7;
scale = 2;}
];

The following code shows the same simple table recreated with the CDS-compliant hdbdd syntax. The new
design-time artifact is called Employee.hdbdd and is the “target” for the migration operation. Note that
all column names remain the same.

namespace sap.cds.tutorial;
@Schema:'MYSCHEMA'
@Catalog.tableType:#COLUMN
@nokey
entity Employee {
firstname : String(20) not null;
lastname : String(20) default 'doe';

SAP HANA Developer Guide

214 PUBLIC Setting up the Persistence Model
 age : Integer not null;
salary : Decimal(7,2);
};

2. Activate the source (hdbtable) and target (CDS) artifacts of the migration operation.
To replace the old hdbtable artifact with the new hdbdd (CDS) artifact, you must activate both artifacts
(the deleted hdbtable artifact and the new CDS document) together in a single activation operation.

Tip
In the SAP HANA Web-based Workbench, the default setting is activate on save, however you can
change this behavior to save without activating.

3. Check that the table is in the catalog in the specified schema.

To ensure that the new CDS-defined table is identical to the old (HDBtable-defined) table, check the
contents of the table in the catalog.

4.1.9.1 Migration Guidelines: hdbtable to CDS Entity

Replace an existing hdbtable definition with the equivalent CDS document.

It is possible to migrate your SAP HANA hdbtable definition to a Core Data Services (CDS) entity that has
equally named but differently typed elements. When recreating the new CDS document, you cannot choose an
arbitrary data type; you must follow the guidelines for valid data-type mappings in the SAP HANA SQL data-
type conversion documentation. Since the SAP HANA SQL documentation does not cover CDS data types you
must map the target type names to CDS types manually.

Note
Remember that most of the data-type conversions depend on the data that is present in the catalog table on
the target system.

If you are planning to migrate SAP HANA (hdbtable) tables to CDS entities, bear in mind the following
important points:

● CDS document structure

The new entity (that replaces the old hdbtable definition) must be defined at the top-level of the new CDS
document; it cannot be defined deeper in the CDS document, for example, nested inside a CDS context. If
the table (entity) is not defined as the top-level element in the CDS document, the resulting catalog name
of the entity (on activation) will not match the name of the runtime table that should be taken over by the
new CDS object. Instead, the name of the new table would also include the name of the CDS context in
which it was defined, which could lead to unintended consequences after the migration.
If the top-level element of the target CDS entity is not an entity (for example, a context or a type), the
activation of the CDS document creates the specified artifact (a context or a type) and does not take over
the catalog table defined by the source (hdbtable) definition.
● Structural compatibility
The new CDS document (defined in the hdbdd artifact) must be structurally compatible with the table
definition in the old hdbtable artifact (that is, with the runtime table).
○ Data types

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 215
 All elements of the new CDS entity that have equally named counterparts in the old hdbtable
definition must be convertible with respect to their data type. The implicit conversion rules described
in the SAP HANA SQL documentation apply.
○ Elements/Columns
Elements/columns that exist in the runtime table but are not defined in the CDS entity will be dropped.
Elements/columns that do not exist in the runtime table but are defined in the CDS entity are added to
the runtime table.

Related Information

SAP HANA to CDS Data-Type Mapping [page 216]

SAP HANA SQL Data Type Conversion

4.1.9.2 SAP HANA to CDS Data-Type Mapping

Mapping table for SAP HANA (hdbtable) and Core Data Services (CDS) types.

Although CDS defines its own system of data types, the list of types is roughly equivalent to the data types
available in SAP HANA (hdbtable); the difference between CDS data types and SAP HANA data types is
mostly in the type names. The following table lists the SAP HANA (hdbtable) data types and indicates what
the equivalent type is in CDS.

Mapping SAP HANA and CDS Types

SAP HANA Type (hdbtable) CDS Type (hdbdd)

NVARCHAR String

SHORTTEXT String

NCLOB LargeString

TEXT LargeString

VARBINARY Binary

BLOB LargeBinary

INTEGER Integer

INT Integer

BIGINT Integer64

DECIMAL(p,s) Decimal(p,s)

DECIMAL DecimalFloat

DOUBLE BinaryFloat

DAYDATE LocalDate

DATE LocalDate

SECONDTIME LocalTime

SAP HANA Developer Guide

216 PUBLIC Setting up the Persistence Model
 SAP HANA Type (hdbtable) CDS Type (hdbdd)

TIME LocalTime

SECONDDATE UTCDateTime

LONGDATE UTCTimestamp

TIMESTAMP UTCTimestamp

ALPHANUM hana.ALPHANUM

SMALLINT hana.SMALLINT

TINYINT hana.TINYINT

SMALLDECIMAL hana.SMALLDECIMAL

REAL hana.REAL

VARCHAR hana.VARCHAR

CLOB hana.CLOB

BINARY hana.BINARY

ST_POINT hana.ST_POINT

ST_GEOMETRY hana.ST_GEOMETRY

Related Information

CDS Entity Syntax Options [page 139]

SAP HANA SQL Data Type Conversion

4.2 Creating the Persistence Model with HDBTable

HDBTable is a language syntax that can be used to define a design-time representation of the artifacts that
comprise the persistent data models in SAP HANA.

In SAP HANA Extended Application Services (SAP HANA XS), the persistence model defines the schema,
tables, and views that specify what data to make accessible and how. The persistence model is mapped to the
consumption model that is exposed to client applications and users, so that data can be analyzed and
displayed.

SAP HANA XS enables you to create database schema, tables, views, and sequences as design-time files in the
repository. Repository files can be read by applications that you develop.

Note
All repository files including your view definition can be transported (along with tables, schema, and
sequences) to other SAP HANA systems, for example, in a delivery unit. A delivery unit is the medium SAP
HANA provides to enable you to assemble all your application-related repository artifacts together into an
archive that can be easily exported to other systems.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 217
You can also set up data-provisioning rules and save them as design-time objects so that they can be included
in the delivery unit that you transport between systems.

As part of the process of setting up the basic persistence model for SAP HANA XS, you perform the following
tasks:

Task Description

Create a schema Define a design-time schema and maintain the schema definition in the repository; the transportable
schema has the file extension .hdbschema, for example, MYSCHEMA.hdbschema.

Create a synonym Define a design-time synonym and maintain the synonym definition in the repository; the transporta­
ble synonym has the file extension .hdbsynonym, for example, MySynonym.hdbsynonym.

Create a table Define a design-time table and maintain the table definition in the repository; the transportable table
has the file extension .hdbtable, for example, MYTABLE.hdbtable

Create a reusable Define the structure of a database table in a design-time file in the repository; you can reuse the ta­
table structure ble-structure definition to specify the table type when creating a new table.

Create a view Define a design-time view and maintain the view definition in the repository; the transportable view
has the file extension .hdbview, for example, MYVIEW.hdbview

Create a sequence Define a design-time sequence and maintain the sequence definition in the repository; the transport­
able sequence has the file extension .hdbsequence, for example, MYSEQUENCE.hdbsequence

Import table con­ Define data-provisioning rules that enable you to import data from comma-separated values (CSV)
tent files into SAP HANA tables using the SAP HANA XS table-import feature; the complete configuration
can be included in a delivery unit and transported between SAP HANA systems.

Note
On activation of a repository file, the file suffix, for example, .hdbview, .hdbschema, or .hdbtable, is used
to determine which runtime plug-in to call during the activation process. The plug-in reads the repository file
selected for activation, for example, a table, sees the object descriptions in the file, and creates the
appropriate runtime object.

4.2.1 Create a Schema

A schema defines the container that holds database objects such as tables, views, and stored procedures. You
need a schema to be able to write to the catalog.

Context

To create a database schema as a design-time object, you create a flat file that contains the schema definition.
You save this file with the suffix .hdbschema in the appropriate package for your application in the SAP HANA
repository.

SAP HANA Developer Guide

218 PUBLIC Setting up the Persistence Model
Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the schema definition file.
a. In the package structure, select the package where you want to create the new schema definition file
and from the context menu choose New File .
b. Enter the name of the schema in the File Name field, for example, MYSCHEMA.hdbschema, and choose
Create.
3. Define the schema name.

Add the schema definition by choosing (Insert snippet) in the toolbar and change the schema name to
MYSCHEMA, for example, as shown below:

schema_name="MYSCHEMA";

4. Save the schema file.

The schema is saved and activated in the SAP HANA repository.
5. Assign schema execution authorization to your user.
After activation in the repository, a schema object is only visible in the catalog to the _SYS_REPO user. To
enable other users, for example the schema owner, to view the newly created schema and the objects it
contains, you must grant the user the required SELECT privilege for the schema object.
To grant schema privileges to yourself:
a. Select the schema file.

b. Choose (Assign execution authorization).

You are assigned the requested schema privileges (by default, EXECUTE, SELECT, INSERT, UPDATE,
and DELETE).

Note
Alternatively open the catalog and run a command in the following form in the SQL editor to grant
specific schema privileges:

call
_SYS_REPO.GRANT_SCHEMA_PRIVILEGE_ON_ACTIVATED_CONTENT('select','<SCHEMANAME>
','<username>');

Related Information

Schema [page 220]

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 219
4.2.1.1 Schema

Relational databases contain a catalog that describes the various elements in the system. The catalog divides
the database into sub-databases known as schema. A database schema enables you to logically group
together objects such as tables, views, and stored procedures. Without a defined schema, you cannot write to
the catalog.

SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database schema as a
transportable design-time file in the repository. Repository files can be read by applications that you develop.

If your application refers to the repository (design-time) version of a schema rather than the runtime version in
the catalog, for example, by using the explicit path to the repository file (with suffix), any changes to the
repository version of the file are visible as soon as they are committed to the repository. There is no need to
wait for the repository to activate a runtime version of the schema.

If you want to define a transportable schema using the design-time hdbschema specifications, use the
configuration schema illustrated in the following example:

string schema_name

The following example shows the contents of a valid transportable schema-definition file for a schema called
MYSCHEMA:

schema_name=”MYSCHEMA”;

The schema is stored in the repository with the schema name MYSCHEMA as the file name and the
suffix .hdbschema, for example, MYSCHEMA.hdbschema.

Note
A schema generated from an .hdbschema artifact can also be used in the context of Core Data Services
(CDS).

Schema Activation

If you want to create a schema definition as a design-time object, you must create the schema as a flat file. You
save the file containing the schema definition with the suffix .hdbschema in the appropriate package for your
application in the SAP HANA repository. You can activate the design-time objects at any point in time.

Note
On activation of a repository file, the file suffix, for example, .hdbschema, is used to determine which
runtime plugin to call during the activation process. The plug-in reads the repository file selected for
activation, parses the object descriptions in the file, and creates the appropriate runtime objects.

If you activate a schema-definition object in SAP HANA, the activation process checks if a schema with the
same name already exists in the SAP HANA repository. If a schema with the specified name does not exist, the
repository creates a schema with the specified name and makes _SYS_REPO the owner of the new schema.

SAP HANA Developer Guide

220 PUBLIC Setting up the Persistence Model
 Note
The schema cannot be dropped even if the deletion of a schema object is activated.

If you define a schema in SAP HANA XS, note the following important points regarding the schema name:

● Name mapping
The schema name must be identical to the name of the corresponding repository object.
● Naming conventions
The schema name must adhere to the SAP HANA rules for database identifiers. In addition, a schema
name must not start with the letters SAP*; the SAP* namespace is reserved for schemas used by SAP
products and applications.
● Name usage
The Data Definition Language (DDL) rendered by the repository contains the schema name as a delimited
identifier.

Related Information

Create a Schema [page 218]

4.2.2 Tutorial: Create a Table

In this tutorial, you use the SAP HANA Web-based Development Workbench Editor to create a table as a
design-time file in the repository using the hdbtable syntax. In the catalog, you view the table definition and
insert data into the table.

Prerequisites

You have the privileges granted by the sap.hana.ide.roles::EditorDeveloper and

sap.hana.ide.roles::CatalogDeveloper roles; these roles are included in the parent role
sap.hana.ide.roles::Developer.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create a new application.
a. From the context menu of the Content folder, choose Create Application.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 221
 b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter a package name, for example, demo.tables, and choose Create.
d. In the context menu of the demo.tables package, choose Activate All.
3. Create a schema.

a. Select the newly created demo.tables package and from the context menu choose New File .
b. Enter the name of the schema in the File Name field, for example, myschema.hdbschema, and choose
Create.

c. Add the schema definition by choosing (Insert snippet) in the toolbar and change the schema name
to MYSCHEMA, for example, schema_name = “MYSCHEMA”;.

d. Save the file and choose (Assign execution authorization) in the toolbar.
4. Create the new table definition.

a. Select the demo.tables package and from the context menu choose New File .
b. Enter the name of the table in the File Name field, for example, mytable.hdbtable, and choose
Create.

c. Choose (Insert snippet) in the toolbar to insert the following table definition code. Remember to
change the schema name in the inserted code to MYSCHEMA.

table.schemaName = "MYSCHEMA";
table.tableType = COLUMNSTORE;
table.columns = [
{name = "KEY1"; sqlType = TINYINT; nullable = false;},
{name = "FIELD1"; sqlType = DOUBLE; nullable = false;},
{name = "FIELD2"; sqlType = DOUBLE; nullable = false;},
{name = "FIELD3"; sqlType = NVARCHAR; length = 10; nullable = false;}
];
table.primaryKey.pkcolumns = ["KEY1"];

d. Save the file.

5. In the catalog, check the table definition.

a. To open the catalog, choose (Navigation Links) Catalog .

b. Select the mytable file under the MYSCHEMA Tables node.
The table definition is displayed, as shown in the example below:

6. Add entries to the table.

a. Choose Open Content.
The data preview appears, displaying an empty table.

b. Choose (Insert).
c. In the new row, enter some test data and save your entries, as shown in the example below:

SAP HANA Developer Guide

222 PUBLIC Setting up the Persistence Model
7. Generate a SQL select statement on the table.
In the context menu of the mytable file, choose Generate Select.
The table rows you just created are displayed in the SQL result view.

Related Information

Tables [page 223]

Table Configuration Syntax [page 225]

4.2.2.1 Tables

In the SAP HANA database, as in other relational databases, a table is a set of data elements that are organized
using columns and rows. A database table has a specified number of columns, defined at the time of table
creation, but can have any number of rows. Database tables also typically have meta-data associated with
them; the meta-data might include constraints on the table or on the values within particular columns.

SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database table as a design-
time file in the repository. All repository files including your table definition can be transported to other SAP
HANA systems, for example, in a delivery unit.

Note
A delivery unit is the medium SAP HANA provides to enable you to assemble all your application-related
repository artifacts together into an archive that can be easily exported to other systems.

If your application is configured to use the design-time version of a database table in the repository rather than
the runtime version in the catalog, any changes to the repository version of the table are visible as soon as they
are committed to the repository. There is no need to wait for the repository to activate a runtime version of the
table.

If you want to define a transportable table using the design-time .hdbtable specifications, use the
configuration schema illustrated in the following example:

struct TableDefinition {
string SchemaName;
optional bool temporary;
optional TableType tableType;
optional bool public;
optional TableLoggingType loggingType;
list<ColumnDefinition> columns;
optional list<IndexDefinition> indexes;
optional PrimaryKeyDefinition primaryKey;
optional string description

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 223
 };

The following code illustrates a simple example of a design-time table definition:

table.schemaName = "MYSCHEMA";
table.tableType = COLUMNSTORE;
table.columns = [
{name = "Col1"; sqlType = VARCHAR; nullable = false; length = 20; comment =
"dummy comment";},
{name = "Col2"; sqlType = INTEGER; nullable = false;},
{name = "Col3"; sqlType = NVARCHAR; nullable = true; length = 20;
defaultValue = "Defaultvalue";},
{name = "Col4"; sqlType = DECIMAL; nullable = false; precision = 2; scale =
3;}];
table.indexes = [
{name = "MYINDEX1"; unique = true; order = DSC; indexColumns = ["Col2"];},
{name = "MYINDEX2"; unique = true; order = DSC; indexColumns = ["Col1",
"Col4"];}];
table.primaryKey.pkcolumns = ["Col1", "Col2"];

If you want to create a database table as a repository file, you must create the table as a flat file and save the
file containing the table dimensions with the suffix .hdbtable, for example, MYTABLE.hdbtable. The new file
is located in the package hierarchy you establish in the SAP HANA repository. You can activate the repository
files at any point in time.

Note
On activation of a repository file, the file suffix, for example, .hdbtable, is used to determine which runtime
plug-in to call during the activation process. The plug-in reads the repository file selected for activation, in
this case a table, parses the object descriptions in the file, and creates the appropriate runtime objects.

Security Considerations

It is important to bear in mind that an incorrectly defined table can lead to security-related problems. If the
content of the table you create is used to determine the behavior of the application, for example, whether data
is displayed depends on the content of a certain cell, any modification of the table content could help an
attacker to obtain elevated privileges. Although you can use authorization settings to restrict the disclosure of
information, data-modification issues need to be handled as follows:

● Make sure you specify the field type and define a maximum length for the field
● Avoid using generic types such as VARCHAR or BLOB.
● Keep the field length as short as possible; it is much more difficult to inject shell-code into a string that is 5
characters long than one that an can contain up to 255 characters.

Related Information

Table Configuration Syntax [page 225]

SAP HANA Developer Guide

224 PUBLIC Setting up the Persistence Model
4.2.2.2 Table Configuration Syntax

SAP HANA Extended Application Services (SAP HANA XS) enables you to use the hdbtable syntax to create a
database table as a design-time file in the repository. The design-time artifact that contains the table definition
must adhere to the .hdbtable syntax specified below.

Table Definition

The following code illustrates a simple example of a design-time table definition using the .hdbtable syntax.

Note
Keywords are case-sensitive, for example, tableType and loggingType, and the schema referenced in the
table definition, for example, MYSCHEMA, must already exist.

table.schemaName = "MYSCHEMA";
table.temporary = true;
table.tableType = COLUMNSTORE;
table.loggingType = NOLOGGING;
table.columns = [
{name = "Col1"; sqlType = VARCHAR; nullable = false; length = 20; comment =
"dummy comment";},
{name = "Col2"; sqlType = INTEGER; nullable = false;},
{name = "Col3"; sqlType = NVARCHAR; nullable = true; length = 20;
defaultValue = "Defaultvalue";},
{name = "Col4"; sqlType = DECIMAL; nullable = false; precision = 2; scale =
3;}];
table.indexes = [
{name = "MYINDEX1"; unique = true; order = DSC; indexColumns = ["Col2"];},
{name = "MYINDEX2"; unique = true; order = DSC; indexType = B_TREE;
indexColumns = ["Col1", "Col4"];}];
table.primaryKey.pkcolumns = ["Col1", "Col2"];

Table-Definition Configuration Schema

The following example shows the configuration schema for tables defined using the .hdbtable syntax. Each
of the entries in the table-definition configuration schema is explained in more detail in a dedicated section
below:

struct TableDefinition {
string SchemaName;
optional bool temporary;
optional TableType tableType;
optional bool public;
optional TableLoggingType loggingType;
list<ColumnDefinition> columns;
optional list<IndexDefinition> indexes;
optional PrimaryKeyDefinition primaryKey;
optional string description
};

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 225
Schema Name

To use the .hdbtable syntax to specify the name of the schema that contains the table you are defining, use
the schemaName keyword. In the table definition, the schemaName keyword must adhere to the syntax shown
in the following example.

table.schemaName = "MYSCHEMA";

Temporary

To use the .hdbtable syntax to specify that the table you define is temporary, use the boolean temporary
keyword. Since data in a temporary table is session-specific, only the owner session of the temporary table is
allowed to INSERT/READ/TRUNCATE the data. Temporary tables exist for the duration of the session, and data
from the local temporary table is automatically dropped when the session is terminated. In the table definition,
the temporary keyword must adhere to the syntax shown in the following example.

table.temporary = true;

Table Type

To specify the table type using the .hdbtable syntax, use the tableType keyword. In the table definition, the
TableType keyword must adhere to the syntax shown in the following example.

table.tableType = [COLUMNSTORE | ROWSTORE];

The following configuration schema illustrates the parameters you can specify with the tableType keyword:

● COLUMNSTORE
Column-oriented storage, where entries of a column are stored in contiguous memory locations. SAP
HANA is particularly optimized for column-order storage.
● ROWSTORE
Row-oriented storage, where data is stored in a table as a sequence of records

Table Logging Type

To enable logging in a table definition using the .hdbtable syntax, use the tableLoggingType keyword. In the
table definition, the tableLoggingType keyword must adhere to the syntax shown in the following example.

table.tableLoggingType = [LOGGING | NOLOGGING];

SAP HANA Developer Guide

226 PUBLIC Setting up the Persistence Model
Table Column Definition

To define the column structure and type in a table definition using the .hdbtable syntax, use the columns
keyword. In the table definition, the columns keyword must adhere to the syntax shown in the following
example.

table.columns = [
{name = "Col1"; sqlType = VARCHAR; nullable = false; length = 20; comment =
"dummy comment";},
{name = "Col2"; sqlType = INTEGER; nullable = false;},
{name = "Col3"; sqlType = NVARCHAR; nullable = true; length = 20;
defaultValue = "Defaultvalue";},
{name = "Col4"; sqlType = DECIMAL; nullable = false; precision = 2; scale =
3;}];

The following configuration schema illustrates the parameters you can specify with the columns keyword:

struct ColumnDefinition {
string name;
SqlDataType sqlType;
optional bool nullable;
optional bool unique;
optional int32 length;
optional int32 scale;
optional int32 precision;
optional string defaultValue;
optional string comment;
};

SQL Data Type

To define the SQL data type for a column in a table using the .hdbtable syntax, use the sqlType keyword. In
the table definition, the sqlType keyword must adhere to the syntax shown in the following example.

table.columns = [
{name = "Col1"; sqlType = VARCHAR; nullable = false; length = 20; comment =
"dummy comment";},
...
];

The following configuration schema illustrates the data types you can specify with the sqlType keyword:

enum SqlDataType {
DATE; TIME; TIMESTAMP; SECONDDATE; INTEGER; TINYINT;
SMALLINT; BIGINT; REAL; DOUBLE; FLOAT; SMALLDECIMAL;
DECIMAL; VARCHAR; NVARCHAR; CHAR; NCHAR;CLOB; NCLOB;
ALPHANUM; TEXT; SHORTTEXT; BLOB; VARBINARY;
};

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 227
Primary Key Definition

To define the primary key for the specified table using the .hdbtable syntax, use the primaryKey and
pkcolumns keywords. In the table definition, the primaryKey and pkcolumns keywords must adhere to the
syntax shown in the following example.

table.primaryKey.pkcolumns = ["Col1", "Col2"];

The following configuration schema illustrates the parameters you can specify with the primaryKey keyword:

struct PrimaryKeyDefinition {
list<string> pkcolumns;
optional IndexType indexType;
};

Table Index Definition

To define the index for the specified table using the .hdbtable syntax, use the indexes keyword. In the table
definition, the indexes keyword must adhere to the syntax shown in the following example.

table.indexes = [
{name = "MYINDEX1"; unique = true; order = DSC; indexColumns = ["Col2"];},
{name = "MYINDEX2"; unique = true; order = DSC; indexColumns = ["Col1",
"Col4"];}];

You can also use the optional parameter indexType to define the type of index, for example, B_TREE or
CPB_TREE, as described in Table Index Type [page 228].

Table Index Type

To define the index type for the specified table using the .hdbtable syntax, use the indexType keyword. In the
table definition, the indexType keyword must adhere to the syntax shown in the following example.

indexType = [B_TREE | CPB_TREE];

B_TREE specifies an index tree of type B+, which maintains sorted data that performs the insertion, deletion,
and search of records. CPB_TREE stands for “Compressed Prefix B_TREE” and specifies an index tree of type
CPB+, which is based on pkB-tree. CPB_TREE is a very small index that uses a “partial key”, that is; a key that
is only part of a full key in index nodes.

Note
If neither the B_TREE nor the CPB_TREE type is specified in the table-definition file, SAP HANA chooses the
appropriate index type based on the column data type, as follows:

● CPB_TREE
Character string types, binary string types, decimal types, when the constraint is a composite key or a
non-unique constraint

SAP HANA Developer Guide

228 PUBLIC Setting up the Persistence Model
 ● B_TREE
All column data types other than those specified for CPB_TREE

Table Index Order

To define the order of the table index using the .hdbtable syntax, use the order keyword. Insert the order with
the desired value (for examaple, ascending or descending) in the index type definition; the order keyword must
adhere to the syntax shown in the following example.

order = [ASC | DSC];

You can choose to filter the contents of the table index either in ascending (ASC) or descending (DSC) order.

Complete Table-Definition Configuration Schema

The following example shows the complete configuration schema for tables defined using the .hdbtable
syntax.

enum TableType {
COLUMNSTORE; ROWSTORE;
};
enum TableLoggingType {
LOGGING; NOLOGGING;
};
enum IndexType {
B_TREE; CPB_TREE;
};
enum Order {
ASC; DSC;
};
enum SqlDataType {
DATE; TIME; TIMESTAMP; SECONDDATE;
INTEGER; TINYINT; SMALLINT; BIGINT;
REAL; DOUBLE; FLOAT; SMALLDECIMAL; DECIMAL;
VARCHAR; NVARCHAR; CHAR; NCHAR; CLOB; NCLOB;
ALPHANUM; TEXT; SHORTTEXT; BLOB; VARBINARY;
};
struct PrimaryKeyDefinition {
list<string> pkcolumns;
optional IndexType indexType;
};
struct IndexDefinition {
string name;
bool unique;
optional Order order;
optional IndexType indexType;
list<string> indexColumns;
};
struct ColumnDefinition {
string name;
SqlDataType sqlType;
optional bool nullable;
optional bool unique;
optional int32 length;
optional int32 scale;

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 229
 optional int32 precision;
optional string defaultValue;
optional string comment;
};
struct TableDefinition {
string schemaName;
optional bool temporary;
optional TableType tableType;
optional bool public;
optional TableLoggingType loggingType;
list<ColumnDefinition> columns;
optional list<IndexDefinition> indexes;
optional PrimaryKeyDefinition primaryKey;
optional string description;
};
TableDefinition table;

Related Information

Tables [page 223]

4.2.3 Create a Reusable Table Structure

SAP HANA Extended Application Services (SAP HANA XS) enables you to define the structure of a database
table in a design-time file in the repository. You can reuse the table-structure definition to specify the table type
when creating a new table.

Prerequisites

You have created a schema definition, for example, MYSCHEMA.hdbschema.

Context

Table-structure definition files are stored in the SAP HANA repository with the .hdbstructure file extension,
for example, TableStructure.hdbstructure. The primary use case for a design-time representation of a
table structure is creating reusable type definitions for procedure interfaces.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor

SAP HANA Developer Guide

230 PUBLIC Setting up the Persistence Model
2. Create a package to hold the table-structure definition file.
a. In the package structure, select the package where you want to create the new subpackage called
Structures, and from the context menu choose New Package .
b. Enter the name of the package in the Package Name field, for example, Structures, and choose
Create.
3. Create the table-structure definition file.
a. In the package structure, select the Structures package you created in the previous step and from
the context menu choose New File .
b. Enter a name for the new table structure in the File Name field, for example,
TableStructure.hdbstructure (remember to add the .hdbstructure file extension), and
choose Create.
4. Define the table structure.
Select the table structure file you created in the previous step, for example,
TableStructure.hdbstructure, and add the table-structure code to the file, as shown in the example
below:

table.schemaName = "MYSCHEMA";
table.columns = [
{name = "Col1"; sqlType = VARCHAR; nullable = false; length = 20; comment
= "dummy comment";},
{name = "Col2"; sqlType = INTEGER; nullable = false;},
{name = "Col3"; sqlType = NVARCHAR; nullable = true; length = 20;
defaultValue = "Defaultvalue";},
{name = "Col4"; sqlType = DECIMAL; nullable = false; precision = 12;
scale = 3;}];
table.primaryKey.pkcolumns = ["Col1", "Col2"];

5. Save the table-structure definition file.

The table structure is saved and activated in the SAP HANA repository.
6. Check that the new table-structure object Structures::TableStructure has been added to the
catalog.
Table structures are created in the Table Types folder in the catalog:
a. Open the catalog.
b. Navigate to the catalog location where you created the new table structure:
Catalog <MYSCHEMA> Procedures Table Types
c. Select the new table structure Structures::TableStructure to display its definition.
d. Check that the entry in the Type field is Table Type.

Results

You have created a new table structure in SAP HANA, which can now be used as a basis for creating new tables.
In the example below, the SQL command CREATE TABLE is used with the like operator to create a new table
in this manner:

CREATE TABLE "MySchema"."MyTypeTable" like

"MySchema"."Structures::TableStructure"

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 231
4.2.3.1 Reusable Table Structures

A table-structure definition is a template that you can reuse as a basis for creating new tables of the same type
and structure. You can reference the table structure in an SQL statement (CREATE TABLE [...] like
[...]) or an SQLScript procedure.

SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database table structure (or
type) as a design-time file in the repository. All repository files including your table-structure definition can be
transported to other SAP HANA systems, for example, in a delivery unit. The primary use case for a design-
time representation of a table structure is creating reusable table-type definitions for procedure interfaces.
However, you an also use table-type definitions in table user-defined fuctions (UDF).

If you want to define a design-time representation of a table structure with the .hdbstructure specifications,
use the configuration schema illustrated in the following example:

struct TableDefinition {
string SchemaName;
optional bool public;
list<ColumnDefinition> columns;
optional PrimaryKeyDefinition primaryKey;
};

Note
The .hdbstructure syntax is a subset of the syntax used in .hdbtable. In a table structure definition,
you cannot specify the table type (for example, COLUMN/ROW), define the index, or enable logging.

The following code illustrates a simple example of a design-time table-structure definition:

table.schemaName = "MYSCHEMA";
table.columns = [
{name = "Col1"; sqlType = VARCHAR; nullable = false; length = 20; comment =
"dummy comment";},
{name = "Col2"; sqlType = INTEGER; nullable = false;},
{name = "Col3"; sqlType = NVARCHAR; nullable = true; length = 20;
defaultValue = "Defaultvalue";},
{name = "Col4"; sqlType = DECIMAL; nullable = false; precision = 2; scale =
3;}];
table.primaryKey.pkcolumns = ["Col1", "Col2"];

If you want to create a database table structure as a repository file, you must create the table structure as a flat
file and save the file containing the structure definition with the .hdbstructure file extension, for example,
TableStructure.hdbstructure. The new file is located in the package hierarchy you establish in the SAP
HANA repository. You can activate the repository files at any point in time.

Note
On activation of a repository file, the file suffix is used to determine which runtime plug-in to call during the
activation process. The plug-in reads the repository file selected for activation, in this case a table structure
element with the file extension .hdbstructure, parses the object descriptions in the file, and creates the
appropriate runtime objects.

SAP HANA Developer Guide

232 PUBLIC Setting up the Persistence Model
You can use the SQL command CREATE TABLE to create a new table based on the table structure, for example,
with the like operator, as illustrated in the following example:

CREATE TABLE "MySchema"."MyTypeTable" like

"MySchema"."Structures::TableStructure"

Related Information

Table Configuration Syntax [page 225]

Create a Reusable Table Structure [page 230]

4.2.4 Create an SQL View

A view is a virtual table based on the dynamic results returned in response to an SQL statement. SAP HANA
Extended Application Services (SAP HANA XS) enables you to create a database view as a design-time file in
the repository.

Prerequisites

You have created a schema definition, for example, MYSCHEMA.hdbschema.

Context

An SQL view contains rows and columns, just like a real database table; the fields in an SQL view are fields from
one or more real tables in the database. You can add SQL functions, for example, WHERE or JOIN statements,
to a view and present the resulting data as if it were coming from one, single table.

To create an SQL view as a design-time object, you create a flat file that contains the view definition. You save
this file with the suffix .hdbview, for example, MYVIEW.hdbview, in the appropriate package for your
application in the SAP HANA repository.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the view definition file.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 233
 a. In the package structure, select the package where you want to create the new view definition file and
from the context menu choose New File .
b. Enter the name of the view in the File Name field, for example, MYVIEW.hdbview, and choose Create.
3. Define the view.
Add the view definition code to the file, as shown in the example below, replacing object names and paths
to suit your requirements.

schema="MYSCHEMA";
query="SELECT T1.\"Column2\" FROM \"MYSCHEMA\".
\"acme.com.test.views::MY_VIEW1\" AS T1 LEFT JOIN \"MYSCHEMA\".
\"acme.com.test.views::MY_VIEW2\" AS T2 ON T1.\"Column1\" = T2.\"Column1\"";
depends_on=["acme.com.test.views::MY_VIEW1", "acme.com.test.views::MY_VIEW2"];

In an SQL view defined using the .hdbview syntax, any dependency to another table or view must be
declared explicitly, for example, with the depends_on keyword. The target view or table specified in the
depends_on keyword must also be mentioned in the SELECT query that defines the SQL view. If one of
more of the tables or views specified in the dependency does not exist, the activation of the object in the
repository fails.

If you want to assign names to the columns in a view, use the following syntax in the SQL query. In the
example below, the following names are specified for the columns defined in the view:
○ idea_id
○ identity_id
○ role_id

schema = "MYSCHEMA";
query = "SELECT role_join.idea_id AS idea_id, ident.member_id AS identity_id,
role_join.role_id AS role_id
FROM \"acme.com.odin.db.iam::t_identity_group_member_transitive\"
AS ident
INNER JOIN \"acme.com.odin.db.idea::t_idea_identity_role\" AS
role_join
ON role_join.identity_id = ident.group_id UNION DISTINCT
SELECT idea_id, identity_id, role_id
FROM \"acme.com.odin.db.idea::t_idea_identity_role\"
WITH read only";

4. Save the SQL view-definition file.

The view is saved and activated in the SAP HANA repository.

4.2.4.1 SQL Views

In SQL, a view is a virtual table based on the dynamic results returned in response to an SQL statement. Every
time a user queries an SQL view, the database uses the view's SQL statement to recreate the data specified in
the SQL view. The data displayed in an SQL view can be extracted from one or more database tables.

An SQL view contains rows and columns, just like a real database table; the fields in an SQL view are fields from
one or more real tables in the database. You can add SQL functions, for example, WHERE or JOIN statements,
to a view and present the resulting data as if it were coming from one, single table.

SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database view as a design-
time file in the repository. Repository files can be read by applications that you develop. In addition, all

SAP HANA Developer Guide

234 PUBLIC Setting up the Persistence Model
repository files including your view definition can be transported to other SAP HANA systems, for example, in a
delivery unit.

If your application refers to the design-time version of a view from the repository rather than the runtime
version in the catalog, for example, by using the explicit path to the repository file (with suffix), any changes to
the repository version of the file are visible as soon as they are committed to the repository. There is no need to
wait for the repository to activate a runtime version of the view.

The following example shows the contents of a valid transportable view-definition file for a view called MYVIEW:

schema="MYSCHEMA";
query="SELECT T1.\"Column2\" FROM \"MYSCHEMA\".\"acme.com.test.views::MY_VIEW1\"
AS T1 LEFT JOIN \"MYSCHEMA\".\"acme.com.test.views::MY_VIEW2\" AS T2 ON
T1.\"Column1\" = T2.\"Column1\"";
depends_on=["acme.com.test.views::MY_VIEW1", "acme.com.test.views::MY_VIEW2"];

If you want to create a view definition as a design-time object, you must create the view as a flat file and save
the file containing the view definition with the suffix .hdbview, for example, MYVIEW.hdbview in the
appropriate package in the package hierarchy established for your application in the SAP HANA repository. You
can activate the design-time object at any point in time.

Tip
On activation of a repository file, the file suffix (for example, .hdbview) is used to determine which runtime
plugin to call during the activation process. The plug-in reads the repository file selected for activation,
parses the object descriptions in the file, and creates the appropriate runtime objects.

In an SQL view defined using the .hdbview syntax, any dependency to another table or view must be declared
explicitly, for example, with the depends_on keyword. The target view or table specified in the depends_on
keyword must also be mentioned in the SELECT query that defines the SQL view. If one of more of the tables or
views specified in the dependency does not exist, the activation of the object in the repository fails.

Note
On initial activation of the SQL view, no check is performed to establish the existence of the target view (or
table) in the depends_on dependency; such a check is only made on reactivation of the SQL view.

Column Names in a View

If you want to assign names to the columns in a view, use the SQL query in the .hdbview file. In this example of
design-time view definition, the following names are specified for columns defined in the view:

● idea_id
● identity_id
● role_id

schema = "MYSCHEMA";
query = "SELECT role_join.idea_id AS idea_id, ident.member_id AS identity_id,
role_join.role_id AS role_id
FROM \"acme.com.odin.db.iam::t_identity_group_member_transitive\" AS
ident

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 235
 INNER JOIN \"acme.com.odin.db.idea::t_idea_identity_role\" AS
role_join
ON role_join.identity_id = ident.group_id UNION DISTINCT
SELECT idea_id, identity_id, role_id
FROM \"acme.com.odin.db.idea::t_idea_identity_role\"
WITH read only";

4.2.4.2 SQL View Configuration Syntax

SAP HANA Extended Application Services (SAP HANA XS) enables you to use the hdbview syntax to create an
SQL view as a design-time file in the repository. The design-time artifact that contains the SQL view definition
must adhere to the .hdbview syntax specified below.

SQL View Definition

The following code illustrates a simple example of a design-time definition of an SQL view using the .hdbview
syntax.

Note
Keywords are case-sensitive, for example, schema and query, and the schema referenced in the table
definition, for example, MYSCHEMA, must already exist.

schema="MYSCHEMA";
public=false
query="SELECT T1.\"Column2\" FROM \"MYSCHEMA\".
\"acme.com.test.tables::MY_TABLE1\" AS T1 LEFT JOIN \"MYSCHEMA\".
\"acme.com.test.views::MY_VIEW1\" AS T2 ON T1.\"Column1\" = T2.\"Column1\"";
depends_on= "acme.com.test.tables::MY_TABLE1","acme.com.test.views::MY_VIEW1";

SQL View Configuration Schema

The following example shows the configuration schema for an SQL view that you define using the .hdbview
syntax. Each of the entries in the view-definition configuration schema is explained in more detail in a
dedicated section below:

string schema;
string query;
bool public(default=true);
optional list<string> depends_on_table;
optional list<string> depends_on_view;

SAP HANA Developer Guide

236 PUBLIC Setting up the Persistence Model
Schema Name

To use the .hdbview syntax to specify the name of the schema that contains the SQL view you are defining,
use the schema keyword. In the SQL view definition, the schema keyword must adhere to the syntax shown in
the following example.

schema= "MYSCHEMA";

query

To use the .hdbview syntax to specify the query that creates the SQL view you are defining, use the query
keyword. In the SQL view definition, the query keyword must adhere to the syntax shown in the following
example.

query="SELECT * FROM \"<MY_SCHEMA_NAME>\".

\"<repository.package.path>::<MY_TABLE_NAME>\"";

For example:

query="SELECT * FROM \"MY_SCHEMA\".\"com.test.tables::02_HDB_DEPARTMENT_VIEW\"";

public

To use the .hdbview syntax to specify whether or not the SQL view you are defining is publicly available, use
the boolean keyword public. In the SQL view definition, the public keyword must adhere to the syntax
shown in the following example.

public=[false|true];

For example:

public=false

Note
The default value for the public keyword is true.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 237
Depends on

In an SQL view defined using the .hdbview syntax, the optional keyword depends_on enables you to define a
dependency to one or more tables or views. In the .hdbview definition, the depends_on keyword must adhere
to the syntax shown in the following example.

depends_on=
["<repository.package.path>::<MY_TABLE_NAME1>","<repository.package.path>::<MY_VI
EW_NAME1>"];

Note
The depends_on keyword replaces and extends the keywords depends_on_table and
depends_on_view.

For example, to specify multiple tables and views with the depends_on keyword, use a comma-separated list
enclosed in square brackets [].

depends_on= ["acme.com.test.tables::MY_TABLE1","acme.com.test.views::MY_VIEW1"];

The target table or view specified in the depends_on keyword must be mentioned in the SELECT query that
defines the SQL view. On initial activation of the SQL view, no check is performed to establish the existence of
the target tables or views specified in the dependency; such a check is only made during reactivation of the
SQL view. If one or more of the target tables or views specified in the dependency does not exist, the re-
activation of the SQL view object in the repository fails.

4.2.5 Create a Sequence

A database sequence generates an automatically incremented list of unique numeric values according to the
rules defined in the sequence specification. The numbers generated by a sequence can be used by
applications, for example, to identify the rows and columns of a table.

Prerequisites

You have created a schema definition, for example, MYSCHEMA.hdbschema.

Context

A sequence specification allows you to set the options that control the start and end point of the sequence, the
size of the increment, and the minimum and maximum values allowed. You can also specify if the sequence
should recycle when it reaches the maximum value specified. You create a sequence definition in a file using
the hdbsequence syntax.

SAP HANA Developer Guide

238 PUBLIC Setting up the Persistence Model
Sequences are not associated with tables; they are referenced by applications, which can use CURRVAL in an
SQL statement to get the current value generated by a sequence and NEXTVAL to generate the next value in
the defined sequence. The relationship between sequences and tables is controlled by the application.
Sequences allow applications to generate unique, primary key values, for example, to identify the rows and
columns of a table, and to coordinate keys across multiple rows or tables.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the sequence definition file.
a. In the package structure, select the package where you want to create the new sequence definition file
and from the context menu choose New File .
b. Enter the name of the sequence in the File Name field and choose Create. Note that sequence
definition files require the file extension .hdbsequence, for example, MySequence.hdbsequence.
3. Define the sequence properties.
Add the sequence code to the file, as shown in the example below:

schema= "MYSCHEMA";
start_with= 10;
maxvalue= 30;
nomaxvalue=false;
minvalue= 1;
nominvalue=true;
cycles= false;
reset_by= "SELECT T1.\"Column2\" FROM \"MYSCHEMA\".
\"com.acme.test.tables::MY_TABLE1\" AS T1 LEFT JOIN \"MYSCHEMA\".
\"com.acme.test.tables::MY_TABLE2\" AS T2 ON T1.\"Column1\" = T2.\"Column1\"";
depends_on=["com.acme.test.tables::MY_TABLE1",
"com.acme.test.tables::MY_TABLE2"];

Note that in this example no increment value is defined, so the default value of 1 (ascend by 1) is assumed.
To set a descending sequence of 1, set the increment_by value to -1.

Note
It is important to bear in mind that incorrectly defined sequences can lead to security-related problems.
For example, if the sequencing process becomes corrupted, it can result in data overwrite. This can
happen if the index has a maximum value which rolls-over, or if a defined reset condition is triggered
unexpectedly. A roll-over can be achieved by an attacker forcing data to be inserted by flooding the
system with requests. Overwriting log tables is a known practice for deleting traces. To prevent
unexpected data overwrite, use the following settings:
○ cycles= false
○ Avoid using the reset_by feature

4. Save the sequence-definition file.

The sequence is saved and activated in the SAP HANA repository.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 239
Related Information

Sequence Configuration Syntax [page 242]

4.2.5.1 Sequences

A sequence is a database object that generates an automatically incremented list of numeric values according
to the rules defined in the sequence specification. The sequence of numeric values is generated in an
ascending or descending order at a defined increment interval, and the numbers generated by a sequence can
be used by applications, for example, to identify the rows and columns of a table.

Sequences are not associated with tables; they are used by applications, which can use CURRVAL in a SQL
statement to get the current value generated by a sequence and NEXTVAL to generate the next value in the
defined sequence. Sequences provide an easy way to generate the unique values that applications use, for
example, to identify a table row or a field. In the sequence specification, you can set options that control the
start and end point of the sequence, the size of the increment size, or the minimum and maximum allowed
value. You can also specify if the sequence should recycle when it reaches the maximum value specified. The
relationship between sequences and tables is controlled by the application. Applications can reference a
sequence object and coordinate the values across multiple rows and tables.

SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database sequence as a
transportable design-time file in the repository. Repository files can be read by applications that you develop.

You can use database sequences to perform the following operations:

● Generate unique, primary key values, for example, to identify the rows and columns of a table
● Coordinate keys across multiple rows or tables

The following example shows the contents of a valid sequence-definition file for a sequence called
MYSEQUENCE. Note that, in this example, no increment value is defined, so the default value of 1 (ascend by 1)
is assumed. To set a descending sequence of 1, set the increment_by value to -1.

schema= "TEST_DUMMY";
start_with= 10;
maxvalue= 30;
nomaxvalue=false;
minvalue= 1;
nominvalue=true;
cycles= false;
reset_by= "SELECT T1.\"Column2\" FROM \"MYSCHEMA\".
\"com.acme.test.tables::MY_TABLE1\" AS T1 LEFT JOIN \"MYSCHEMA\".
\"com.acme.test.tables::MY_TABLE2\" AS T2 ON T1.\"Column1\" = T2.\"Column1\"";
depends_on=["com.acme.test.tables::MY_TABLE1",
"com.acme.test.tables::MY_TABLE2"];

The sequence definition is stored in the repository with the suffix hdbsequence, for example,
MYSEQUENCE.hdbsequence.

Note
A schema generated from an .hdbsequence artifact can also be used in the context of Core Data Services
(CDS).

SAP HANA Developer Guide

240 PUBLIC Setting up the Persistence Model
If you activate a sequence-definition object in SAP HANA XS, the activation process checks if a sequence with
the same name already exists in the SAP HANA repository. If a sequence with the specified name does not
exist, the repository creates a sequence with the specified name and makes _SYS_REPO the owner of the new
sequence.

In a sequence defined using the .hdbsequence syntax, the reset_by keyword enables you to reset the
sequence using a query on any view, table or even table function. However, any dependency must be declared
explicitly, for example, with the depends_on keyword. The target table or view specified in the depends_on
keyword must be mentioned in the SELECT query that defines the reset condition. If the table or view specified
in the dependency does not exist, the activation of the object in the repository fails.

Note
On initial activation of the sequence definition, no check is performed to establish the existence of the target
view (or table) in the dependency; such a check is only made on reactivation of the sequence definition.

Security Considerations

It is important to bear in mind that an incorrectly defined sequences can lead to security-related problems. For
example, if the sequencing process becomes corrupted, it can result in data overwrite. This can happen if the
index has a maximum value which rolls-over, or if a defined reset condition is triggered unexpectedly. A roll-
over can be achieved by an attacker forcing data to be inserted by flooding the system with requests.
Overwriting log tables is a known practice for deleting traces. To prevent unexpected data overwrite, use the
following settings:

● cycles= false
● Avoid using the reset_by feature

Related Information

Sequence Configuration Syntax [page 242]

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 241
4.2.5.2 Sequence Configuration Syntax

SAP HANA Extended Application Services (SAP HANA XS) enables you to use the hdbsequence syntax to
create a database sequence as a design-time file in the repository. The design-time artifact that contains the
sequence definition must adhere to the .hdbsequence syntax specified below.

Sequence Definition

The following code illustrates a simple example of a design-time sequence definition using the .hdbsequence
syntax.

Note
Keywords are case-sensitive, for example, maxvalue and start_with, and the schema referenced in the table
definition, for example, MYSCHEMA, must already exist.

schema= "MYSCHEMA";
start_with= 10;
maxvalue= 30;
nomaxvalue= false;
minvalue= 1;
nominvalue= true;
cycles= false;
reset_by= "SELECT T1.\"Column2\" FROM \"MYSCHEMA\".
\"com.acme.test.tables::MY_TABLE1\" AS T1 LEFT JOIN \"MYSCHEMA\".
\"com.acme.test.tables::MY_TABLE2\" AS T2 ON T1.\"Column1\" = T2.\"Column1\"";
depends_on= ["com.acme.test.tables::MY_TABLE1",
"com.acme.test.tables::MY_TABLE2"];

Sequence-Definition Configuration Schema

The following example shows the configuration schema for sequences defined using the .hdbsequence
syntax. Each of the entries in the sequence-definition configuration schema is explained in more detail in a
dedicated section below:

string schema;
int32 increment_by(default=1);
int32 start_with(default=-1);
optional int32 maxvalue;
bool nomaxvalue(default=false);
optional int32 minvalue;
bool nominvalue(default=false);
optional bool cycles;
optional string reset_by;
bool public(default=false);
optional string depends_on_table;
optional string depends_on_view;
optional list<string> depends_on;

SAP HANA Developer Guide

242 PUBLIC Setting up the Persistence Model
Schema Name

To use the .hdbsequence syntax to specify the name of the schema that contains the sequence you are
defining, use the schema keyword. In the sequence definition, the schema keyword must adhere to the syntax
shown in the following example.

schema= "MYSCHEMA";

Increment Value

To use the .hdbsequence syntax to specify that the sequence increments by a defined value, use the
increment_by keyword. increment_by specifies the amount by which the next sequence value is
incremented from the last value assigned. The default increment is 1. In the sequence definition, the
increment_by keyword must adhere to the syntax shown in the following example.

increment_by= 2;

To generate a descending sequence, specify a negative value.

Note
An error is returned if the increment_by value is 0.

Start Value

To use the .hdbsequence syntax to specify that the sequence starts with a specific value, use the
start_with keyword. If you do not specify a value for the start_with keyword, the value defined in
minvalue is used for ascending sequences, and value defined in maxvalue is used for descending sequences.
In the sequence definition, the start_with keyword must adhere to the syntax shown in the following
example.

start_with= 10;

Maximum Value

To use the .hdbsequence syntax to specify that the sequence stops at a specific maximum value, for
example, 30, use the optional keyword maxvalue. In the sequence definition, the maxvalue keyword must
adhere to the syntax shown in the following example.

maxvalue= 30;

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 243
 Note
The maximum value (maxvalue) a sequence can generate must be between -4611686018427387903 and
4611686018427387902.

No Maximum Value

To use the .hdbsequence syntax to specify that the sequence does not stop at any specific maximum value,
use the boolean keyword nomaxvalue. When the nomaxvalue keyword is used, the maximum value for an
ascending sequence is 4611686018427387903 and the maximum value for a descending sequence is -1. In the
sequence definition, the nomaxvalue keyword must adhere to the syntax shown in the following example.

nomaxvalue= true;

Note
Note that the default setting for nomaxvalue is false.

Minimum Value

To use the .hdbsequence syntax to specify that the sequence stops at a specific minimum value, for example,
1, use the minvalue keyword. In the sequence definition, the minvalue keyword must adhere to the syntax
shown in the following example.

minvalue= 1;

Note
The minimum value (minvalue) a sequence can generate must be between -4611686018427387903 and
4611686018427387902.

No Minimum Value

To use the .hdbsequence syntax to specify that the sequence does not stop at any specific minimum value,
use the boolean keyword nominvalue. When the nominvalue keyword is used, the minimum value for an
ascending sequence is 1 and the minimum value for a descending sequence is -4611686018427387903. In the
sequence definition, the nominvalue keyword must adhere to the syntax shown in the following example.

nominvalue= true;

SAP HANA Developer Guide

244 PUBLIC Setting up the Persistence Model
 Note
Note that the default setting nominvalue is false.

Cycles

In a sequence defined using the .hdbsequence syntax, the optional boolean keyword cycles enables you to
specify whether the sequence number will be restarted after it reaches its maximum or minimum value. For
example, the sequence restarts with minvalue after having reached maxvalue (where increment_by is
greater than zero (0)) or restarts with maxvalue after having reached minvalue (where increment_by is
less than zero (0)). In the .hdbsequence definition, the cycles keyword must adhere to the syntax shown in
the following example.

cycles= false;

Reset by Query

In a sequence defined using the .hdbsequence syntax, the reset_by keyword enables you to reset the
sequence using a query on any view, table or even table function. However, any dependency must be declared
explicitly, for example, with the depends_on_view or depends_on_table keyword. If the table or view
specified in the dependency does not exist, the activation of the sequence object in the repository fails.

In the .hdbsequence definition, the reset_by keyword must adhere to the syntax shown in the following
example.

reset_by= "SELECT \"Col2\" FROM \"MYSCHEMA\".\"acme.com.test.tables::MY_TABLE\"

WHERE \"Col2\"='12'";

During a restart of the database, the system automatically executes the reset_by statement and the
sequence value is restarted with the value determined from the reset_by subquery

Note
If reset_by is not specified, the sequence value is stored persistently in the database. During the restart of
the database, the next value of the sequence is generated from the saved sequence value.

Depends on

In a sequence defined using the .hdbsequence syntax, the optional keyword depends_on enables you to
define a dependency to one or more specific tables or views, for example when using the reset_by option to

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 245
specify the query to use when resetting the sequence. In the .hdbsequence definition, the depends_on
keyword must adhere to the syntax shown in the following example.

depends_on=
["<repository.package.path>::<MY_TABLE_NAME1>","<repository.package.path>::<MY_VI
EW_NAME1>"];

Note
The depends_on keyword replaces and extends the keywords depends_on_table and
depends_on_view.

For example, to specify multiple tables and views with the depends_on keyword, use a comma-separated list
enclosed in square brackets [].

depends_on= ["com.acme.test.tables::MY_TABLE1",
"com.acme.test.tables::MY_TABLE2", "com.acme.test.views::MY_VIEW1"];

The target table or view specified in the depends_on keyword must be mentioned in the SELECT query that
defines the reset condition. On initial activation of the sequence definition, no check is performed to establish
the existence of the target table or view specified in the dependency; such a check is only made during
reactivation of the sequence definition. If one or more of the target tables or views specified in the dependency
does not exist, the re-activation of the sequence object in the repository fails.

Related Information

Sequences [page 240]

4.2.6 Create a Synonym

Extended Application Services (SAP HANA XS) enables you to create a local database synonym as a design-
time file in the repository.

Prerequisites

You have created a schema definition, for example, SCHEMA_2.hdbschema.

Context

In SAP HANA, a design-time synonym artifact has the suffix .hdbsynonym and defines the target object by
specifying an authoring schema and an object name; its activation evaluates a system's schema mapping to

SAP HANA Developer Guide

246 PUBLIC Setting up the Persistence Model
determine the physical schema in which the target table is expected, and creates a local synonym that points
to this object.

Restriction
A design-time synonym cannot refer to another synonym, and you cannot define multiple synonyms in a
single design-time synonym artifact. In addition, the target object specified in a design-time synonym must
only exist in the catalog; it is not possible to use .hdbsynonym to define a synonym for a catalog object that
originates from a design-time artifact.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the synonym definition file.
To generate a synonym called "acme.com.app1::MySynonym1", you must create a design-time
synonym artifact called MySynonym1.hdbsynonym in the repository package acme.com.app1. The first
line of the design-time synonym artifact must be specified as shown in the following example.

Sample Code

{ "acme.com.app1::MySynonym1" : {...}}

a. In the package structure, select the package where you want to create the new synonym-definition file
and from the context menu choose New File .
b. Enter the name of the synonym in the File Name field, for example, MySynonym1.hdbsynonym, and
choose Create.
3. Define the synonym.
Add the synonym-definition code to the new file, as shown in the example below, replacing object names
and paths to suit your requirements.

Sample Code

{ "acme.com.app1::MySynonym1" : {
"target" : {
"schema": "DEFAULT_SCHEMA",
"object": "MY_ERP_TABLE_1"
},
"schema": "SCHEMA_2"
}
}

4. Save the synonym-definition file.

The synonym is saved and activated in the SAP HANA repository.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 247
Related Information

Synonyms [page 248]

Schema [page 220]

4.2.6.1 Synonyms

SAP HANA Extended Application Services (SAP HANA XS) enables you to create a design-time representation
of a local database synonym. The synonym enables you to refer to a table (for example, from a view) that only
exists as a catalog object.

In SAP HANA XS, a design-time representation of a local synonym has the suffix.hdbsynonym that you can
store in the SAP HANA repository. The syntax of the design-time synonym artifact requires you to define the
target object by specifying an authoring schema and an object name. You also need to specify the schema in
which to create the new synonym. On activation of a design-time synonym artifact, SAP HANA XS evaluates a
system's schema mapping to determine the physical schema in which the target table is expected, and creates
a local synonym in the specified schema which points to this object. You can use this type of synonym if you
need to define a CDS view that refers to a table which only exists in the catalog; that is, the catalog table has no
design-time representation.

Restriction
A synonym cannot refer to another synonym, and you cannot define multiple synonyms in a single design-
time synonym artifact. In addition, the target object specified in a design-time synonym must only exist in
the catalog; it is not possible to define a define-time synonym for a catalog object that originates from a
design-time artifact.

In the following example of a design-time synonym artifact, the table MY_ERP_TABLE_1 resides in the schema
DEFAULT_SCHEMA. The activation of the design-time synonym artifact illustrated in the example would
generate a local synonym ("acme.com.app1::MySynonym1") in the schema SCHEMA_2. Assuming that a
schema-mapping table exists that maps DEFAULT_SCHEMA to the schema SAP_SCHEMA, the newly
generated synonym "SCHEMA_2"."acme.com.app1::MySynonym1" points to the run-time object
"SAP_SCHEMA"."MY_ERP_TABLE_1".

Sample Code
MySynonym1.hdbsynonym

{ "acme.com.app1::MySynonym1" : {
"target" : {
"schema": "DEFAULT_SCHEMA",
"object": "MY_ERP_TABLE_1"
},
"schema": "SCHEMA_2"
}
}

SAP HANA Developer Guide

248 PUBLIC Setting up the Persistence Model
 Tip
To generate a synonym called "acme.com.app1::MySynonym1", a design-time artifact called
MySynonym1.hdbsynonym must exist in the repository package acme.com.app1; the first line of the
design-time synonym artifact must be specified as illustrated in the example above.

Related Information

Schema [page 220]

4.2.6.2 Synonym Configuration Syntax

A specific syntax is required to create a design-time representation of a local database synonym in SAP HANA
Extended Application Services.

Synonym Definition

SAP HANA Extended Application Services (SAP HANA XS) enables you to use the hdbsynonym syntax to
create a database synonym as a design-time file in the repository. On activation, a local synonym is generated
in the catalog in the specified schema. The design-time artifact that contains the synonym definition must
adhere to the .hdbsynonym syntax specified below.

Note
The activation of the design-time synonym artifact illustrated in the following example generates a local
synonym ("acme.com.app1::MySynonym1") in the schema SCHEMA_2.

Sample Code
MySynonym1.hdbsynonym

{ "acme.com.app1::MySynonym1" : {
"target" : {
"schema": "DEFAULT_SCHEMA",
"object": "MY_ERP_TABLE_1"
},
"schema [page 251]": "SCHEMA_2"
}
}

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 249
Synonym Location

In the first line of the synonym-definition file, you must specify the absolute repository path to the package
containing the synonym artifact (and the name of the synonym artifact) itself using the syntax illustrated in the
following example.

Code Syntax

{ "<full.path.to.package>::<MySynonym1>" : {...}}

For example, to generate a synonym called "acme.com.app1::MySynonym1", you must create a design-time
artifact called MySynonym1.hdbsynonym in the repository package acme.com.app1; the first line of the
design-time synonym artifact must be specified as illustrated in the following example.

Sample Code

{ "acme.com.app1::MySynonym1" : {...}}

target

To specify the name and location of the object for which you are defining a synonym, use the target keyword
together with the keywords schema and object. In the synonym definition, the target keyword must adhere
to the syntax shown in the following example.

Code Syntax

"target" : {
"schema": "<Name_of_schema_containing_<"object">",
"object": "<Name_of_target_object>"
},

In the context of the target keyword, the following additional keywords are required:

● schema defines the name of the schema where the target object (defined in object) is located.
● object specifies the name of the catalog object to which the synonym applies.

Restriction
The target object specified in a design-time synonym must only exist in the catalog; it is not possible to
define a design-time synonym for a catalog object that originates from a design-time artifact.

SAP HANA Developer Guide

250 PUBLIC Setting up the Persistence Model
schema

To specify the catalog location of the generated synonym, use the schema keyword. In the synonym definition,
the schema keyword must adhere to the syntax shown in the following example.

Code Syntax

"schema": "<Schema_location_of_generated_synonym>"

Related Information

Synonyms [page 248]

4.2.7 Tutorial: Import Data with HDBTable Table Import

The table-import function is a data-provisioning tool that enables you to import data from comma-separated
values (CSV) files into SAP HANA database tables.

Context

In this tutorial, you import data from a CSV file into a table generated from a design-time definition that uses
the .hdbtable syntax. Note that the names used are just examples; where necessary, replace the names of
the schema, tables, files, and so on with your own names.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create a root package for your table-import application.
a. In the structure, select the package (for example, mycompany.tests) where you want to create a new
package for your table-import configuration and from the context menu choose New Package .
b. Enter a package name, for example, TiTest, and choose Create.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 251
 Note
Naming conventions exist for package names, for example, a package name must not start with
either a dot (.) or a hyphen (-) and cannot contain two or more consecutive dots (..). In addition, the
name must not exceed 190 characters.

3. Create a set of table-import files.

For the purposes of this tutorial, you create all files in the same package, for example, a package called
TiTest. Note, however, that the table-import feature also allows you to use files distributed in different
packages.

The following files are required for the table import scenario:
○ The table-import configuration file, for example, inhabitants.hdbti
Specifies the source file containing the data values to import and the target table in SAP HANA into
which the data will be inserted.
○ A CSV file, for example, inhabitants.csv
Contains the data to be imported into the SAP HANA table during the table-import operation; values in
the .csv file can be separated either by a comma (,) or a semi-colon (;).
○ A target table, for example, inhabitants.hdbtable
The target table can be either a runtime table in the catalog or a table definition, for example, a table
defined using the .hdbtable syntax (TiTable.hdbtable) or the CDS-compliant .hdbdd syntax
(TiTable.hdbdd).

Note
In this tutorial, the target table for the table-import operation is inhabitants.hdbtable, a
design-time table defined using the .hdbtable syntax.

○ The schema definition, for example, AMT.hdbschema

Specifies the name of the schema in which the target import table is created.
When all the necessary files are available, you can import data from the source CSV file into the desired
target table.
4. Create the schema definition file and assign schema privileges:
a. Create or open the schema definition (AMT.hdbschema) file, enter the name of the schema you want
to use to contain the target table, and save the file:

schema_name="AMT";

b. To grant schema privileges to yourself, select the AMT.hdbschema file and choose (Assign
execution authorization).
You are assigned the requested schema privileges.
5. Create or open the table-definition file for the target import table (inhabitants.hdbtable) and enter
the following lines of text; this example uses the .hdbtable syntax:

table.schemaName = "AMT";
table.tableType = COLUMNSTORE;
table.columns =
[
{name = "ID"; sqlType = VARCHAR; nullable = false; length = 20; comment =
"";},
{name = "surname"; sqlType = VARCHAR; nullable = true; length = 30; comment =
"";},

SAP HANA Developer Guide

252 PUBLIC Setting up the Persistence Model
 {name = "name"; sqlType = VARCHAR; nullable = true; length = 30; comment =
"";},
{name = "city"; sqlType = VARCHAR; nullable = true; length = 30; comment =
"";}
];
table.primaryKey.pkcolumns = ["ID"];

6. Open the CSV file containing the data to import, for example, inhabitants.csv in a text editor and enter
the values shown in the following example:

0,Annan,Kofi,Accra
1,Essuman,Wiredu,Tema
2,Tetteh,Kwame,Kumasi
3,Nterful,Akye,Tarkwa
4,Acheampong,Kojo,Tamale
5,Assamoah,Adjoa,Takoradi
6,Mensah,Afua,Cape Coast

Note
You can import data from multiple .csv files in a single, table-import operation. However, each .csv file
must be specified in a separate code block ({table= ...}) in the table-import configuration file.

7. Create or open the table-import configuration file (inhabitants.hdbti) and enter the following lines of
text (make sure the paths point to the correct locations in your environment):

import = [
{
table = "mycompany.tests.TiTest::inhabitants";
schema = "AMT";
file = "mycompany.tests.TiTest:inhabitants.csv";
header = false;
}
];

8. Save all files.

This activates all the repository objects. The data specified in the CSV file inhabitants.csv is imported
into the SAP HANA table inhabitants using the data-import configuration defined in the
inhabitants.hdbti table-import configuration file.
9. In the catalog, check the contents of the runtime table inhabitants to ensure that the correct data was
imported into the correct columns.

Expand the AMT Tables node, select the table mycompany.tests.TiTest::inhabitants, and
from the context menu choose Open Content.

4.2.7.1 Data Provisioning Using Table Import

You can import data from comma-separated values (CSV) into the SAP HANA tables using the SAP HANA
Extended Application Services (SAP HANA XS) table-import feature.

In SAP HANA XS, you create a table-import scenario by setting up an table-import configuration file and one or
more comma-separated value (CSV) files containing the content you want to import into the specified SAP
HANA table. The import-configuration file links the import operation to one or more target tables. The table
definition (for example, in the form of a .hdbdd or .hdbtable file) can either be created separately or be
included in the table-import scenario itself.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 253
To use the SAP HANA XS table-import feature to import data into an SAP HANA table, you need to understand
the following table-import concepts:

● Table-import configuration
You define the table-import model in a configuration file that specifies the data fields to import and the
target tables for each data field.

Note
The table-import file must have the .hdbti extension, for example, myTableImport.hdbti.

CSV Data File Constraints

The following constraints apply to the CSV file used as a source for the table-import feature in SAP HANA XS:

● The number of table columns must match the number of CSV columns.
● There must not be any incompatibilities between the data types of the table columns and the data types of
the CSV columns.
● Overlapping data in data files is not supported.
● The target table of the import must not be modified (or appended to) outside of the data-import operation.
If the table is used for storage of application data, this data may be lost during any operation to re-import
or update the data.

Related Information

Table-Import Configuration [page 204]

Table-Import Configuration-File Syntax [page 207]

4.2.7.2 Table-Import Configuration

You can define the elements of a table-import operation in a design-time file; the configuration includes
information about source data and the target table in SAP HANA.

SAP HANA Extended Application Services (SAP HANA XS) enables you to perform data-provisioning
operations that you define in a design-time configuration file. The configuration file is transportable, which
means you can transfer the data-provisioning between SAP HANA systems quickly and easily.

The table-import configuration enables you to specify how data from a comma-separated-value (.csv) file is
imported into a target table in SAP HANA. The configuration specifies the source file containing the data values
to import and the target table in SAP HANA into which the data must be inserted. As further options, you can
specify which field delimiter to use when interpreting data in the source .csv file and if keys must be used to
determine which columns in the target table to insert the imported data into.

SAP HANA Developer Guide

254 PUBLIC Setting up the Persistence Model
 Note
If you use multiple table import configurations to import data into a single target table, the keys keyword is
mandatory. This is to avoid problems relating to the overwriting or accidental deletion of existing data.

The following example of a table-import configuration shows how to define a simple import operation which
inserts data from the source files myData.csv and myData2.csv into the table myTable in the schema
mySchema.

import = [
{
table = "myTable";
schema = "mySchema";
file = "sap.ti2.demo:myData.csv";
header = false;
delimField = ";";
keys = [ "GROUP_TYPE" : "BW_CUBE"];
},
{
table = "sap.ti2.demo::myTable";
file = "sap.ti2.demo:myData2.csv";
header = false;
delimField = ";";
keys = [ "GROUP_TYPE" : "BW_CUBE"];
}
];

In the table import configuration, you can specify the target table using either of the following methods:

● Public synonym (“sap.ti2.demo::myTable”)

If you use the public synonym to reference a target table for the import operation, you must use either the
hdbtable or cdstable keyword, for example, hdbtable = "sap.ti2.demo::myTable";
● Schema-qualified catalog name (“mySchema”.“MyTable”
If you use the schema-qualified catalog name to reference a target table for the import operation, you must
use the table keyword in combination with the schema keyword, for example, table = "myTable";
schema = "mySchema";

Note
Both the schema and the target table specified in the table-import operation must already exist. If either the
specified table or the schema does not exist, SAP HANA XS displays an error message during the activation
of the configuration file, for example: Table import target table cannot be found. or Schema
could not be resolved.

You can also use one table-import configuration file to import data from multiple .csv source files. However,
you must specify each import operation in a new code block introduced by the [hdb | cds]table keyword, as
illustrated in the example above.

By default, the table-import operation assumes that data values in the .csv source file are separated by a
comma (,). However, the table-import operation can also interpret files containing data values separated by a
semi-colon (;).

● Comma (,) separated values

,,,BW_CUBE,,40000000,2,40000000,all

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 255
● Semi-colon (;) separated values

;;;BW_CUBE;;40000000;3;40000000;all

Note
If the activated .hdbti configuration used to import data is subsequently deleted, only the data that was
imported by the deleted .hdbti configuration is dropped from the target table. All other data including any
data imported by other .hdbti configurations remains in the table. If the target CDS entity has no key
(annotated with @nokey) all data that is not part of the CSV file is dropped from the table during each table-
import activation.

You can use the optional keyword keys to specify the key range taken from the source .csv file for import into
the target table. If keys are specified for an import in a table import configuration, multiple imports into same
target table are checked for potential data collisions.

Note
The configuration-file syntax does not support wildcards in the key definition; the full value of a selectable
column value has to be specified.

Security Considerations

In SAP HANA XS, design-time artifacts such as tables (.hdbtable or .hdbdd) and table-import
configurations (.hdbti) are not normally exposed to clients via HTTP. However, design-time artifacts
containing comma-separated values (.csv) could be considered as potential artifacts to expose to users
through HTTP. For this reason, it is essential to protect these exposed .csv artifacts by setting the appropriate
application privileges; the application privileges prevents data leakage, for example, by denying access to data
by users, who are not normally allowed to see all the records in such tables.

Tip
Place all the .csv files used to import content to into tables together in a single package and set the
appropriate (restrictive) application-access permissions for that package, for example, with a
dedicated .xsaccess file.

Related Information

Table-Import Configuration-File Syntax [page 207]

SAP HANA Developer Guide

256 PUBLIC Setting up the Persistence Model
4.2.7.3 Table-Import Configuration-File Syntax

The design-time configuration file used to define a table-import operation requires the use of a specific syntax.
The syntax comprises a series of keyword=value pairs.

If you use the table-import configuration syntax to define the details of the table-import operation, you can use
the keywords illustrated in the following code example. The resulting design-time file must have the .hdbti file
extension, for example, myTableImportCfg.hdbti.

import = [
{
table = "myTable";
schema = "mySchema";
file = "sap.ti2.demo:myData.csv";
header = false;
useHeaderNames = false;
delimField = ";";
delimEnclosing=“\““;
distinguishEmptyFromNull = true;
keys = [ "GROUP_TYPE" : "BW_CUBE", "GROUP_TYPE" : "BW_DSO", "GROUP_TYPE" :
"BW_PSA"];
}
];

table

In the table-import configuration, the table, cdstable, and hdbtable keywords enable you to specify the
name of the target table into which the table-import operation must insert data. The target table you specify in
the table-import configuration can be a runtime table in the catalog or a design-time table definition, for
example, a table defined using either the .hdbtable or the .hdbdd (Core Data Services) syntax.

Note
The target table specified in the table-import configuration must already exist. If the specified table does not
exist, SAP HANA XS displays an error message during the activation of the configuration file, for example:
Table import target table cannot be found.

Use the table keyword in the table-import configuration to specify the name of the target table using the
qualified name for a catalog table.

table = "target_table";
schema = "mySchema";

Note
You must also specify the name of the schema in which the target catalog table resides, for example, using
the schema keyword.

The hdbtable keyword in the table-import configuration enables you to specify the name of a target table using
the public synonym for a design-time table defined with the .hdbtable syntax.

hdbtable = "sap.ti2.demo::target_table";

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 257
The cdstable keyword in the table-import configuration enables you to specify the name of a target table using
the public synonym for a design-time table defined with the CDS-compliant .hdbdd syntax.

cdstable = "sap.ti2.demo::target_table";

Caution
There is no explicit check if the addressed table is created using the .hdbtable or CDS-compliant .hdbdd
syntax.

If the table specified with the cdstable or hdbtable keyword is not defined with the corresponding syntax,
SAP HANA displays an error when you try to activate the artifact, for example,Invalid combination of
table declarations found, you may only use [cdstable | hdbtable | table] .

schema

The following code example shows the syntax required to specify a schema in a table-import configuration.

schema = "TI2_TESTS";

Note
The schema specified in the table-import configuration file must already exist.

If the schema specified in a table-import configuration file does not exist, SAP HANA XS displays an error
message during the activation of the configuration file, for example:

● Schema could not be resolved.

● If you import into a catalog table, please provide schema.

The schema is only required if you use a table's schema-qualified catalog name to reference the target table for
an import operation, for example, table = "myTable"; schema = "mySchema";. The schema is not
required if you use a public synonym to reference a table in a table-import configuration, for example,
hdbtable = "sap.ti2.demo::target_table";.

file

Use the file keyword in the table-import configuration to specify the source file containing the data that the
table-import operation imports into the target table. The source file must be a .csv file with the data values
separated either by a comma (,) or a semi-colon (;). The file definition must also include the full package path
in the SAP HANA repository.

file = "sap.ti2.demo:myData.csv";

SAP HANA Developer Guide

258 PUBLIC Setting up the Persistence Model
header

Use the header keyword in the table-import configuration to indicate if the data contained in the
specified .csv file includes a header line. The header keyword is optional, and the possible values are true or
false.

header = false;

useHeaderNames

Use the useHeaderNames keyword in the table-import configuration to indicate if the data contained in the
first line of the specified .csv file must be interpreted. The useHeaderNames keyword is optional; it is used in
combination with theheader keyword. The useHeaderNames keyword is boolean: possible values are true or
false.

Note
The useHeaderNames keyword only works if header is also set to “true”.

useHeaderNames = false;

The table-import process considers the order of the columns; if the column order specified in the .csv, file
does not match the order used for the columns in the target table, an error occurs on activation.

delimField

Use the delimField keyword in the table-import configuration to specify which character is used to separate
the values in the data to be imported. Currently, the table-import operation supports either the comma (,) or
the semi-colon (;). The following example shows how to specify that values in the .csv source file are
separated by a semi-colon (;).

delimField = ";";

Note
By default, the table-import operation assumes that data values in the .csv source file are separated by a
comma (,). If no delimiter field is specified in the .hdbti table-import configuration file, the default setting
is assumed.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 259
delimEnclosing

Use the delimEnclosing keyword in the table-import configuration to specify a single character that
indicates both the start and end of a set of characters to be interpreted as a single value in the .csv file, for
example “This is all one, single value”. This feature enables you to include in data values in a .CSV file even the
character defined as the field delimiter (in delimField), for example, a comma (,) or a semi-colon (;).

Tip
If the value used to separate the data fields in your .csv file (for example, the comma (,)) is also used inside
the data values themselves ("This, is, a, value"), you must declare and use a delimiter enclosing
character and use it to enclose all data values to be imported.

The following example shows how to use the delimEnclosing keyword to specify the quote (") as the
delimiting character that indicates both the start and the end of a value in the .csv file. Everything enclosed
between the delimEnclosing characters (in this example, “”) is interpreted by the import process as one,
single value.

delimEnclosing=“\““;

Note
Since the hdbti syntax requires us to use the quotes (“”) to specify the delimiting character, and the
delimiting character in this example is, itself, also a quote ("), we need to use the backslash character (\) to
escape the second quote (").

In the following example of values in a .csv file, we assume that delimEnclosing“\““, and
delimField=",". This means that imported values in the .csv file are enclosed in the quote character
("value”) and multiple values are separated by the comma ("value1”,"value 2”). Any commas inside the
quotes are interpreted as a comma and not as a field delimiter.

"Value 1, has a comma","Value 2 has, two, commas","Value3"

You can use other characters as the enclosing delimiter, too, for example, the hash (#). In the following
example, we assume that delimEnclosing="#" and delimField=";". Any semi-colons included inside the
hash characters are interpreted as a semi-colon and not as a field delimiter.

#Value 1; has a semi-colon#;#Value 2 has; two; semi-colons#;#Value3#

distinguishEmptyFromNull

Use the distinguishEmptyFromNull keyword in combination with delimEnclosing to ensure that the
table-import process correctly interprets any empty value in the .CSV file, which is enclosed with the value
defined in the delimEnclosing keyword, for example, as an emtpy space. This ensures that an emtpy space
is imported “as is” into the target table. If the empty space in incorrectly interpreted, it is imported as NULL.

distinguishEmptyFromNull = true;

SAP HANA Developer Guide

260 PUBLIC Setting up the Persistence Model
 Note
The default setting for distinguishEmptyFromNull is false.

If distinguishEmptyFromNull=false is used in combination with delimEnclosing, then an empty value

in the .CSV (with or without quotes “”) is interpreted as NULL.

"Value1",,"",Value2

The table-import process would add the values shown in the example .csv above into the target table as
follows:

Value1 | NULL | NULL | Value2

keys

Use the keys keyword in the table-import configuration to specify the key range to be considered when
importing the data from the .csv source file into the target table.

keys = [ "GROUP_TYPE" : "BW_CUBE", "GROUP_TYPE" : "BW_DSO", "GROUP_TYPE" :

"BW_PSA"];

In the example above, all the lines in the .csv source file where the GROUP_TYPE column value matches one of
the given values (BW_CUBE, BW_DSO, or BW_PSA) are imported into the target table specified in the table-import
configuration.

;;;BW_CUBE;;40000000;3;40000000;slave
;;;BW_DSO;;40000000;3;40000000;slave
;;;BW_PSA;;2000000000;1;2000000000;slave

In the following example, the GROUP_TYPE column is specified as empty(“”).

keys = [ "GROUP_TYPE" : ""];

All the lines in the .csv source file where the GROUP_TYPE column is empty are imported into the target table
specified in the table-import configuration.

;;;;;40000000;2;40000000;all

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 261
4.2.7.4 Table-Import Configuration Error Messages

During the course of the activation of the table-import configuration and the table-import operation itself, SAP
HANA checks for errors and displays the following information in a brief message.

Table-Import Error Messages

Message Number Message Text Message Reason

40200 Invalid combination of table 1. The table keyword is specified in a table-

import configuration that references a ta­
declarations found, you may only
ble defined using the .hdbtable
use [cdstable | hdbtable | table]
(or .hdbdd) syntax.
2. The hdbtable keyword is specified in a ta­
ble-import configuration that references a
table defined using another table-defini-
tion syntax, for example, the .hdbdd syn­
tax.
3. The cdstable keyword is specified in a ta­
ble-import configuration that references a
table defined using another table-defini-
tion syntax, for example, the .hdbtable
syntax.

40201 If you import into a catalog table, 1. You specified a target table with the table
keyword but did not specify a schema with
please provide schema
the schema keyword.

40202 Schema could not be resolved 1. The schema specified with the schema
keyword does not exist or could not be
found (wrong name).
2. The public synonym for an .hdbtable
or .hdbdd (CDS) table definition cannot
be resolved to a catalog table.

40203 Schema resolution error 1. The schema specified with the schema
keyword does not exist or could not be
found (wrong name).
2. The database could not complete the
schema-resolution process for some rea­
son - perhaps unrelated to the table-im­
port configuration (.hdbti), for exam­
ple, an inconsistent database status.

40204 Table import target table cannot be 1. The table specified with the table keyword
does not exist or could not be found
found
(wrong name or wrong schema name).

40210 Table import syntax error 1. The table-import configuration file

(.hdbti) contains one or more syntax
errors.

SAP HANA Developer Guide

262 PUBLIC Setting up the Persistence Model
 Message Number Message Text Message Reason

40211 Table import constraint checks 1. The same key is specified in multiple ta­
ble-import configurations (.hdbti files),
failed
which leads to overlaps in the range of
data to import.
2. If keys are specified for an import in a ta­
ble-import configuration, multiple imports
into the same target table are checked for
potential data collisions

40212 Importing data into table failed 1. Either duplicate keys were written (due to
duplicates in the .CSV source file) or
2. An (unexpected) error occurred on the
SQL level.

40213 CSV table column count mismatch 1. Either the number of columns in the .CSV
record is higher than the number of col­
umns in the table, or
2. The number of columns in the .CSV re­
cord is higher than the number of columns
in its header.

40214 Column type mismatch The csv file does not match the target table for
either of the following reasons:

1. Data are missing for some not-null

columns
2. Some columns specified in the .CSV re­
cord do not exist in the table

40216 Key does not match to table header For some key columns of the table no data are
provided.

SAP HANA Developer Guide

Setting up the Persistence Model PUBLIC 263
5 Developing Procedures

SQL in SAP HANA includes extensions for creating procedures, which enables you to embed data-intensive
application logic into the database, where it can be optimized for performance (since there are no large data
transfers to the application and features such as parallel execution are possible). Procedures are used when
other modeling objects, such as analytic or attribute views, are not sufficient.

Some of the reasons to use procedures instead of standard SQL:

● SQL is not designed for complex calculations, such as for financials.

● SQL does not provide for imperative logic.
● Complex SQL statements can be hard to understand and maintain.
● SQL queries return one result set. Procedures can return multiple result sets.
● Procedures can have local variables, eliminating the need to explicitly create temporary tables for
intermediate results.

Languages

Procedures can be written in the following languages:

● SQLScript: The language that SAP HANA provides for writing procedures.
● R: An open-source programming language for statistical computing and graphics, which can be installed
and integrated with SAP HANA.

There are additional libraries of procedures, called Business Function Library and Predictive Analysis Library,
that can be called via SQL or from within another procedure.

SQL Extensions for Procedures

SQL includes the following statements for enabling procedures:

● CREATE TYPE: Creates a table types, which are used to define parameters for a procedure that represent
tabular results. For example:

CREATE TYPE tt_publishers AS TABLE (

publisher INTEGER,
name VARCHAR(50),
price DECIMAL,
cnt INTEGER);

● CREATE PROCEDURE: Creates a procedure. The LANGUAGE clause specifies the language you are using to
code the procedure. For example:

CREATE PROCEDURE ProcWithResultView(IN id INT, OUT o1 CUSTOMER)

LANGUAGE SQLSCRIPT READS SQL DATA WITH RESULT VIEW ProcView AS
BEGIN
o1 = SELECT * FROM CUSTOMER WHERE CUST_ID = :id;

SAP HANA Developer Guide

264 PUBLIC Developing Procedures
 END;

● CALL: Calls a procedure. For example:

CALL getOutput (1000, 'EUR', NULL, NULL);

Code Completion

In the SAP HANA Web-based Development Workbench, the editor provides semantic code completion for the
hdbprocedure file type. The semantic code completion feature is a context based search tool that lists
suggested catalog objects and local variables that assist you with developing accurate stored procedures in a
faster and more efficient matter. You can quickly identify valid objects, reducing errors during activation. Code
completion proposals take into consideration SQLScript grammar, context specific schemas, and textual input.

The suggested objects are derived from the following origins:

● Catalog objects: such as schemas, views, table functions, procedures, scalar functions, synonyms
● Local variables: such as input and output parameters, declared scalar variables
● Database artifacts

Suggested objects are listed alphabetically, according to the following format:

[icon] artifact_name - artifact_type (artifact_context), for example DUMMY - Table

(<Schema name>)

The list of proposals contain syntactic and semantic proposals listed in the following order:

1. Local variables
2. Catalog objects (maximum of 50 suggestions)
3. Keywords

Note
Objects selected from the proposed list might be automatically inserted as quoted identifiers based on the
SQLScript language guidelines For example, if the object contains special characters, or lower and upper
case characters.

5.1 Create and Edit Procedures

You can create and edit procedures in the SAP HANA Web-based Development Workbench Editor tool.

Prerequisites

You have the privileges granted by the role sap.hana.ide.roles::EditorDeveloper; this role is included in the
parent role sap.hana.ide.roles::Developer.

SAP HANA Developer Guide

Developing Procedures PUBLIC 265
Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the file that will contain the stored procedure.

a. Select the package where you want to create the new stored procedure and from the context menu
choose New HDB Procedure .
b. Enter the required data:

○ File name: Enter the file name without the file extension. The file extension .hdbprocedure is
added automatically when the file is created.
○ Schema: Enter the name of an existing schema.
c. Choose Create.
The new procedure is listed under the package you selected.
3. Define the new stored procedure.
Begin writing your code inside your new procedure and save it. The syntax is checked simultaneously and
is highlighted. Auto-completion of the syntax appears as you type or by using the semantic code
completion feature.

Note
You can only write one stored procedure per file. The file name and the procedure name must be the
same. Only SQLScript language is supported for hdbprocedure procedures.

To use semantic code completion:

a. Position the cursor where you want to insert an object.
b. Press CTRL + SPACEBAR .
A suggested list of valid objects appear.

Note
Text-based searches display the object names that begin with and contain the entered text.
Searches are asynchronous, the suggested list is updated in parallel to the user's refined textual
input.

c. Use the arrow keys to scroll through the list, click Enter to select the object, or Esc to close the code
completion window without selecting an object.
4. Save the procedure.
Your procedure is saved and activated and is now available in the catalog as a runtime object. This allows
you and other users to call the procedure and debug it.

Related Information

Define and Use Table Types in Procedures [page 267]

SAP HANA Developer Guide

266 PUBLIC Developing Procedures
Tutorial: Create an SQLScript Procedure that Uses Imperative Logic [page 269]
SQLScript Security Considerations [page 276]
SAP HANA SQL and System Views Reference

5.1.1 Define and Use Table Types in Procedures

You can use a table type to define parameters for a procedure; the table type represents tabular results.

Prerequisites

● Access to the SAP HANA repository

Context

If you define a procedure that uses data provided by input and output parameters, you can use table types to
store the parameterized data. These parameters have a type and are either based on a global table (for
example, a catalog table), a global table type, or a local (inline) table type. This task shows you two ways to use
the .hdbprocedure syntax to define a text-based design-time procedure artifact; the parameterized data for
your procedure can be stored in either of the following ways:

● Global
In an externally defined (and globally available) table type, for example, using the Core Data Service (CDS)
syntax
● Local:
In a table type that is defined inline, for example, in the procedure itself

Procedure

1. Create a procedure that uses data provided by a local (inline) table type.
To define a text-based design-time procedure, use the .hdbprocedure syntax. The procedure in this
example stores data in a local table type defined inline, that is; in the procedure itself.

Note
If you plan to define a global table type (for example, using CDS) you can skip this step.

a. Create a design-time artifact called get_product_sale_price.hdbprocedure and save it in the

repository.
b. Add the following code to the new repository artifact get_product_sale_price.hdbprocedure.

SAP HANA Developer Guide

Developing Procedures PUBLIC 267
 Tip
The table used to store the parameterized data is defined inline, in the procedure's OUT parameter.

PROCEDURE
SAP_HANA_EPM_NEXT."sap.hana.democontent.epmNext.procedures::get_product_sal
e_price" (
IN im_productid NVARCHAR(10),
OUT ex_product_sale_price table (
"PRODUCTID" nvarchar(10),
"CATEGORY" nvarchar(40),
"PRICE" decimal(15,2),
"SALEPRICE" decimal(15,2) ) )
LANGUAGE SQLSCRIPT
SQL SECURITY INVOKER
DEFAULT SCHEMA SAP_HANA_EPM_NEXT
READS SQL DATA AS
BEGIN

c. Save and activate the new (hdb)procedure artifact.

2. Define a global table type using Core Data Services (CDS).
If you want to define a global table type to store data for your use by your procedure, you can use the CDS
syntax to define the global table type, as illustrated in the following example:

Note
This is only required if you want to use a global table type. If you plan to define a table type inline, you
can skip this step.

a. Create a design-time artifact called GlobalTypes.hdbdd and save it in the repository.

b. Add the following code to the new repository artifact GlobalTypes.hdbdd.

namespace sap.hana.democontent.epmNext.data;
@Schema: 'SAP_HANA_EPM_NEXT'
context GlobalTypes {
type tt_product_sale_price {
PRODUCTID: String(10);
CATEGORY: String(40);
PRICE: Decimal(15,2);
SALEPRICE: Decimal(15,2);
};
};

c. Save and activate the new CDS table type.

This generates a table type called GlobalTypes.tt_product_sale_price in the package
sap.hana.democontent.epmNext.data. You use this path to reference the table type in your
procedure.
3. Create the procedure that uses data provided by a global table type.
To define a text-based design-time procedure, use the .hdbprocedure syntax. The procedure in this
example stores data in a table with the structure defined in the CDS global data type
tt_product_sale_price.

Note
This is only required if you want to use a global table type. If you plan to define a table type inline, you
can skip this step.

SAP HANA Developer Guide

268 PUBLIC Developing Procedures
 a. Create a design-time artifact called get_product_sale_price.hdbprocedure and save it in the
repository.
b. Add the following code to the new repository artifact get_product_sale_price.hdbprocedure.

Tip
The OUT parameter refers to the CDS type tt_product_sale_price defined in the CDS
document GlobalTypes.hdbdd.

PROCEDURE
SAP_HANA_EPM_NEXT."sap.hana.democontent.epmNext.procedures::get_product_sal
e_price" (
IN im_productid NVARCHAR(10),
OUT ex_product_sale_price SAP_HANA_EPM_NEXT."
sap.hana.democontent.epmNext.data::GlobalTypes.tt_product_sale_price")
LANGUAGE SQLSCRIPT
SQL SECURITY INVOKER
DEFAULT SCHEMA SAP_HANA_EPM_NEXT
READS SQL DATA AS
BEGIN

c. Save and activate the new (hdb)procedure artifact.

5.1.2 Tutorial: Create an SQLScript Procedure that Uses

Imperative Logic

SQLScript procedures can make use of standard SQL statements to build a query that requests data and
returns a specified result set.

Prerequisites

● You have installed the SAP HANA Interactive Education (SHINE) HCODEMOCONTENT delivery unit (DU); this
DU contains the tables and views that you want to consume with the procedure you build in this tutorial.
● You have generated data to populate the tables and views provided by the SHINE delivery unit and used in
this tutorial. You can generate the data with tools included in the SHINE delivery unit.

Note
You might have to adjust the paths in the code examples provided to suit the package hierarchy in your SAP
HANA repository, for example, to point to the underlying content (demonstration tables and services)
referenced in the tutorial.

SAP HANA Developer Guide

Developing Procedures PUBLIC 269
Context

The stored procedure you create in this tutorial uses standard SQL statements (for example, SELECT
statements) and some imperative logic constructs to determine the sale price of a product based on the
product category.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the file that will contain the stored procedure.

a. In the package where you want to create the new stored procedure, create a new subpackage called
procedures, if not already available.
b. From the context menu of the procedures folder, choose New HDB Procedure .
c. Enter the required data:

○ File name: Enter the file name get_product_sales_price. The file extension .hdbprocedure
is added automatically when the file is created.
○ Schema: Enter the name of an existing schema, for example, MYSCHEMA.
d. Choose Create.
3. Define the new stored procedure.
This procedure uses standard SQL statements and some imperative logic constructs to determine the sale
price of a product based on the product category.
a. In the get_product_sales_price.hdbprocedure file, use the following code to define the details
of the stored procedure:

Sample Code

PROCEDURE "MYSCHEMA"."demo.procedures::get_product_sales_price" (IN

productid NVARCHAR(10), OUT product_sale_price
SAP_HANA_DEMO."sap.hana.democontent.epm.data::EPM.Procedures.tt_product_s
ale_price")
LANGUAGE SQLSCRIPT
SQL SECURITY INVOKER
READS SQL DATA AS
BEGIN
/*****************************
Write your procedure logic
*****************************/
declare lv_category nvarchar(40) := null;
declare lv_discount decimal(15,2) := 0;
lt_product = select PRODUCTID, CATEGORY, PRICE
from "sap.hana.democontent.epm.data::EPM.MD.Products"
where PRODUCTID = :productid;
select CATEGORY into lv_category from :lt_product;
if :lv_category = 'Notebooks' then
lv_discount := .20;
elseif :lv_category = 'Handhelds' then
lv_discount := .25;
elseif :lv_category = 'Flat screens' then

SAP HANA Developer Guide

270 PUBLIC Developing Procedures
 lv_discount := .30;
elseif :lv_category like '%printers%' then
lv_discount := .30;
else
lv_discount := 0.00; -- No discount
end if;
product_sale_price =
select PRODUCTID, CATEGORY, PRICE,
cast((PRICE - (PRICE * :lv_discount)) as decimal(15,2))
as "SALEPRICE" from :lt_product;
END;

Remember
Remember to replace the schema name and fully qualified procedure name with the ones you have
used. In the example above, the schema name is MYSCHEMA and the fully qualified procedure name
is demo.procedures::get_product_sales_price.

b. Save the changes you have made to the new stored procedure.
4. Preview the data in the editor.

a. In the toolbar choose (Invoke Procedure with UI).

The SQL console opens.
b. On the Prepare SQL tab, enter a product ID, for example, HT-1000.

c. Choose (Run).
The SQL result is displayed.

5. Open the catalog and check that the new stored procedure was successfully created in the correct
location.
Example: Catalog.MYSCHEMA.Procedures.demo.procedures::get_product_sales_price
6. Test the new stored procedure in the catalog.
a. In the context menu of the file (for example, demo.procedures::get_product_sales_price),
choose Invoke Procedure.
The SQL console opens.

Sample Code

CALL "MYSCHEMA"."demo.procedures::get_product_sales_price"(PRODUCTID =>

''/*<NVARCHAR(10)>*/,PRODUCT_SALE_PRICE => ?);

b. Enter a product ID, for example, HT-1000, and choose (Run).

Sample Code

CALL "MYSCHEMA"."demo.procedures::get_product_sales_price"

SAP HANA Developer Guide

Developing Procedures PUBLIC 271
 (PRODUCTID => 'HT-1000', PRODUCT_SALE_PRICE => ? );

The SQL result is displayed.

5.2 Tutorial: Create a Scalar User-Defined Function

In SQL, a user-defined function (UDF) enables you to build complex logic into a single database object. A scalar
UDF is a custom function that can be called in the SELECT and WHERE clauses of an SQL statement.

Prerequisites

● You have installed the SAP HANA Interactive Education (SHINE) HCODEMOCONTENT delivery unit (DU); this
DU contains the tables and views that you want to consume with the procedure you build in this tutorial.
● You have generated data to populate the tables and views provided by the SHINE delivery unit and used in
this tutorial. You can generate the data with tools included in the SHINE delivery unit.

Note
You might have to adjust the paths in the code examples provided to suit the package hierarchy in your SAP
HANA repository, for example, to point to the underlying content (demonstration tables and services)
referenced in the tutorial.

Context

A scalar user-defined function has a list of input parameters and returns the scalar values specified in the
RETURNS <return parameter list> option defined in the SQL function, for example, decimal(15,2).
The scalar UDF named apply_discount that you create in this tutorial performs the following actions:

● Applies a discount to the stored product price

● Calculates the sale price of a product including the suggested discount

SAP HANA Developer Guide

272 PUBLIC Developing Procedures
Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the file that will contain the scalar UDF.
a. In the package where you want to create the new scalar UDF, create a new subpackage called
functions, if not already available.
b. From the context menu of the functions folder, choose New File .
c. Enter the file name apply_discount.hdbscalarfunction (remember to use
the .hdbscalarfunction extension) and choose Create.
3. Create the user-defined function.
The user-defined function (UDF) you create in this step applies a discount to the stored product price and
calculates the sale price of a product including the suggested discount.
a. In the apply_discount.hdbscalarfunction file, use the following code to define the details of the
new user-defined function. Make sure the paths point to the correct locations in your environment, for
example, the schema name, the package location for the new UDF, and the location of the demo tables
referenced in the code:

FUNCTION
"SAP_HANA_DEMO"."sap.hana.democontent.epm.functions::apply_discount"
(im_price decimal(15,2),
im_discount decimal(15,2) )
RETURNS result decimal(15,2)
LANGUAGE SQLSCRIPT
SQL SECURITY INVOKER AS
BEGIN
result := :im_price - ( :im_price * :im_discount );
END;

b. Save the changes you have made to the new scalar UDF.
c. Check the catalog to ensure the new UDF was successfully created in the correct location, for example:
Catalog.SAP_HANA_DEMO.Functions.sap.hana.democontent.epm.functions::apply_dis
count
4. Use the new UDF in an SQL select statement.

a. Open the catalog and choose (Open SQL Console).

b. To call the new UDF, enter the following SQL statement and choose (Run). Remember to modify the
paths to point to the correct locations in your environment, for example, the schema name, the
package location of the new UDF, and the location of the demo table referenced in the code.

select PRODUCTID, CATEGORY, PRICE,

"SAP_HANA_DEMO"."sap.hana.democontent.epm.functions::apply_discount"(PRICE,
0.33 )
as "SalePrice" from
"sap.hana.democontent.epm.data::EPM.MD.Products";

SAP HANA Developer Guide

Developing Procedures PUBLIC 273
5.3 Tutorial: Create a Table User-Defined Function

In SQL, a user-defined function (UDF) enables you to build complex logic into a single database object that you
can call from a SELECT statement. You can use a table user-defined function (UDF) to create a parameterized,
fixed view of the data in the underlying tables.

Prerequisites

● You have installed the SAP HANA Interactive Education (SHINE) HCODEMOCONTENT delivery unit (DU); this
DU contains the tables and views that you want to consume with the procedure you build in this tutorial.
● You have generated data to populate the tables and views provided by the SHINE delivery unit and used in
this tutorial. You can generate the data with tools included in the SHINE delivery unit.

Note
You might have to adjust the paths in the code examples provided to suit the package hierarchy in your SAP
HANA repository, for example, to point to the underlying content (demonstration tables and services)
referenced in the tutorial.

SAP HANA Developer Guide

274 PUBLIC Developing Procedures
Context

A table UDF has a list of input parameters and must return a table of the type specified in RETURNS <return-
type>. The table UDF named get_employees_by_name_filter that you create in this tutorial performs the
following actions:

● Executes a SELECT(INNER JOIN) statement against the employee and address tables
● Filters the results by performing a fuzzy search on the last name

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the file that will contain the table UDF.
a. In the package where you want to create the new table UDF, create a new subpackage called
functions, if not already available.
b. From the context menu of the functions folder, choose New File .
c. Enter the file name get_employees_by_name_filter.hdbtablefunction (remember to use
the .hdbtablefunction extension) and choose Create.
3. Define details of the user-defined function.
The user-defined function you create in this step first executes a SELECT(INNER JOIN) statement
against the employee and address tables and then filters the results by performing a fuzzy search on the
last name.
a. In the apply_discount.hdbscalarfunction file, use the following code to define the details of the
new user-defined function. Make sure the paths point to the correct locations in your environment, for
example, the schema name, the package location for the new UDF, and the location of the demo tables
referenced in the code:

FUNCTION
"SAP_HANA_DEMO"."sap.hana.democontent.epm.functions::get_employees_by_name_
filter" (lastNameFilter NVARCHAR(40))
RETURNS table ( EMPLOYEEID NVARCHAR(10),
"NAME.FIRST" NVARCHAR(40),
"NAME.LAST" NVARCHAR(40),
EMAILADDRESS NVARCHAR(255),
ADDRESSID NVARCHAR(10), CITY NVARCHAR(40),
POSTALCODE NVARCHAR(10), STREET NVARCHAR(60))
LANGUAGE SQLSCRIPT
SQL SECURITY INVOKER AS
BEGIN
RETURN
select a."EMPLOYEEID", a."NAME.FIRST",
a."NAME.LAST", a."EMAILADDRESS",
a."ADDRESSID.ADDRESSID" as "ADDRESSID", b."CITY", b."POSTALCODE",
b."STREET"
from "sap.hana.democontent.epm.data::EPM.MD.Employees"
as a
inner join
"sap.hana.democontent.epm.data::EPM.MD.Addresses"
as b

SAP HANA Developer Guide

Developing Procedures PUBLIC 275
 on a."ADDRESSID.ADDRESSID" = b.ADDRESSID
where contains("NAME.LAST", :lastNameFilter, FUZZY(0.9));
END;

b. Save the changes you have made to the new table UDF.
c. Check the catalog to ensure the new UDF was successfully created in the correct location, for example:
Catalog.SAP_HANA_DEMO.Functions.sap.hana.democontent.epm.functions::get_emplo
yees_by_name_filter
4. In the catalog, use the new UDF in an SQL select statement.
a. In the context menu of the file (for example,
sap.hana.democontent.epm.functions::get_employees_by_name_filter), choose Invoke
Function.

b. In the SQL console, enter a value for the last name filter, for example, *ll*, and choose (Run).

Sample Code
Remember to modify the paths to point to the correct locations in your environment, for example,
the schema name and the package location of the new UDF.

select * from
"SAP_HANA_DEMO"."sap.hana.democontent.epm.functions::get_employees_by_nam
e_filter"('*ll*');

The SQL result is displayed.

5.4 SQLScript Security Considerations

You can develop secure procedures using SQLScript in SAP HANA by observing the following
recommendations.

Using SQLScript, you can read and modify information in the database. In some cases, depending on the
commands and parameters you choose, you can create a situation in which data leakage or data tampering
can occur. To prevent this, SAP recommends using the following practices in all procedures.

● Mark each parameter using the keywords IN or OUT. Avoid using the INOUT keyword.
● Use the INVOKER keyword when you want the user to have the assigned privileges to start a procedure.
The default keyword, DEFINER, allows only the owner of the procedure to start it.

SAP HANA Developer Guide

276 PUBLIC Developing Procedures
● Mark read-only procedures using READS SQL DATA whenever it is possible. This ensures that the data and
the structure of the database are not altered.

Tip
Another advantage to using READS SQL DATA is that it optimizes performance.

● Ensure that the types of parameters and variables are as specific as possible. Avoid using VARCHAR, for
example. By reducing the length of variables you can reduce the risk of injection attacks.
● Perform validation on input parameters within the procedure.

Dynamic SQL

In SQLScript you can create dynamic SQL using one of the following commands: EXEC and EXECUTE
IMMEDIATE. Although these commands allow the use of variables in SQLScript where they might not be
supported. In these situations you risk injection attacks unless you perform input validation within the
procedure. In some cases injection attacks can occur by way of data from another database table.

To avoid potential vulnerability from injection attacks, consider using the following methods instead of dynamic
SQL:

● Use static SQL statements. For example, use the static statement, SELECT instead of EXECUTE
IMMEDIATE and passing the values in the WHERE clause.
● Use server-side JavaScript to write this procedure instead of using SQLScript.
● Perform validation on input parameters within the procedure using either SQLScript or server-side
JavaScript.
● Use APPLY_FILTER if you need a dynamic WHERE condition
● Use the SQL Injection Prevention Function

Escape Code

You might need to use some SQL statements that are not supported in SQLScript, for example, the GRANT
statement. In other cases you might want to use the Data Definition Language (DDL) in which some <name>
elements, but not <value> elements, come from user input or another data source. The CREATE TABLE
statement is an example of where this situation can occur. In these cases you can use dynamic SQL to create
an escape from the procedure in the code.

To avoid potential vulnerability from injection attacks, consider using the folowing methods instead of escape
code:

● Use server-side JavaScript to write this procedure instead of using SQLScript.

● Perform validation on input parameters within the procedure using either SQLScript or server-side
JavaScript.

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

SAP HANA Developer Guide

Developing Procedures PUBLIC 277
5.5 Debugging Procedures

The SAP HANA SQLScript debugger allows you to debug and analyze procedures.

In a debug session, your procedures are executed in serial mode, not in parallel (not optimized). The stored
procedure call stack appears in the debug view, allowing you to view the nested calls and test the correctness
of the procedure logic. Note that the debugger is not intended to be used for evaluating performance.

The following debug session types are available:

● Editor – Enables you to debug design-time (.hdbprocedure) objects

● Catalog - Enables you to debug design-time (.hdbprocedure) and runtime procedure objects
● External - Enables you to debug procedures that are executed by an external session

Related Information

Debug Privileges for Procedures [page 278]

Assign the DEBUG Privilege [page 279]
Assign the ATTACH DEBUGGER Privilege [page 280]
Debug Procedures [page 281]
Debug an External Session [page 284]

5.5.1 Debug Privileges for Procedures

To debug procedures, you require the DEBUG privilege. To debug procedures in an external session, you also
need the ATTACH DEBUGGER privilege.

Privilege Description Use Case

DEBUG Authorizes debug functionality on Required to debug procedures that are owned by another
a specific procedure or on the user.
(object privilege)
procedures of a specific schema.
Procedures created in the repository are owned by
It allows the user to:
_SYS_REPO and the user therefore needs to be granted the
● Set breakpoints
debug authorization.
● Display the procedure source
in the procedure viewer Procedures created directly in the catalog using the SQL
● Inspect intermediate results console are owned by the user creating them, so that user
does not require an additional debug authorization to de­
bug the procedure.

ATTACH DEBUGGER Authorizes the debugging of a Required to debug an external session belonging to a dif­
procedure called by a different ferent user. The session owner needs to grant the ATTACH
(system privilege)
user. In addition, the DEBUG privi­ DEBUGGER authorization to the user who is debugging.
lege for the corresponding proce­
dure is needed.

SAP HANA Developer Guide

278 PUBLIC Developing Procedures
Related Information

Assign the DEBUG Privilege [page 279]

Assign the ATTACH DEBUGGER Privilege [page 280]

5.5.2 Assign the DEBUG Privilege

Grant the DEBUG privilege to your user. The DEBUG privilege is required to debug procedures that are owned
by another user.

Context

Procedures created in the repository are owned by _SYS_REPO, so to debug these procedures you need to be
granted the debug authorization. You can assign the DEBUG privilege on a procedure or schema.

The steps below describe how to assign this privilege using the security tool. Note that you can also grant this
authorization from the SQL console in the catalog using either of the following statements:

CALL _SYS_REPO.GRANT_PRIVILEGE_ON_ACTIVATED_CONTENT('debug','<object>','<user>');

CALL
_SYS_REPO.GRANT_SCHEMA_PRIVILEGE_ON_ACTIVATED_CONTENT('debug','<schema>','<user>'
);

Procedure

1. Open the SAP HANA Web-based Development Workbench security tool.

The security tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/security

2. Expand the Security Users node.

3. Select your user.
4. Choose the Object Privileges tab.

5. Choose the (Add) button, select the relevant schema or procedure, and choose OK. The selected SQL
object is added to the table.
6. In the table, select the schema or procedure you just added.
A list of privileges for the object is shown.
7. Select the DEBUG option in the privileges list.

SAP HANA Developer Guide

Developing Procedures PUBLIC 279
 Note
If you want to allow other users to debug your schema or procedure, select Yes under Grantable to
Others.

8. Save your changes.

Related Information

Debug Privileges for Procedures [page 278]

SAP HANA Web-Based Development Workbench [page 7]

5.5.3 Assign the ATTACH DEBUGGER Privilege

Grant the ATTACH DEBUGGER privilege to another user to allow them to debug procedures in your sessions.

Context

The steps below describe how to assign the ATTACH DEBUGGER privilege using the security tool. Note that you
can also grant this authorization from the SQL console in the catalog using the following statement:

GRANT ATTACH DEBUGGER TO <user>;

Note
The user also needs the object privilege DEBUG on the relevant procedure.

Procedure

1. Open the SAP HANA Web-based Development Workbench security tool.

The security tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/security

2. Expand the Security Users node.

3. Select the user you want to grant the privilege to.
4. Choose the Privileges on Users tab.

5. Choose the (Add) button. Your user name is added to the table.
6. Select the ATTACH DEBUGGER option and save your changes.

SAP HANA Developer Guide

280 PUBLIC Developing Procedures
Related Information

Debug Privileges for Procedures [page 278]

SAP HANA Web-Based Development Workbench [page 7]

5.5.4 Debug Procedures

You can debug and analyze SQLScript procedures in the editor or catalog of the SAP HANA Web-based
Development Workbench.

Procedure

1. Open the SAP HANA Web-based Development Workbench editor or catalog.

Option URL

Editor http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor

Catalog http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/catalog

2. Get the current debug token.

When working in different browser windows (for example, editor and catalog), one of the browsers might
already be attached to the SQL debugger. By applying the current debug token you can attach the SQL
debugger to your current browser session.

a. Choose (Settings) in the toolbar.

b. Editor only: Switch to the SQL Debugger tab.
c. Select the Select a Debug Token radio button.
d. To enter the debug token, choose Get Current Debug Token.
e. Apply your changes.

Note
If the debugger is bound to another browser, you can also detach it, that is, release the debugger, by
refreshing your current browser.

Tip
When you work in different browsers (Chrome and Firefox, for example), each browser debugs
separately. To invoke a procedure in your current browser and debug it in another one, get the debug
token of your current browser and apply it in the other browser. Note that you might have to refresh your
current browser before giving the debug token to the other browser.

3. Open a procedure.

SAP HANA Developer Guide

Developing Procedures PUBLIC 281
 Option Description

Editor In the Content tree, select the procedure to open it in the code editor.

Catalog In the catalog, expand the <schema> Procedures node and select the procedure.

The source code appears in the stored procedure viewer. It is read-only but you can set break­
points.

4. Add breakpoints in the source code.

Set a breakpoint in front of a code line by clicking the line number, as shown in the example below:

5. Start a debug session.

a. In the toolbar, choose (Invoke Procedure).

The SQL editor opens.
b. Enter values for any input parameters.

Note
For scalar types, insert a value. For table types, enter the name of a catalog table
(schema.tablename) that contains the relevant input. For example, SYS.USERS.

c. Choose (Run) in the toolbar.

The debug session begins and the SQL debug browser opens on the right, showing the status of the
session. The debugger will stop at the first breakpoint and the session will be suspended until you resume
it.

You can see a list of all of the breakpoints on the Breakpoints tab. From the Breakpoints tab, you can:
○ Disable specific breakpoints or disable all of them.
○ Remove specific breakpoints or remove all of them.
○ Click a breakpoint to see which line it belongs to in the source code.
6. Add an expression.

a. Choose (Toggle Expression Editor) or choose Add Expression from the context menu of a variable
you want to investigate further.

SAP HANA Developer Guide

282 PUBLIC Developing Procedures
 The Expression Editor opens.
b. Edit the expression.

The following types of SQL expression are supported:

SQL Expression Example

Variable name v_index1

<expression> <operator> <expression> v_index1 + v_index2

v_msg || 'ABCD'

Condition expression v_index1 > 0 -> return 0 (false) or 1 (true)

Function expression substr(v_msg, 2)

Aggregate expression select COUNT(*) from msgtable

select SUM(T.amount) from msgtable T

Column name msgtable.amount

<table_variable>.<column_name> select * from <table_variable>

c. Press ENTER .
The expression is now listed under the Expressions node.

7. Choose (Resume) or (Step over) to step through the code execution.

Option Description

(Resume) Continues execution to the next breakpoint

(Step over) Steps through the code line-by-line

You can evaluate your local scalar and table variables in the top pane under the Variables node. It shows the
values of the scalar variables and the number of rows in each table.

Under the Expressions node, you can see the values of the expressions you added. To view the content of
tables, choose Display Content from the context menu of the expression. The results are shown on the
Expression Result tab.

8. View the content of the tables listed under the Variables node.
Select a table and from the context menu choose Display Content. The results are shown on a separate tab
named according to the table.

Results

The debug session is terminated when the procedure run has finished.

SAP HANA Developer Guide

Developing Procedures PUBLIC 283
5.5.5 Debug an External Session

You can execute procedures in the SAP HANA studio and debug and analyze them in the SAP HANA Web-
based Development Workbench using an external session.

Prerequisites

You have been assigned the DEBUG authorization for the procedure or associated schema.

Procedure

1. In the SAP HANA studio, get the details you need to set up an external session.
External sessions can be set up through a connection ID or HANA user (including, optionally, an application
user).

Option Description

Connec­ To get the connection ID, open the SQL console and execute the following statement:
tion ID
SELECT SESSION_CONTEXT('CONN_ID') FROM DUMMY;

HANA This is your SAP HANA database user. You can optionally set an application user, which can be used as an
user additional filter attribute.

To set an application user, open the SQL console and execute the following statement, replacing <applica­
tion user name> with the appropriate value:

SET 'APPLICATIONUSER'='<application user name>';

To check the application user has been set correctly, execute the following statement:

SELECT SESSION_CONTEXT('APPLICATIONUSER') FROM DUMMY;

2. In the SAP HANA Web-based Development Workbench editor or catalog, set up the external debug
session.

a. In the toolbar, choose (Settings).

b. Editor only: Switch to the SQL Debugger tab.
c. In the dialog box, select one of the following options:

Option Description

Select a Connection Enter the connection ID you obtained in step 1.

Set Filter Attribute Enter the SAP HANA user (this is your SAP HANA database user) and, op­
tionally, an application user, if you set an application user in step 1.

d. Apply your changes.

SAP HANA Developer Guide

284 PUBLIC Developing Procedures
 An external session is attached for the specified connection or SAP HANA user.

3. Open the procedure.

Option Description

Editor In the Content tree, select the procedure to open it in the code editor.

Catalog In the catalog, expand the <schema> Procedures node and select the procedure.

The source code appears in the stored procedure viewer. It is read-only but you can set break­
points.

4. Add breakpoints in the source code.

Click the line numbers of the source code to set breakpoints.
5. Start the debug session.
In the SAP HANA studio, call the procedure from the SQL console.
The debug session begins and the SQL debug browser opens in the SAP HANA Web-based Development
Workbench, showing the status of the session. The debugger will stop at the first breakpoint and the
session will be suspended until you resume it.

Results

The debug session is terminated when the procedure run has finished.

SAP HANA Developer Guide

Developing Procedures PUBLIC 285
6 Defining Web-based Data Access

SAP HANA extended application services (SAP HANA XS) provide applications and application developers with
access to the SAP HANA database using a consumption model that is exposed via HTTP.

In addition to providing application-specific consumption models, SAP HANA XS also host system services that
are part of the SAP HANA database, for example: search services and a built-in Web server that provides
access to static content stored in the SAP HANA repository.

The consumption model provided by SAP HANA XS focuses on server-side applications written in JavaScript
and making use of a powerful set of specially developed API functions. However, you can use other methods to
provide access to the data you want to expose in SAP HANA. For example, you can set up an ODATA service or
use the XML for Analysis (XMLA) interface to send a Multi-dimensional Expressions (MDX) query. This section
describes how to set up a service that enables you to expose data using OData or XMLA.

6.1 Data Access with OData in SAP HANA XS

In SAP HANA Extended Application Services (SAP HANA XS), the persistence model (for example, tables,
views, and stored procedures) is mapped to the consumption model that is exposed to clients - the
applications you write to extract data from the SAP HANA database.

You can map the persistence and consumption models with the Open Data Protocol (OData), a resource-based
Web protocol for querying and updating data. An OData application running in SAP HANA XS is used to provide
the consumption model for client applications exchanging OData queries with the SAP HANA database.

Note
SAP HANA XS currently supports OData version 2.0, which you can use to send OData queries (for example,
using the HTTP GET method). Language encoding is restricted to UTF-8.

You can use OData to enable clients to consume authorized data stored in the SAP HANA database. OData
defines operations on resources using RESTful HTTP commands (for example, GET, PUT, POST, and DELETE)
and specifies the URI syntax for identifying the resources. Data is transferred over HTTP using either the Atom
(XML) or the JSON (JavaScript) format.

Note
For modification operations, for example, CREATE, UPDATE, and DELETE, SAP HANA XS supports only the
JSON format (“content-type: application/json”).

Applications running in SAP HANA XS enable accurate control of the flow of data between the presentational
layer, for example, in the Browser, and the data-processing layer in SAP HANA itself, where the calculations are
performed, for example, in SQL or SQLScript. If you develop and deploy an OData service running in SAP HANA
XS, you can take advantage of the embedded access to SAP HANA that SAP HANA XS provides; the embedded
access greatly improves end-to-end performance.

SAP HANA Developer Guide

286 PUBLIC Defining Web-based Data Access
6.1.1 OData in SAP HANA XS

OData is a resource-based web protocol for querying and updating data. OData defines operations on
resources using HTTP commands (for example, GET, PUT, POST, and DELETE) and specifies the uniform
resource indicator (URI) syntax to use to identify the resources.

Data is transferred over HTTP using the Atom or JSON format:

Note
OData makes it easier for SAP, for partners, and for customers to build standards-based applications for
many different devices and on various platforms, for example, applications that are based on a lightweight
consumption of SAP and non-SAP business application data.

The main aim of OData is to define an abstract data model and a protocol which, combined, enable any client
to access data exposed by any data source. Clients might include Web browsers, mobile devices, business-
intelligence tools, and custom applications (for example, written in programming languages such as PHP or
Java); data sources can include databases, content-management systems, the Cloud, or custom applications
(for example, written in Java).

The OData approach to data exchange involves the following elements:

● OData data model

Provides a generic way to organize and describe data. OData uses the Entity 1 Data Model (EDM).
● OData protocol
Enables a client to query an OData service. The OData protocol is a set of interactions, which includes the
usual REST-based create, read, update, and delete operations along with an OData-defined query
language. The OData service sends data in either of the following ways:
○ XML-based format defined by Atom/AtomPub
○ JavaScript Object Notation (JSON)
● OData client libraries
Enables access to data via the OData protocol. Since most OData clients are applications, pre-built libraries
for making OData requests and getting results reduces and simplifies work for the developers who create
those applications.
A broad selection of OData client libraries are already widely available, for example: Android, Java,
JavaScript, PHP, Ruby, and the best known mobile platforms.
● OData services
Exposes an end point that allows access to data in the SAP HANA database. The OData service
implements the OData protocol (using the OData Data Services runtime) and uses the Data Access layer to
map data between its underlying form (database tables, spreadsheet lists, and so on) and a format that the
requesting client can understand.

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 287
6.1.2 Tutorial: Use the SAP HANA OData Interface

In this tutorial, you create a simple OData service that exposes a SAP HANA database table as an OData
collection so that it can be analyzed and displayed by client applications.

Prerequisites

You have the privileges granted by the role sap.hana.ide.roles::EditorDeveloper; this role is included in the
parent role sap.hana.ide.roles::Developer.

Context

SAP HANA Extended Application Services allows you to create OData services without needing to perform
server side coding. To create an OData service from an existing HANA table (or view), you define a service
definition file with the suffix .xsodata.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the OData application, for example, helloodata.
a. Select the Content folder and from the context menu choose Create Application.
b. In the Package field, enter the name of the application root package, for example, helloodata.
c. Choose the Empty application (with XSAccess and XSApp) template and then choose
Create.
The index.html, .xsaccess, and .xsapp files are created and listed under the newly added
helloodata package.
d. Optionally delete the automatically created index.html file.
3. Create a schema, for example, HELLO_ODATA.hdbschema.
The schema is required for the table that contains the data to be exposed by your OData service definition.
The schema is defined in a flat file with the file extension .hdbschema.

a. Select the helloodata package and from the context menu choose New File .
b. Enter the file name HELLO_ODATA.hdbschema and choose Create.
c. Enter the following code in the HELLO_ODATA.hdbschema file:

schema_name="HELLO_ODATA";

d. Save the file.

SAP HANA Developer Guide

288 PUBLIC Defining Web-based Data Access
4. Create the database table that contains the data to be exposed by your OData service definition, for
example, otable.hdbtable.

a. Select the helloodata package and from the context menu choose New File .
b. Enter the file name otable.hdbtable and choose Create.
c. Enter the following code in the otable.hdbtable file:

table.schemaName = "HELLO_ODATA";
table.tableType = COLUMNSTORE;
table.columns = [
{name = "Col1"; sqlType = VARCHAR; nullable = false; length = 20;
comment = "dummy comment";},
{name = "Col2"; sqlType = INTEGER; nullable = false;},
{name = "Col3"; sqlType = NVARCHAR; nullable = true; length = 20;
defaultValue = "Defaultvalue";},
{name = "Col4"; sqlType = DECIMAL; nullable = false; precision = 12;
scale = 3;}];
table.primaryKey.pkcolumns = ["Col1", "Col2"];

d. Save the file.

5. Assign schema execution authorization to your user.
After activation in the repository, a schema object is only visible in the catalog to the _SYS_REPO user. To
enable other users, for example the schema owner, to view the newly created schema and the objects it
contains, you must grant the user the required SELECT privilege for the schema object.
To grant schema privileges to yourself:
a. Select the HELLO_ODATA.hdbschema file.

b. Choose (Assign execution authorization).

You are assigned the requested schema privileges (by default, EXECUTE, SELECT, INSERT, UPDATE,
and DELETE).
6. Create an OData service-definition file.
The OData service-definition file has the file extension .xsodata, for example, hello.xsodata and must
be located in the root package of the OData application:

a. Select the helloodata package and from the context menu choose New File .
b. Enter the file name hello.xsodata and choose Create.
c. Enter the following code in the hello.xsodata file:

service {
"helloodata::otable";
}

d. Save the OData service definition file.

7. To test the new OData service, select the hello.xsodata file and choose (Run).
The root URI of the OData service is passed to a new browser tab and an HTTP request executed.
The correctly addressed URI returns the list of resources exposed by the OData service, as shown below. In
this example, an entity set otable has been created for the table defined in the hdbtable file
helloodata:otable.hdbtable. The default name of the entity set is the name of the repository object
file, here "otable":

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 289
 Note
You can view the same output as above in JSON format by appending the parameter format=json to
the URL: hello.xsodata/?$format=json

The JSON output would then be:

{ "d": { "EntitySets": ["otable"] } }

8. To view the details of the data model used by the OData service, add the /$metadata parameter to the
end of the URL and refresh your browser window.
The field descriptions for all the attributes of the OData service are now shown in the generated metadata
document, as can be seen in the example below. All information about the table, such as its properties,
data types, and primary key, is obtained from the database catalog:

9. Use the OData Explorer to test the service.

SAP HANA Developer Guide

290 PUBLIC Defining Web-based Data Access
 The OData Explorer is a tool that enables you to test or simulate a backend XS OData service and ensure
that the fields are correctly exposed and that it functions correctly.
a. In the Editor, select the hello.xsodata file and from the context menu choose Open OData Explorer.
In the entities pane on the left, you can see the otable entity.
b. Select the entity to display its details in the work area pane on the right.
c. Choose + to add a row of data manually, as shown in the example below, and choose Create:

Col1 test1

Col2 1

Col3 value 1

Col4 1.1

d. Choose Generate Data to create a set of test data based on random and/or fixed values. Specify the
number of rows you want to create and choose Generate.

10. View the data of the entity.

In the browser, add the parameter /otable?$format=xml to the URL and refresh the browser window.
You can now see the test data you created in the otable table (the example below shows the first row of
data you added manually):

Results

You have successfully exposed the database entity as an OData service by means of SAP HANA extended
applications services and tested it directly within a browser. You now have a functional OData service that can
be called by an application, typically from within a Web page.

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 291
6.1.3 Define the Data an OData Service Exposes

An OData service exposes data stored in database tables or views as OData collections for analysis and display
by client applications. However, first of all, you need to ensure that the tables and views to expose as an OData
collection actually exist.

Procedure

1. Create a simple database table to expose with an OData service.

2. Create a simple database view to expose with an OData service.
This step is optional; you can expose tables directly. In addition, you can create a modeling view, for
example, analytic, attribute, or calculation.
3. Grant select privileges to the tables and views to be exposed with the OData service.
After activation in the repository, schema and tables objects are only visible in the catalog to the
_SYS_REPO user. To enable other users, for example the schema owner, to view the newly created schema
in the catalog, you must grant the user the required SELECT privilege.

call
_SYS_REPO.GRANT_SCHEMA_PRIVILEGE_ON_ACTIVATED_CONTENT('select','<SCHEMANAME>',
'<username>');

6.1.4 Create an OData Service Definition

The OData service definition is a configuration file you use to specify which data (for example, views or tables)
is exposed as an OData collection for analysis and display by client applications.

Prerequisites

You have defined the data to expose with the OData application, for example, at least the following:

● A database schema
● A database table

Context

An OData service for SAP HANA XS is defined in a text file with the file extension .xsodata, for example,
OdataSrvDef.xsodata. The file resides in the package hierarchy of the OData application and must contain
at least the entry service {}, which would generate an operational OData service with an empty service catalog
and an empty metadata file.

SAP HANA Developer Guide

292 PUBLIC Defining Web-based Data Access
Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the file that will contain your OData service definition:
a. From the context menu of the package where you want to create the new OData service-definition file,
choose New File .

Note
The file containing the OData service definition must be placed in the root package of the OData
application for which the service is intended.

b. Enter a file name with the file extension .xsodata, for example, OdataSrvDef.xsodata, and choose
Create.
3. Define the OData service.
The OData service definition uses the OData Service Definition Language (OSDL), which includes a list of
keywords that you specify in the OData service-definition file to enable important features.

Note
The XS OData editor will detect syntax errors, highlight keywords, and provide code assistance.

The following example shows a simple OData service definition exposing a simple table:

service namespace "my.namespace" {

"sample.odata::table" as "MyTable";
}

This service definition exposes a table defined in the file sample.odata:table.hdbtable and creates
an EntitySet for this entity named MyTable. The specification of an alias is optional. If omitted, the default
name of the EntitySet is the name of the repository object file, in this example, table.
4. Save the OData service definition.

Tip

To run an OData service, select the OData service file and choose (Run).

Related Information

Define the Data an OData Service Exposes [page 292]

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 293
6.1.5 OData Service Definitions

The OData service definition is the mechanism you use to define what data to expose with OData, how, and to
whom. Data exposed as an OData collection is available for analysis and display by client applications, for
example, a browser that uses functions provided by an OData client library running on the client system.

To expose information by means of OData to applications using SAP HANA XS, you must define database views
that provide the data with the required granularity. Then you create an OData service definition, which is a file
you use to specify which database views or tables are exposed as OData collections.

Note
SAP HANA XS supports OData version 2.0, which you can use to send OData queries (for example, using the
HTTP GET method). Language encoding is restricted to UTF-8.

An OData service for SAP HANA XS is defined in a text file with the file suffix .xsodata, for example,
OdataSrvDef.xsodata. The file must contain at least the entry service {}, which would generate a
completely operational OData service with an empty service catalog and an empty metadata file. However,
usually you use the service definition to expose objects in the database catalog, for example: tables, SQL views,
or calculation rules.

In the OData service-definition file, you can use the following ways to name the SAP HANA objects you want to
expose by OData:

Note
The syntax to use in the OData service-definition file to reference objects depends on the object type, for
example, repository (design-time) or database catalog (runtime).

● Repository objects
Expose an object using the object's repository (design-time) name in the OData service-definition file. This
method of exposing database objects using OData enables the OData service to be automatically updated
if the underlying repository object changes. Note that a design-time name can be used to reference
analytic and calculation views; it cannot be used to reference SQL views. The following example shows how
to include a reference to a table in an OData service definition using the table's design-time name.

service {
"acme.com.odata::myTable" as "myTable";
}

Note
Calculation views are only accessible from within xsodata files by referring to the design-time name.
However, it is recommended to use design-time names whenever possible for calculation views or
common tables. With design-time names, the cross references are recreated during activation (for
example, for where-used), which means changes are visible automatically.

● Database objects
Expose an object using the object's database catalog (runtime) name. The support for database objects is
mainly intended for existing or replicated objects that do not have a repository design-time representation.

SAP HANA Developer Guide

294 PUBLIC Defining Web-based Data Access
 The following example shows how to include a reference to a table in an OData service definition using the
table's runtime name.

service {
"mySchema"."myTable" as "MyTable";
}

Note
It is strongly recommended not to use catalog (runtime) names in an OData service-definition. The use
of catalog object names is only enabled in a service-definition because some objects do not have a
design-time name. If at all possible, use the design-time name to reference objects in an OData service-
definition file.

By default, all entity sets and associations in an OData service are writeable, that is they can be modified with a
CREATE, UPDATE, or DELETE requests. However, you can prevent the execution of a modification request by
setting the appropriate keyword (create, update, or delete) with the forbidden option in the OData service
definition. The following example of an OData service definition for SAP HANA XS shows how to prevent any
modification to the table myTable that is exposed by the OData service. Any attempt to make a modification to
the indicated table using a CREATE, UPDATE, or DELETE request results in the HTTP response status 403
FORBIDDEN.

service {
“sap.test::myTable”
create forbidden
update forbidden
delete forbidden;
}

For CREATE requests, for example, to add a new entry to either a table or an SQL view exposed by an OData
service, you must specify an explicit key (not a generated key); the key must be included in the URL as part of
the CREATE request. For UPDATE and DELETE requests, you do not need to specify the key explicitly (and if
you do, it will be ignored); the key is already known, since it is essential to specify which entry in the table or
SQL view must be modified with the UPDATE or DELETE request.

Note
Without any support for IN/OUT table parameters in SQLScript, it is not possible to use a sequence to
create an entry in a table or view exposed by an OData service. However, you can use XS JavaScript exits to
update a table with a generated value.

Related Information

Tutorial: Creating a Modification Exit with XS JavaScript [page 317]

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 295
6.1.5.1 OData Service-Definition Type Mapping

During the activation of the OData service definition, SQL types defined in the service definition are mapped to
EDM types according to a mapping table.

For example, the SQL type "Time" is mapped to the EDM type "EDM.Time"; the SQL type "Decimal" is mapped
to the EDM type "EDM.Decimal"; the SQL types "Real" and "Float" are mapped to the EDM type
"EDM.Single".

Note
The OData implementation in SAP HANA Extended Application Services (SAP HANA XS) does not support
all SQL types.

In the following example, the SQL types of columns in a table are mapped to the EDM types in the properties of
an entity type.

{name = "ID"; sqlType = INTEGER; nullable = false;}, {name = "RefereeID";

sqlType = VARCHAR; nullable = true;}

<Property Name="ID" Type="Edm.Int32" Nullable="false"/> <Property

Name="RefereeID" Type="Edm.String" Nullable="true"/>

Related Information

OData Service Definition: SQL-EDM Type Mapping (XS Advanced) [page 321]
OData Service Definitions [page 294]

6.1.5.2 OData Service-Definition Features

The OData service definition provides a list of keywords that you use in the OData service-definition file to
enable important features. For example, the following list illustrates the most-commonly used features used in
an OData service-definition and, where appropriate, indicates the keyword to use to enable the feature:

● Aggregation
The results of aggregations on columns change dynamically, depending on the grouping conditions. As a
result, aggregation cannot be done in SQL views; it needs to be specified in the OData service definition
itself. Depending on the type of object you want to expose with OData, the columns to aggregate and the
function used must be specified explicitly (explicit aggregation) or derived from metadata in the database
(derived aggregation). Note that aggregated columns cannot be used in combination with the $filter
query parameter, and aggregation is only possible with generated keys.
● Association
Define associations between entities to express relationships between entities. With associations it is
possible to reflect foreign key constraints on database tables, hierarchies and other relations between
database objects.

SAP HANA Developer Guide

296 PUBLIC Defining Web-based Data Access
● Key Specification
The OData specification requires an EntityType to denote a set of properties forming a unique key. In SAP
HANA, only tables can have a unique key, the primary key. All other (mostly view) objects require you to
specify a key for the entity. The OData service definition language (OSDL) enables you to do this by
denoting a set of existing columns or by generating a local key. Bear in mind that local keys are transient;
they exist only for the duration of the current session and cannot be dereferenced.

Note
OSDL is the language used to define a service definition; the language includes a list of keywords that
you use in the OData service-definition file to enable the required features.

● Parameter Entity Sets

You can use a special parameter entity set to enter input parameters for SAP HANA calculation views and
analytic views. During activation of the entity set, the specified parameters are retrieved from the
metadata of the calculation (or analytical) view and exposed as a new EntitySet with the name suffix
"Parameters", for example "CalcViewParameters".
● Projection
If the object you want to expose with an OData service has more columns than you actually want to expose,
you can use SQL views to restrict the number of selected columns in the SELECT. However, for those cases
where SQL views are not appropriate, you can use the with or without keywords in the OData service
definition to include or exclude a list of columns.

Related Information

OData Service-Definition Examples [page 297]

6.1.6 OData Service-Definition Examples

The OData service definition describes how data exposed in an end point can be accessed by clients using the
OData protocol.

Each of the examples listed below is explained in a separate section. The examples show how to use the OData
Service Definition Language (OSDL) in the OData service-definition file to generate an operational OData
service that enables clients to use SAP HANA XS to access the OData end point you set up.

● Empty Service
● Namespace Definition
● Object Exposure
● Property Projection
● Key Specification
● Associations
● Aggregation
● Parameter Entity Sets
● ETag Support

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 297
● Nullable Properties

6.1.6.1 OData Empty Service

An OData service for SAP HANA XS is defined by a text file containing at least the following line:

Service definition sample.odata:empty.xsodata

service {}

A service file with the minimal content generates an empty, completely operational OData service with an
empty service catalog and an empty metadata file:

Note
● Examples and graphics are provided for illustration pusrposes only; some URLs may differ from the
ones shown.

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata

{
"d" : {
"EntitySets" : []
}
}

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata/$metadata

An empty service metadata document consists of one Schema containing an empty EntityContainer. The
name of the EntityContainer is the name of the .xsodata file, in this example "empty".

6.1.6.2 OData Namespace Definition

Every .xsodata file must define it's own namespace by using the namespace keyword:

SAP HANA Developer Guide

298 PUBLIC Defining Web-based Data Access
Service definition sample.odata:namespace.xsodata

service namespace "my.namespace" {}

The resulting service metadata document has the specified schema namespace:

Note
Examples and graphics are provided for illustration pusrposes only; some URLs may differ from the ones
shown.

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata/$metadata

6.1.6.3 OData Object Exposure

In the examples provided to illustrate object exposure, the following definition of a table applies:

Table definition sample.odata:table.hdbtable

COLUMN TABLE "sample.odata::table" (

"ID" INTEGER,
"Text" NVARCHAR(1000),
"Time" TIMESTAMP,
PRIMARY KEY ("ID")
);

Database Objects

Similar to the exposure of an object by using the repository design-time name is the exposure by the database
name:

Service definition sample.odata:db.xsodata

service {
"sample.odata::table" as "MyTable";
}

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 299
The service exposes the same table by using the database catalog name of the object and the name of the
schema where the table is created in.

6.1.6.4 OData Property Projection

If the object you want to expose with an OData service has more columns than you actually want to expose, you
can use SQL views to restrict the number of selected columns in the SELECT.

Nevertheless, SQL views are sometimes not appropriate, for example with calculation views, and for these
cases we provide the possibility to restrict the properties in the OData service definition in two ways. By
providing an including or an excluding list of columns.

Including Properties

You can specify the columns of an object that have to be exposed in the OData service by using the with
keyword. Key fields of tables must not be omitted.

Service definition sample.odata:with.xsodata

service {
"sample.odata::table" as "MyTable" with ("ID","Text");
}

The resulting EntityType then contains only the properties derived from the specified columns:

Note
Examples and graphics are provided for illustration pusrposes only; some URLs may differ from the ones
shown.

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata/$metadata

Excluding Properties

The opposite of the with keyword is the without keyword, which enables you to specify which columns you
do NOT want to expose in the OData service:

SAP HANA Developer Guide

300 PUBLIC Defining Web-based Data Access
Service definition sample.odata:without.xsodata

service {
"sample.odata::table" as "MyTable" without ("Text","Time");
}

The generated EntityType then does NOT contain the properties derived from the specified columns:

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata/$metadata

6.1.6.5 OData Key Specification

The OData specification requires an EntityType to denote a set properties forming a unique key. In HANA
only tables may have a unique key, the primary key. For all other (mostly view) objects you need to specify a key
for the entity.

In OSDL, you can specify a key for an entity/object by denoting a set of existing columns or by generating a key.

Note
Key attributes are not evaluated.

For the examples illustrating key specification, we use the following SQL view, which selects all data from the
specified table.

View definition sample.odata:view.hdbview

{
VIEW "sample.odata::view" as select * from "sample.odata::table"
}

Existing Key Properties

If the object has set of columns that may form a unique key, you can specify them as key for the entity. These
key properties are always selected from the database, no matter if they are omitted in the $select query
option. Therefore explicit keys are not suitable for calculation views and analytic views as the selection has an
impact on the result.

Service definition sample.odata:explicitkeys.xsodata/$metadata

service {
"sample.odata::view" as "MyView" key ("ID","Text");

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 301
 }

The metadata document for the exposure of the view above is almost equal to the metadata document for
repository objects. Only the key is different and consists now of two columns:

Note
Examples and graphics are provided for illustration pusrposes only; some URLs may differ from the ones
shown.

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata/$metadata

Caution
The OData infrastructure cannot check whether your specified keys are unique, so be careful when choosing
keys.

Generated Local Key

For objects that do not have a unique key in their results, for example, calculation views or aggregated tables,
you can generate a locally valid key. This key value numbers the results starting with 1 and is not meant for
dereferencing the entity; you cannot use this key to retrieve the entity. The key is valid only for the duration of
the current session and is used only to satisfy OData's need for a unique ID in the results. The property type of
a generated local key is Edm.String and cannot be changed.

SAP HANA Developer Guide

302 PUBLIC Defining Web-based Data Access
Service definition sample.odata:generatedkeys.xsodata

service {
"sample.odata::view" as "MyView" key generate local "GenID";
}

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata/$metadata

As a consequence of the transient nature of generated local keys, it is not possible to define navigation
properties on these entities or use them in filter or order by conditions.

6.1.6.6 OData Associations

You can define associations between entities to express relationships between entities. With associations it is
possible to reflect foreign key constraints on database tables, hierarchies and other relations between
database objects. OSDL supports simple associations, where the information about the relationship is stored
in one of the participating entities, and complex associations, where the relationship information is stored in a
separate association table.

Associations themselves are freestanding. On top of them you can specify which of the entities participating in
the relationship can navigate over the association to the other entity by creating NavigationPropertys.

For the examples used to illustrate OData associations, we use the tables customer and order:

Table definition: sample.odata:customer.hdbtable

COLUMN TABLE "sample.odata::customer" (

"ID" INTEGER NOT NULL,
"OrderID" INTEGER,
PRIMARY KEY ("ID")
);

Table definition: sample.odata:order.hdbtable

COLUMN TABLE "sample.odata::order" (

"ID" INTEGER NOT NULL,
"CustomerID" INTEGER,
PRIMARY KEY ("ID")
);

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 303
There is one relationship order.CustomerID to customer.ID.

Simple Associations

The definition of an association requires you to specify a name, which references two exposed entities and
whose columns keep the relationship information. To distinguish the ends of the association, you must use the
keywords principal and dependent. In addition, it is necessary to denote the multiplicity for each end of the
association.

Service definition: sample.odata:assocsimple.xsodata

service {
"sample.odata::customer" as "Customers";
"sample.odata::order" as "Orders";
association "Customer_Orders" with referential constraint principal
"Customers"("ID") multiplicity "1" dependent "Orders"("CustomerID") multiplicity
"*";
}

The association in the example above with the name Customer_Orders defines a relationship between the
table customer, identified by its EntitySet name Customers, on the principal end, and the table order,
identified by its entity set name Orders, on the dependent end. Involved columns of both tables are denoted
in braces ({}) after the name of the corresponding entity set. The multiplicity keyword on each end of the
association specifies their cardinality - in this example, one-to-many.

The with referential constraint syntax ensures that the referential constraint check is enforced at
design time, for example, when you activate the service definition in the SAP HANA repository. The referential
constraint information appears in the metadata document.

Note
SAP strongly recommends that you use the with referential constraint syntax.

The number of columns involved in the relationship must be equal for both ends of the association, and their
order in the list is important. The order specifies which column in one table is compared to which column in the
other table. In this simple example, the column customer.ID is compared to order.CustomerID in the
generated table join.

As a result of the generation of the service definition above, an AssociationSet named Customer_Orders
and an Association with name Customer_OrdersType are generated:

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata/$metadata

SAP HANA Developer Guide

304 PUBLIC Defining Web-based Data Access
The second association is similar to the first one and is shown in the following listing:

association "Customer_Recruit" with referential constraint principal

"Customers"("ID") multiplicity "1" dependent "Customers"("RecruitID")
multiplicity "*";

Complex Associations

For the following example of a complex association, an additional table named knows is introduced that
contains a relationship between customers.

Table definition: sample.odata:knows.hdbtable

COLUMN TABLE "sample.odata::knows" (

"KnowingCustomerID" INTEGER NOT NULL,
"KnowCustomerID" INTEGER NOT NULL,
PRIMARY KEY ("KnowingCustomerID","KnowCustomerID")
);

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 305
Relationships that are stored in association tables such as knows can be similarly defined as simple
associations. Use the keyword over to specify the additional table and any required columns.

Service definition: sample.odata:assoccomplex.xsodata

service {
"sample.odata::customer" as "Customers";
"sample.odata::order" as "Orders";
association "Customer_Orders"
principal "Customers"("ID") multiplicity "*"
dependent "Customers"("ID") multiplicity "*"
over "sample.odata::knows" principal ("KnowingCustomerID") dependent
("KnownCustomerID");
}

With the keywords principal and dependent after over you can specify which columns from the
association table are joined with the principal respectively dependent columns of the related entities. The
number of columns must be equal in pairs, and their order in the list is important.

The generated Association in the metadata document is similar to the one created for a simple association
except that the ReferentialConstraint is missing:

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata/$metadata

Navigation Properties

By only defining an association, it is not possible to navigate from one entity to another. Associations need to
be bound to entities by a NavigationProperty. You can create them by using the keyword navigates:

Service definition: sample.odata:assocnav.xsodata

service {
"sample.odata::customer" as "Customers" navigates ("Customer_Orders" as
"HisOrders");
"sample.odata::order" as "Orders";
association "Customer_Orders" principal "Customers"("ID") multiplicity "1"
dependent "Orders"("CustomerID") multiplicity "*";
}

The example above says that it is possible to navigate from Customers over the association Customer_Order
via the NavigationProperty named "HisOrders".

SAP HANA Developer Guide

306 PUBLIC Defining Web-based Data Access
The right association end is determined automatically by the entity set name. But if both ends are bound to the
same entity, it is necessary to specify the starting end for the navigation. This is done by specifying either from
principal or from dependent which refer to the principal and dependent ends in the association.

Service definition: sample.odata:assocnavself.xsodata

service {
"sample.odata::customer" as "Customers"
navigates ("Customer_Orders" as "HisOrders","Customer_Recruit" as
"Recruit" from principal);
"sample.odata::order" as "Orders";
association "Customer_Orders" principal "Customers"("ID") multiplicity "1"
dependent "Orders"("CustomerID") multiplicity "*";
association "Customer_Recruit" principal "Customers"("ID") multiplicity
"1" dependent "Customers"("RecruitID") multiplicity "*";
}

In both cases a NavigationProperty is added to the EntityType.

http://<myHANAServer>:<port>/odata/services/<myService>.xsodata/$metadata

6.1.6.7 OData Aggregation

The results of aggregations on columns change dynamically depending on the grouping conditions. This means
that aggregation cannot be performed in SQL views; it needs to be specified in the OData service definition
itself. Depending on the type of object to expose, you need to explicitly specify the columns to aggregate and
the function to use or derived them from metadata in the database.

In general, aggregations do not have consequences for the metadata document. It just effects the semantics of
the concerning properties during runtime. The grouping condition for the aggregation contain all selected non-
aggregated properties. Furthermore, aggregated columns cannot be used in $filter, and aggregation is only
possible with generated keys.

Derived Aggregation

The simplest way to define aggregations of columns in an object is to derive this information from metadata in
the database. The only objects with this information are calculation views and analytic views. For all other

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 307
object types, for example, tables and SQL views, the activation will not work. To cause the service to use
derived information, you must specify the keywords aggregates always, as illustrated in the following example:

service {
"sample.odata::calc" as "CalcView"
keys generate local "ID"
aggregates always;
}

Explicit Aggregation

The example for the explicit aggregation is based on the following table definition:
sample.odata:revenues.hdbtable

COLUMN TABLE "sample.odata::revenues" (

"Month" INTEGER NOT NULL,
"Year" INTEGER NOT NULL,
"Amount" INTEGER,
PRIMARY KEY ("Month","Year")
);

You can aggregate the columns of objects (without metadata) that are necessary for the derivation of
aggregation by explicitly denoting the column names and the functions to use, as illustrated in the following
example of a service definition: sample.odata:aggrexpl.xsodata

service {
"sample.odata::revenues" as "Revenues"
keys generate local "ID"
aggregates always (SUM of "Amount");
}

The results of the entity set Revenues always contain the aggregated value of the column Amount. To extract
the aggregated revenue amount per year, add $select=Year,Amount to your requested URI.

6.1.6.8 OData Parameter Entity Sets

SAP HANA calculation views can interpret input parameters. For OData, these parameters can be entered by
using a special parameter entity set.

Parameter entity sets can be generated for calculation views by adding parameters via entity to the entity, as
illustrated in the following service-definition example:

service {
"sample.odata::calc" as "CalcView"
keys generate local "ID"
parameters via entity;
}

During loading of the service, parameters specified in sample.odata/calc.calculationview are retrieved

from the metadata of the calculation view and exposed as a new EntitySet named after the entity set name
and the suffix Parameters, for example, CalcViewParameters. A NavigationProperty named Results
is generated to retrieve the results from the parameterized call.

SAP HANA Developer Guide

308 PUBLIC Defining Web-based Data Access
The name of the generated parameter entity set and the navigation property can be customized, as illustrated
in the following service-definition example:

service {
"sample.odata::calc" as "CalcView"
keys generate local "ID"
parameters via entity "CVParams" results property "Execute";
}

With the definition above, the name of the parameter entity set is CVParams, and the name of the
NavigationProperty for the results is Execute.

Navigating to Entities via Parameters

In an OData service definition, you can enable navigation between an entity and a parameterized entity. This
feature is particularly useful if you need to have access to individual entries in a parameterized entity set, for
example, a calculation view with parameters. If you need to access individual entries in an entity set that has
parameters, you must expose the parameters as keys. If you do not need to have access to individual entries in
an entity set, you can use the key generate local option to generate a pseudo key.

To enable navigation between an entity and a parameterized entity, you must perform the following steps:

1. Specify the parameters as part of the key of the target entity

2. Define the association between the entities

Enabling navigation between an entity and a parameterized entity is only possible if the parameters are part of
the entity-type key in the OData service definition file. To make the parameters part of the key of the target
entity, use the via key syntax, as illustrated in the following example:

service {
"sap.test::calcview" key ("theKeyColumns") parameters via key and entity;
}

You also have to define an association between the source and target entities, for example, with additional
entries introduced by the via parameters keyword, as illustrated in the following example:

service {
"sap.test::table" as "Tab" navigates ("avp" as "ViewNav");
"sap.test::calcview" as "View" key ("theKeyColumns") parameters via key and
entity;

association via parameters "avp"

principal "Tab"("paramValue") multiplicity "*"
dependent "View"("parameter") multiplicity "*";
}

Note
The order of the property list of the dependent end is crucial.

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 309
The parameters you define in the dependent end of the association must be the first properties in the list. In
addition, the parameters specified must be given in the same order as they are specified in the view, as
illustrated in the following example:

association via parameters "avp"

principal "Tab"("col1", "col2", "col3") multiplicity "*"
dependent "View"("parameter1", "parameter2", "colA") multiplicity "*";

In the example immediately above, the principal “Tab” has three columns that contain the information that is
required to navigate to the dependent “View” in the association.

● “col1”
The value of “col1” should be set for “parameter1”
● “col2”
The value of “col2” should be set for “parameter2”
● “col3”
The parameter “col3” contains additional information that is not passed as an input parameter, but as
part of a WHERE condition.

The generated SQL statement would look like the following:

select ... from "sap.test::calcview"(placeholder."$$parameter1$$"=>?,

placeholder."$$parameter2$$"=>?)
where "colA"=?

Note
This navigation property cannot be used in combination with the OData query options $expand, $filter
and $orderby.

6.1.6.9 OData ETag Support

This feature allows a service to define the fields that are to be included in the concurrency check.

You can now use entity tags (ETags) for optimistic concurrency control. If you choose to use this feature, then
you must enable it per entity in the .xsodata file. Enabling this feature per entity allows for the concurrency
control to be applied to multiple fields. The following code example provides information about how to do this.

Sample Code

service
{ entity "sap.test.odata.db.views::Etag" as "EtagAll"
key ("KEY_00") concurrencytoken;
entity "sap.test.odata.db.views::Etag" as "EtagNvarchar"
key ("KEY_00") concurrencytoken ("NVARCHAR_01","INTEGER_03");
}

If you specify concurrencytoken only, then all properties, except the key properties, are used to calculate the
ETag value. If you provide specific properties, then only those properties are used for the calculation.

SAP HANA Developer Guide

310 PUBLIC Defining Web-based Data Access
 Note
You cannot specify concurrencytoken on aggregated properties that use the AVG (average) aggregation
method.

6.1.6.10 OData Nullable Properties

You can create a service to enable nullable properties in OData.

During the 'Create' phase, the XSODATA layer generates all entity properties automatically. Since the
properties are not nullable, consumers of the code are forced to pass dummy values into them. However,
OData supports $filter and $orderby conditions on the null value. This means that it is now possible to
treat null as a value, if you enable it. You can enable this behavior for the entire service only, not per entity.

The following code example provides information about how you can do this.

Sample Code

service {
…
}
settings {
support null;
}

If you enable this support, then $filter requests, such as $filter=NVARCHAR_01 eq null, are possible.
Otherwise null is rejected with an exception. Of course, if you do not enable the support, then the default
behavior applies. All null values are ignored in comparisons and the respective rows are removed from the
result; this is common database behavior.

6.1.6.11 OData Configurable Cache Settings

You can create a service to configure the cache settings for the $metadata request to optimize performance.

When calling OData services, the services make repeated requests for the $metadata document. Since
changes to the underlying entity definitions occurs rarely,SAP has enabled the option to configure caching for
these $metadata documents. By configuring the cache, you can avoid many redundant queries to process the
metadata.

The following code example provides information about how you can do this.

Sample Code

service {
...
}
settings {
metadata cache-control "no-store";

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 311
 content cache-control "max-age=3600,must-revalidate";
}

6.1.6.12 Custom Exits for OData Write Requests

SAP HANA XS enables you to execute custom code at defined points of an OData write request.

If you provide a custom exit for an OData write request, the code has to be provided in form of an SQLScript
procedure with signatures that follow specific conventions. The following type of write exits are supported for
OData write requests in SAP HANA XS:

● Validation Exits
These exits are for validation of input data and data consistency checks. They can be registered for create,
update, and delete events and executed before or after the change operation, or before or after the commit
operation. You can specify a maximum of four validation exits per change operation; the exit is registered
for the corresponding event with the respective keyword: “before”, “after”, “precommit” or “postcommit”.
● Modification Exits
You can define custom logic to create, update, or delete an entry in an entity set. If a modification exit is
specified, it is executed instead of the generic actions provided by the OData infrastructure. You use the
using keyword to register the exit.

If registered, the scripts for the exits are executed in the order shown in the following table:

Execution Order of Exit Validation/Modification Scripts

OData Insert Type Script Execution Order

Single Insert before, using, after, precommit, postcommit

Batch Insert before(1), using(1), after(1), before(2), using(2), after(2), … , precommit(1), precommit(2),
postcommit(1), postcommit(2)

The signature of a registered script has to follow specific rules, depending on whether it is registered for entity
or link write operations and depending on the operation itself. The signature must also have table-typed
parameters for both input and output:

● Entity Write Operations

● Link Write Operations

For entity write operations, the methods registered for the CREATE operation are passed a table containing the
new entry that must be inserted into the target table; the UPDATE operation receives the entity both before and
after the modification; the DELETE operation receives the entry that must be deleted. The table type of the
parameters (specified with the EntityType keyword in the table below) corresponds to the types of the exposed
entity.

Entity Write Operations

Script Type Create Update Delete

before, after, precommit, us­ IN new EntityType, OUT error IN new EntityType, IN old En­ IN old EntityType, OUT error
ing ErrorType tityType, OUT error Error­ ErrorType
Type

SAP HANA Developer Guide

312 PUBLIC Defining Web-based Data Access
 Script Type Create Update Delete

postcommit IN new EntityType IN new EntityType, IN old En­ IN old EntityType

tityType

For link write operations, all exits that are executed before the commit operation take two table-typed input
parameters and one table-typed output parameter. The first parameter must correspond to the structure of
the entity type at the principal end of the association; the second parameter must correspond to the
dependent entity type.

Link Write Operations

Script Type Create, Update, Delete

before, after, precommit, us­ IN principal PrincipalEntityType, IN dependent DependentEntityType, OUT error ErrorType
ing

postcommit IN principal PrincipalEntityType, IN dependent DependentEntityType

Note
Parameter types (IN, OUT) are checked during activation; the data types of table type columns are not
checked.

The OUT parameter enables you to return error information. The first row in the OUT table is then serialized as
inner error in the error message. If no error occurs, the OUT table must remain empty. The structure of the
table type ErrorType is not restricted. Any columns with special names HTTP_STATUS_CODE and
ERROR_MESSAGE are mapped to common information in the OData error response. Content of columns with
other names are serialized into the inner error part of the error message that allows the return of custom
error information.

Error Message Content

Column Name Type Value Range Error Response Information

HTTP_STATUS_CODE INTEGER 400-417 (default: 400) The HTTP response status

code

ERROR_MESSAGE NVARCHAR The error message

(<message>)

Note
If the SQLScript procedure throws an exception or writes an error messages to the OUT parameter table, the
OData write operation is aborted. If more than one error message is added, only the content of the first row
is returned in the resulting error message. Any scripts registered for the postcommit event must not have
an OUT parameter as the write operation cannot be aborted at such a late stage, even in the event of an
error.

The following example illustrates a typical error-type table type, which is defined in a design-time file that must
have the .hdbtabletype file suffix, for example error.hdbtabletype:

"sample.odata::error" AS TABLE (
"HTTP_STATUS_CODE" INTEGER,
"ERROR_MESSAGE" NVARCHAR(100),

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 313
 "DETAIL" NVARCHAR(100)
)

The following example shows how information is extracted from the error table if an error occurs during the
execution of a create procedure for an OData write operation:

create procedure "sample.odata::createmethod"(IN new "sample.odata::table", OUT

error "sample.odata::error")
language sqlscript
sql security invoker as
id INT;
begin
select ID into id from :new;
if :id < 1000 then
error = select 400 as http_status_code,
'invalid ID' error_message,
'value must be >= 1000' detail from dummy;
else
insert into "sample.odata::table" values (:id);
end if;
end;

6.1.6.13 Tutorial: Creating a Validation Exit with SQLScript

Use SQLScript to create a custom validation exit which runs server-side verification and data-consistency
checks for an OData update operation.

Prerequisites

To perform this task, you need the following objects:

● A table to expose, for example, sample.odata::table.hdbtable

● An error type, for example, sample.odata::error.hdbtabletype

Context

In this tutorial, you see how to register an SQL script for an OData update operation; the script verifies, before
the execution of the update operation, that the updated value is larger than the previous one. In the example
shown in this tutorial, you define the table to be updated and a table type for the error output parameter of the
exit procedure.

Procedure

1. Create a table definition file using .hdbtable syntax.

SAP HANA Developer Guide

314 PUBLIC Defining Web-based Data Access
 The table to expose is defined in sample.odata:table.hdbtable, which should look like the following
example:

COLUMN TABLE "table" (

"ID" INTEGER NOT NULL,
PRIMARY KEY ("ID")
);

2. Create a table type for the error output parameter of the exit procedure.

The error type file sample.odata:error.hdbtabletype should look like the following example:

"sample.odata::error" AS TABLE (
"HTTP_STATUS_CODE" INTEGER,
"ERROR_MESSAGE" NVARCHAR(100),
"DETAIL" NVARCHAR(100)
)

3. Create a procedure that runs before the UPDATE event.

The procedure script for the before UPDATE event must have two table input parameters and one output
parameter, for example:
○ IN new "sample.odata::table"
○ IN old "sample.odata::table"
○ OUT error "sample.data::error"

The procedure sample.odata:beforeupdate.hdbprocedure would look like the following example:

procedure "sample.odata::beforeupdate"
(IN new "sample.odata::table", IN old "sample.odata::table", OUT error
"sample.odata::error")
language sqlscript
sql security invoker as
idnew INT;
idold INT;
begin
select ID into idnew from :new;
select ID into idold from :old;
if :idnew <= :idold then
error = select 400 as http_status_code,
'invalid ID' error_message,
'the new value must be larger than the previous' detail from dummy;
end if;
end;

4. Register the procedure to be executed at the before event.

You use the update events (before “...”) keywords to register the procedure, as illustrated in the
following example of an OData service file:

service {
“sample.odata::table”
update events (before “sample.odata::beforeupdate”);
}

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 315
6.1.6.14 Tutorial: Creating a Modification Exit with SQLScript

Register an SQL script as a modification exit for an OData create operation for an entity.

Prerequisites

To perform this task, you need the following objects:

● A table to expose for the OData create operation, for example, sample.odata::table.hdbtable
● An error type, for example, sample.odata::error.hdbstructure

Note
These objects are used as types in the procedure.

Context

SAP HANA XS enables you to register custom code that handles the OData write operation for non-trivial
cases. In this tutorial, you see how to register a modification exit for an OData CREATE operation for an entity.
The procedure you register verifies the data to insert, refuses the insertion request if the specified ID is less
than 1000, and in the event of an error, inserts a row with error information into the output table.

Procedure

1. Create a table definition file using .hdbtable syntax.

The table you create in this step is used in the procedure you create later in the tutorial. The table to expose
is defined in sample.odata:table.hdbtable, which should look like the following example:

table.schemaName = "ODATASAMPLES";
table.columns = [{name = "ID"; sqlType = INTEGER; nullable = false;}];
table.primaryKey.pkcolumns = ["ID"];

2. Create a table type for the error output parameter of the exit procedure.

The error type you create in this step is used in the procedure you create later in the tutorial. The error type
file sample.odata:error.hdbstructure should look like the following example:

table.schemaName = "ODATASAMPLES";
table.columns = [
{name = "HTTP_STATUS_CODE"; sqlType = INTEGER;},
{name = "ERROR_MESSAGE"; sqlType = NVARCHAR; length = 100;},
{name = "DETAIL"; sqlType = NVARCHAR; length = 100;}
];

3. Create a procedure that runs before the UPDATE event.

SAP HANA Developer Guide

316 PUBLIC Defining Web-based Data Access
 The table and error type objects you created in the previous steps are used as types in the procedure
created here. The procedure also performs a verification on the data, rejects the insertion in case of an ID
below 1000, and inserts a row with error information into the output table.

The procedure sample.odata:createmethod.hdbprocedure should look like the following example:

procedure "ODATA_TEST"."sample.odata::createmethod"
(IN new "sample.odata::table", OUT error "sample.odata::error")
language sqlscript
sql security invoker as
id INT;
begin
select ID into id from :new;
if :id < 1000 then
error = select 400 as http_status_code,
'invalid ID' error_message,
'value must be >= 1000' detail from dummy;
else
insert into "sample.odata::table" values (:id);
end if;
end;

4. Register the procedure to be executed at the CREATE event.

You use the create using keywords to register the procedure, as illustrated in the following OData
service file:

service {
“sample.odata::table”
create using “sample.odata::createmethod”;
}

6.1.6.15 Tutorial: Creating a Modification Exit with XS

JavaScript

You can use server-side JavaScript to write a script which you register as a modification exit for an OData
update operation for an entity.

Prerequisites

To perform this task, bear in mind the following prerequisites:

● A table to expose for the OData create operation, for example, sample.odata::table.hdbtable

Context

SAP HANA XS enables you to register custom code that handles the OData write operation. In this tutorial, you
see how to use server-side JavaScript (XSJS) to write a script which you register as a modification exit for
OData UPDATE operations for an entity. The script you register verifies the data to insert, and throws a defined

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 317
error string in the event of an error, for example, Could not update table; check access
permissions.

To register an XS JavaScript function as an OData modification exit, perform the following steps:

Procedure

1. Create a table definition file, for example, using the .hdbtable syntax.

The table you create in this step is used in the XS JavaScript function you create later in the tutorial. The
table to expose is defined in sample.odata:table.hdbtable, which should look like the following
example:

COLUMN TABLE "table" (

"ID" INTEGER NOT NULL,
PRIMARY KEY ("ID")
);

2. Create the XS JavaScript function that you want to register for OData modification events.

Note
The XS JavaScript function that you want to register for OData modification events must be created in
the form of an XSJS library, for example, with the file extension .xsjslib; the XS JavaScript function
cannot be an .xsjs file.

The function you register has one parameter, which can have the properties listed in the following table:

Property Type Description

connection Connection The SQL connection used in the OData request

beforeTableName String The name of a temporary table with the single entry before
the operation (UPDATE and DELETE events only)

afterTableName String The name of a temporary table with the single entry after
the operation (CREATE and UPDATE events only)

The XS JavaScript function jsexit.xsjslib could look like the following example:

function update_instead(param) {
$.trace.debug(“entered function”);
let before = param.beforeTableName;
let after = param.afterTableName;
let pStmt = param.connection.prepareStatement('select * from ”' + after
+'"');
// ...
if (ok) {
// update
} else {
throw “an error occurred; check access privileges”
}
}

3. Bind the XS JavaScript function to the entity specified in the OData service definition.

SAP HANA Developer Guide

318 PUBLIC Defining Web-based Data Access
 To bind the XS JavaScript function to a specified entity, use the syntax:
<Package.Path>:<file>.<suffix>::<XSJS_FunctionName> as illustrated in the following example:

service {
"sample.odata::table" as "Table" update using
"sap.test:jsexit.xsjslib::update_instead";
}

6.1.7 OData Service Definition Language Syntax (XS

Advanced)

The OData Service Definition Language (OSDL) provides a set of keywords that enable you to set up an ODATA
service definition file that specifies what data to expose, in what way, and to whom.

The following list shows the syntax of the OData Service Definition Language (OSDL) in an EBNF-like format;
conditions that apply for usage are listed after the table.

definition :=service [annotations]

service :='service' [namespace] body
namespace :='namespace' quotedstring
quotedstring :=quote string quote
string :=UTF8
quote :='"'
body :='{' content '}'
content :=entry [content]
entry :=( entity | association ) ';'
entity :=object [entityset] [with] [keys] [navigates]
[aggregates] [parameters] [modification]
object :=['entity'] ( repoobject | catalogobject )
repoobject :=quote repopackage '/' reponame '.' repoextension quote
repopackage :=string
reponame :=string
repoextension :=string
catalogobject :=catalogobjectschema '.' catalogobjectname
catalogobjectschema :=quotedstring
catalogobjectname :=quotedstring
entityset :='as' entitysetname
entitysetname :=quotedstring
with :=( 'with' | 'without' ) propertylist
propertylist :='(' columnlist ')'
columnlist :=columnname [',' columnlist]
columnname :=quotedstring
keys :='keys' ( keylist | keygenerated )
keylist :=propertylist
keygenerated :='generate' ( keygenlocal )
keygenlocal :='local' columnname
navigates :='navigates' '(' navlist ')'
navlist :=naventry [',' navlist]
naventry :=assocname 'as' navpropname [fromend]
assocname :=quotedstring
navpropname :=quotedstring
fromend :='from' ( 'principal' | 'dependent' )
aggregates :='aggregates' 'always' [aggregatestuple]
aggregatestuple :='(' aggregateslist ')'
aggregateslist :=aggregate [',' aggregateslist]
aggregate :=aggregatefunction 'of' columnname
aggregatefunction :=( 'SUM' | 'AVG' | 'MIN' | 'MAX' )
parameters :='parameters' 'via' [parameterskeyand] 'entity'
[parameterentitysetname] [parametersresultsprop]
parameterskeyand :='key' 'and'

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 319
 parameterentitysetname :=quotedstring
parametersresultsprop :='results' 'property' quotedstring
modification :=[create] [update] [delete]
create :='create' modificationspec
update :='update' modificationspec
delete :='delete' modificationspec
modificationspec :=( modificationaction [events] | events | 'forbidden' )
modificationaction :='using' action
action :=quotedstring
events :='events' '(' eventlist ')'
eventlist :=eventtype action [',' eventlist]
eventtype :=( 'before' | 'after' | 'precommit' | 'postcommit' )
association :=associationdef [assocrefconstraint] principalend
dependentend [( assoctable | storage | modification )]
associationdef :='association' assocname
assocrefconstraint :=‘with’ ‘referential’ ‘constraint'
principalend :='principal' end
dependentend :='dependent' end
end :=endref multiplicity
endref :=endtype [joinpropertieslist]
endtype :=entitysetname
joinpropertieslist :='(' joinproperties ')'
joinproperties :=columnlist
multiplicity :='multiplicity' quote multiplicityvalue quote
multiplicityvalue :=( '1' | '0..1' | '1..*' | '*' )
assoctable :='over' repoobject overprincipalend overdependentend
[modification]
overprincipalend :='principal' overend
overdependentend :='dependent' overend
overend :=propertylist
storage :=( nostorage | storageend [modification] )
nostorage :='no' 'storage'
storageend :='storage' 'on' ( 'principal' | 'dependent' )
annotations :='annotations' annotationsbody
annotationsbody :='{' annotationscontent '}'
annotationscontent :=annotationconfig [annotationscontent]
annotationconfig :='enable' annotation
annotation :='OData4SAP'

Note
Support for OData annotations is currently not available in SAP HANA XS Advanced.

Conditions

The following conditions apply when using the listed keywords:

1. If the namespace is not specified, the schema namespace in the EDMX metadata document will be the
repository package of the service definition file concatenated with the repository object name. E.g. if the
repository design time name of the .xsodata file is sap.hana.xs.doc/hello.xsodata the
namespace will implicitly be sap.hana.xs.doc.hello.
2. keyslist must not be specified for objects of type 'table'. They must only be applied to objects referring a
view type. keygenerated in turn, can be applied to table objects.
3. If the entityset is not specified in an entity, the EntitySet for this object is named after the repository
object name or the catalogobjectname. For example, if object is "sap.hana.xs.doc/odata_docu",
then the entitysetname is implicitly set to odata_docu, which then can also be referenced in
associations.

SAP HANA Developer Guide

320 PUBLIC Defining Web-based Data Access
4. The fromend in a naventry must be specified if the endtype is the same for both the principalend
and the dependentend of an association.
5. The number of joinproperties in the principalend must be the same as in the dependentend.
6. Ordering in the joinproperties of ends is relevant. The first columnname in the joinproperties of
the principalend is compared with the first columnname of the dependentend, the second with the
second, and so on.
7. The overprincipalend corresponds to the principalend. The number of properties in the
joinproperties and the overproperties must be the same and their ordering is relevant. The same
statement is true for the dependent end.
8. aggregates can only be applied in combination with keygenerated.
9. If aggregatestuple is omitted, the aggregation functions are derived from the database. This is only
possible for calculation views and analytic views.
10. Specifying parameters is only possible for calculation views and analytic views.
11. The default parameterentitysetname is the entitysetname of the entity concatenated with the suffix
"Parameters".
12. If the parametersresultsprop is omitted, the navigation property from the parameter entity set to the
entity is called "Results".
13. Support for OData annotations is currently under development. For more information about the SAP-
specific metadata annotations that become available with the enable OData4SAP statement in
an .xsodata file, see the Related Links below. Note that not all annotations allowed by OData are
supported by SAP HANA XS.

Related Information

SAP Annotations for OData

Open Data Protocol

6.1.8 OData Service Definition: SQL-EDM Type Mapping (XS

Advanced)

During the activation of the OData service definition, the SAP HANA SQL types are mapped to the required
OData EDM types according to the rules specified in a mapping table.

The following mapping table lists how SAP HANA SQL types are mapped to OData EDM types during the
activation of an OData service definition.

Note
The OData implementation in SAP HANA XS supports only those SQL types listed in the following table.

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 321
SAP HANA SQL to OData EDM Type Mapping
SAP HANA SQL Type OData EDM Type

Time Edm.Time

Date Edm.DateTime

SecondDate Edm.DateTime

LongDate Edm.DateTime

Timestamp Edm.DateTime

TinyInt Edm.Byte

SmallInt Edm.Int16

Integer Edm.Int32

BigInt Edm.Int64

SmallDecimal Edm.Decimal

Decimal Edm.Decimal

Real Edm.Single

Float Edm.Single

Double Edm.Double

Varchar Edm.String

NVarchar Edm.String

Char Edm.String

NChar Edm.String

Binary Edm.Binary

Varbinary Edm.Binary

Example SQL Type Mapping

The following examples shows how SAP HANA SQL types (name, integer, Varchar) of columns in a table are
mapped to the OData EDM types in the properties of an entity type.

SAP HANA SQL:

{name = "ID"; sqlType = INTEGER; nullable = false;},

{name = "RefereeID"; sqlType = VARCHAR; nullable = true;}

The following example illustrates how the SAP HANA SQL types illustrated in the previous example are mapped
to EDM types:

<Property Name="ID" Type="Edm.Int32" Nullable="false"/>

<Property Name="RefereeID" Type="Edm.String" Nullable="true"/>

SAP HANA Developer Guide

322 PUBLIC Defining Web-based Data Access
6.1.9 OData Security Considerations

Enabling access to data by means of OData can create some security-related issues that you need to consider
and address, for example, the data you want to expose, who can start the OData service, and so on.

If you want to use OData to expose data to users and clients in SAP HANA application services, you need to
bear in mind the security considerations described in the following list:

● Data Access
Restrict user select authorization for tables/views exposed by the OData service
● OData Service
Restrict authorization rights to start the OData service
● OData Statistical content
Restrict access to the URL/Path used to expose OData content in the Web browser

6.1.10 OData Batch Requests (XS Advanced)

The OData standard allows the collection of multiple individual HTTP requests into one single batched HTTP
request.

Clients using a defined OData service to consume exposed data can collect multiple, individual HTTP requests,
for example, retrieve, create, update and delete (GET, POST, PUT, DELETE), in a single “batch” and send the
batched request to the OData service as a single HTTP request. You can compile the batch request manually
(by creating the individual requests in the batch document by hand) or automatically, for example, with an
AJAX call that adds requests to a queue and loops through the queues to build the batch request. In both
cases, the OData standard specifies the syntax required for the header and body elements of a valid batch
request document.

SAP HANA XS supports the OData $batch feature out-of-the-box; there is nothing to configure in SAP HANA
XS to use $batch to perform operations in SAP HANA using an OData service. To understand how the $batch
feature works, you need to look at the following phases of the operation:

● Batch Request
● Batch Response

A batch request is split into two parts: the request header and the request body. The body of a batch request
consists of a list of operations in a specific order where each operation either retrieves data (for example, using
the HTTP GET command) or requests a change. A change request involves one or more insert, update or delete
operations using the POST, PUT, or DELETE commands.

Note
A change request must not contain either a retrieve request or any nested change requests.

The batch request must contain a Content-Type header specifying the value “multipart/mixed” and a
boundary ID boundary=batch_#; the batch boundary ID is then used to indicate the start of each batch
request, as illustrated in the following example.

POST /service/$batch HTTP/1.1

Host: host
Content-Type: multipart/mixed;boundary=batch_8219-6895 // Define batch ID

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 323
 --batch_8219-6895 // Batch 1 start
Content-Type: multipart/mixed; boundary=changeset_a4e3-a738 // Define
changeset ID
--changeset_a4e3-a738 // Changeset 1
start
Content-Type: application/http
Content-Transfer-Encoding: binary
[PUT...]

--changeset_a4e3-a738 // Changeset 2
start
Content-Type: application/http
Content-Transfer-Encoding: binary
[POST...]
--changeset_a4e3-a738-- // Changeset (all)
end
--batch_8219-6895 // Batch part 2
start
Content-Type: application/http
Content-Transfer-Encoding:binary
[GET...]
--batch_8219-6895-- // Batch (all) end

Within the batch request, changeset is defined by another boundary ID (for example,
boundary=changeset_123), which is then used to indicate the start and end of the change requests. The
batch request must be closed, too.

Note
In the following example of a simple OData batch request, some content has been removed to emphasize
the structure and layout.

POST http://localhost:8002/sap/sample/odata/syntax.xsodata/$batch HTTP/1.1

Host: localhost:8002
Connection: keep-alive
Content-Length: 471
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/30.0.1599.101 Safari/537.36
Cache-Control: no-cache
Content-Type: multipart/mixed; boundary=batch_123
Accept: */*
Accept-Encoding: identity
Accept-Language: en-US,en;q=0.8
x-sap-request-language: en-US
--batch_123
Content-Type:multipart/mixed;boundary=changeset_456
Content-Transfer-Encoding:binary
--changeset_456
Content-Type:application/http
Content-Transfer-Encoding:binary
POST BatchSample HTTP/1.1
Content-Type:application/json
Content-Length:11
{"ID" : 14}
--changeset_456
Content-Type:application/http
Content-Transfer-Encoding:binary
POST BatchSample HTTP/1.1
Content-Type:application/json
Content-Length:11
Accept: application/json
{"ID" : 15}
--changeset_456--
--batch_123--

SAP HANA Developer Guide

324 PUBLIC Defining Web-based Data Access
The batch response includes a response for each of the retrieve or change operations included in the
corresponding batch request. The order of the responses in the response body must match the order of
requests in the batch request. In the context of the batch response, the following is true:

● The response to a retrieve request is always formatted in the same way regardless of whether it is sent
individually or as part of batch.
● The body of the collected response to a set of change-requests is one of the following:
○ A response for all the successfully processed change requests within the change set, in the correct
order and formatted exactly as it would have appeared outside of a batch
○ A single response indicating the failure of the entire change set

The following example shows the form and syntax of the OData batch response to the request illustrated above.

HTTP/1.1 202 Accepted

content-type: multipart/mixed; boundary=0CDF14D90919CC8B4A32BD0E0B330DA10
content-length: 2029
content-language: en-US
cache-control: no-cache
expires: Thu, 01 Jan 1970 00:00:00 GMT
--0CDF14D90919CC8B4A32BD0E0B330DA10
Content-Type: multipart/form-data; boundary=0CDF14D90919CC8B4A32BD0E0B330DA11
Content-Length: 1843
--0CDF14D90919CC8B4A32BD0E0B330DA11
Content-Type: application/http
Content-Length: 1118
content-transfer-encoding: binary
HTTP/1.1 201 Created
Content-Type: application/atom+xml;charset=utf-8
location: http://localhost:8002/sap/sample/odata/syntax.xsodata/BatchSample(14)/
Content-Length: 943
<?xml version="1.0" encoding="utf-8" standalone="yes"?><entry xml:base="http://
localhost:8002/sap/sample/odata/syntax.xsodata/" xmlns:d="http://
schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://
schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://
www.w3.org/2005/Atom"><id>http://localhost:8002/sap/sample/odata/syntax.xsodata/
BatchSample(14)</id><title type="text"></title><author><name /></author><link
rel="edit" title="BatchSample" href="BatchSample(14)"/><link rel="http://
schemas.microsoft.com/ado/2007/08/dataservices/related/Ref" type="application/
atom+xml;type=entry" title="Ref" href="BatchSample(14)/Ref"></link><category
term="sap.sample.odata.syntax.BatchSampleType" scheme="http://
schemas.microsoft.com/ado/2007/08/dataservices/scheme" /><content
type="application/xml"><m:properties><d:ID m:type="Edm.Int32">14</d:ID><d:SELFID
m:type="Edm.Int32" m:null="true"></d:SELFID></m:properties></content></entry>
--0CDF14D90919CC8B4A32BD0E0B330DA11
Content-Type: application/http
Content-Length: 427
content-transfer-encoding: binary
HTTP/1.1 201 Created
Content-Type: application/json
location: http://localhost:8002/sap/sample/odata/syntax.xsodata/BatchSample(15)
Content-Length: 271
{"d":{"__metadata": {"uri":"http://localhost:8002/sap/sample/odata/
syntax.xsodata/
BatchSample(15)","type":"sap.sample.odata.syntax.BatchSampleType"},"ID":
15,"SELFID":null,"Ref":{"__deferred":{"uri":"http://localhost:8002/sap/sample/
odata/syntax.xsodata/BatchSample(15)/Ref"}}}}
--0CDF14D90919CC8B4A32BD0E0B330DA11--
--0CDF14D90919CC8B4A32BD0E0B330DA10--

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 325
OData Batch Requests in SAPUI5 Applications

If you are developing a UI client using SAPUI5, you can make use of the ODataModel tools to ensure that the
data requests generated by the various UI controls bound to an OData service are collected and sent in
batches. The SAPUI5 ODataModel toolset includes a large selection of tools you can use to configure the use of
the OData batch feature, for example:

● setUseBatch
Enable or disable batch processing for all requests (read and change)
● addBatchChangeOperations
Appends the change operations to the end of the batch stack, which is sent with the submitBatch
function
● addBatchReadOperations
Appends the read operations to the end of the batch stack, which is sent with the submitBatch function
● submitBatch
Submits the collected changes in the batch which were collected via addBatchReadOperations or
addBatchChangeOperations.

Related Information

Open Data Protocol

SAPUI5 ODataModel Reference

6.2 Data Access with XMLA in SAP HANA XS

In SAP HANA Extended Application Services, the persistence model (for example, tables, views and stored
procedures) is mapped to the consumption model that is exposed to clients - the applications you write to
extract data from the SAP HANA database.

You can map the persistence and consumption models with XML for Analysis (XMLA). With XMLA, you write
multi-dimensional -expressions (MDX) queries wrapped in an XMLA document. An XML for Analysis (XMLA)
application running in SAP HANA application services is used to provide the consumption model for client
applications exchanging MDX queries (wrapped in XMLA documents) with the SAP HANA database.

XMLA uses Web-based services to enable platform-independent access to XMLA-compliant data sources for
Online Analytical Processing (OLAP). XMLA enables the exchange of analytical data between a client
application and a multi-dimensional data provider working over the Web, using a Simple Object Access
Protocol (SOAP)-based XML communication application-programming interface (API).

Applications running in SAP HANA XS enable very accurate control of the flow of data between the
presentational layer, for example, in the Browser, and the data-processing layer in SAP HANA itself, where the
calculations are performed, for example in SQL or SqlScript. If you develop and deploy an XMLA service
running in SAP HANA XS, you can take advantage of the embedded access to SAP HANA that SAP HANA XS
provides; the embedded access greatly improves end-to-end performance.

SAP HANA Developer Guide

326 PUBLIC Defining Web-based Data Access
6.2.1 XML for Analysis (XMLA)

XML for Analysis (XMLA) uses Web-based services to enable platform-independent access to XMLA-compliant
data sources for Online Analytical Processing (OLAP).

XMLA enables the exchange of analytical data between a client application and a multi-dimensional data
provider working over the Web, using a Simple Object Access Protocol (SOAP)-based XML communication
application-programming interface (API).

Implementing XMLA in SAP HANA enables third-party reporting tools that are connected to the SAP HANA
database to communicate directly with the MDX interface. The XMLA API provides universal data access to a
particular source over the Internet, without the client having to set up a special component. XML for Analysis is
optimized for the Internet in the following ways:

● Query performance
Time spent on queries to the server is kept to a minimum
● Query type
Client queries are stateless by default; after the client has received the requested data, the client is
disconnected from the Web server.

In this way, tolerance to errors and the scalability of a source (the maximum permitted number of users) is
maximized.

XMLA Methods

The specification defined in XML for Analysis Version 1.1 from Microsoft forms the basis for the implementation
of XML for Analysis in SAP HANA.

The following list describes the methods that determine the specification for a stateless data request and
provides a brief explanation of the method's scope:

● Discover
Use this method to query metadata and master data; the result of the discover method is a rowset. You
can specify options, for example, to define the query type, any data-filtering restrictions, and any required
XMLA properties for data formatting.
● Execute
Use this method to execute MDX commands and receive the corresponding result set; the result of the
Execute command could be a multi-dimensional dataset or a tabular rowset. You can set options to
specify any required XMLA properties, for example, to define the format of the returned result set or any
local properties to use to determine how to format the returned data.

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 327
6.2.2 Tutorial: Use the SAP HANA XMLA Interface

You can use the XML for Analysis (XMLA) interface included in SAP HANA Extended Application Services (SAP
HANA XS) to provide a service that enables XMLA-capable clients to query multidimensional cubes in SAP
HANA.

Prerequisites

● A multidimensional data cube is available in SAP HANA, for example, in the form of a calculation view, an
analytic view, or an attribute view
● An XMLA client is available

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the root package for your XMLA interface test:
a. From the context menu of the Content folder, choose Create Application.
b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter a package name, for example, helloxmla, and choose Create.
The system creates an index.html file and the .xsaccess and .xsapp files.
3. In the .xsaccess file, ensure that the application content is exposed to HTTP requests:

{
"exposed" : true
}

4. Create an XMLA service-definition file: and place it in your root XMLA package helloxmla.

a. Select your root XMLA package, for example, helloxmla, and from the context menu choose New
File .

Note
The file containing the XMLA service definition must be placed in the root package of the XMLA
application for which the service is intended.

b. Enter a file name with the file extension .xsxmla, for example, hello.xsxmla, and choose Create.
c. Enter the following content in the hello.xsxmla XMLA service-definition file:

service {*}

5. Save the XMLA service-definition file.

6. Test the connection to the SAP HANA XS Web server.

SAP HANA Developer Guide

328 PUBLIC Defining Web-based Data Access
 http://<hana.server.name>:80<HANA_instance_number>/helloxmla/hello.xsxmla

Note
You have successfully completed this step if you see a 404 Error page; the page indicates that the SAP
HANA XS Web server has responded.

7. Connect your XMLA client application to the inbuilt XMLA interface in SAP HANA XS.
To connect an XMLA-capable client (for example, Microsoft Excel) with the XMLA interface in SAP HANA
XS, you will need a product (for example, a plug-in for Microsoft Excel) that can transfer the XMLA message
that the SAP HANA XS XMLA interface can understand.
8. Configure your client to send an XMLA query to SAP HANA.

6.2.3 Define the Data an XMLA Service Exposes

An XMLA service exposes data stored in database tables for analysis and display by client applications.
However, first of all, you need to ensure that the tables and views to expose as an XMLA service actually exist
and are accessible.

Context

To define the data to expose using an XMLA service, you must perform at least the following tasks:

Procedure

1. Create a simple database schema.

2. Create a simple database table to expose with an XMLA service.
3. If required, create a simple database view to expose with an XMLA service.
4. Grant select privileges to the tables and views to be exposed with the XMLA service.

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 329
6.2.4 Create an XMLA Service Definition

The XMLA service definition is a file you use to specify which data is exposed as XMLA/MDX collections for
analysis and display by client applications.

Prerequisites

● You have created a package structure for your XMLA application.

● Data is available to expose using the XMLA interface.

Context

An XMLA service for SAP HANA XS is defined in a text file with the file extension .xsxmla, for example,
XMLASrvDef.xsxmla. The file resides in the package hierarchy of the XMLA application and must contain only
the entry {*}, which generates a completely operational XMLA service.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/ide/editor
2. Create the file that will contain your XMLA service definition:
a. From the context menu of the package where you want to create the new XMLA service-definition file,
choose New File .

Note
The file containing the XMLA service definition must be placed in the root package of the XMLA
application for which the service is intended.

b. Enter a file name with the file extension .xsxmla, for example, XMLASrvDef.xsxmla, and choose
Create.
3. Create the XMLA service definition.
The XMLA service definition is a configuration file that you use to specify which data is to be exposed as an
XMLA collection.
The following code is an example of a valid XMLA service definition, which exposes all authorized data to
XMLA requests:

service{*}

Not the currently the XMLA service-definition file enables you to specify only that all authorized data is
exposed to XMLA requests.

SAP HANA Developer Guide

330 PUBLIC Defining Web-based Data Access
4. Save the XMLA service definition.

Related Information

Define the Data an XMLA Service Exposes [page 329]

6.2.5 XMLA Service Definition

The XMLA service definition is a file you use to specify which data is exposed as XMLA collections. Exposed
data is available for analysis and display by client applications, for example, a browser that uses functions
provided either by the XMLA service running in SAP HANA XS or by an XMLA client library running on the client
system.

To expose information via XMLA to applications using SAP HANA Extended Application Services (SAP HANA
XS), you define database views that provide the data with the required granularity and you use the XMLA
service definition to control access to the exposed data.

Note
SAP HANA XS supports XMLA version 1.1, which you can use to send MDX queries.

An XMLA service for SAP HANA XS is defined in a text file with the file suffix .xsxmla, for example,
XMLASrvDef.xsxmla. The file must contain only the entry {*}, which would generate a completely
operational XMLA service.

XMLA Service-Definition Keywords

Currently, the XMLA service-definition file enables you to specify only that all authorized data is exposed to
XMLA requests, as illustrated in the following example:

Service {*}

6.2.6 XMLA Security Considerations

Enabling access to data by means of XMLA opens up some security considerations that you need to address,
for example, the data you want to expose, who can start the XMLA service, and so on.

If you want to use XMLA to expose data to users and clients in SAP HANA XS, you need to bear in mind the
security considerations described in the following list:

● Data Access
Restrict user select authorization for data exposed by the XMLA service

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 331
● XMLA Statistical content
Restrict access to the URL/Path used to expose XMLA content in the Web browser, for example, using the
application-access file (.xsaccess)

6.2.7 Multidimensional Expressions (MDX)

Multidimensional Expressions (MDX) is a language for querying multidimensional data that is stored in OLAP
cubes.

MDX uses a multidimensional data model to enable navigation in multiple dimensions, levels, and up and down
a hierarchy. With MDX, you can access pre-computed aggregates at specified positions (levels or members) in
a hierarchy.

Note
MDX is an open standard. However, SAP has developed extensions to MDX to enable faster and more
efficient access to multidimensional data; for example, to serve specific SAP HANA application
requirements and to optimize the result set for SAP HANA clients.

MDX is implicitly a hierarchy-based paradigm. All members of all dimensions must belong to a hierarchy. Even
if you do not explicitly create hierarchies in your SAP HANA data model, the SAP HANA modeler implicitly
generates default hierarchies for each dimension. All identifiers that are used to uniquely identify hierarchies,
levels and members in MDX statements (and metadata requests) embed the hierarchy name within the
identifier.

In SAP HANA, the standard use of MDX is to access SAP HANA models (for example, analytical and attribute
views) that have been designed, validated and activated in the modeler in the SAP HANA studio. The studio
provides a graphical design environment that enables detailed control over all aspects of the model and its
language-context-sensitive runtime representation to users.

MDX in SAP HANA uses a runtime cube model, which usually consists of an analytical (or calculation) view that
represents data in which dimensions are modeled as attribute views. You can use the analytical view to specify
whether a given attribute is intended for display purposes only or for aggregation. The attributes of attribute
views are linked to private attributes in an analytic view in order to connect the entities. One benefit of MDX in
SAP HANA is the native support of hierarchies defined for attribute views.

Note
MDX in SAP HANA includes native support of hierarchies defined for attribute views. SAP HANA supports
level-based and parent-child hierarchies and both types of hierarchies are accessible with MDX.

SAP HANA supports the use of variables in MDX queries; the variables are an SAP-specific enhancement to
standard MDX syntax. You can specify values for all mandatory variables that are defined in SAP HANA studio
to various modeling entities. The following example illustrates how to declare SAP HANA variables and their
values:

MDX
Select
From [SALES_DATA_VAR]
Where [Measures].[M2_1_M3_CONV]
SAP VARIABLES [VAR_VAT] including 10,

SAP HANA Developer Guide

332 PUBLIC Defining Web-based Data Access
 [VAR_K2] including 112,
[VAR_TARGET_CURRENCY] including 'EUR',

6.2.8 MDX Functions

MDX in SAP HANA supports a variety of standard MDX functions.

The following MDX functions are supported:

Aggregate
Ancestor
Ancestors
Ascendants
Avg
BottomCount
Children
ClosingPeriod
Count
Cousin
Crossjoin
CurrentMember
DefaultMember
Descendants
Dimension
Dimensions
Distinct
DistinctCount
DrillDownLevel
DrillDownLevelBottom
DrillDownLevelTop
DrillDownMember
DrillDownMemberBottom
DrillDownMemberTop
DrillUpLevel
DrillUpmember
Except
Filter
FirstChild
FirstSibling
Generate
Head
Hierarchize
Hierarchy
Instr

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 333
 Intersect
IsAncestor
IsGeneration
IsLeaf
IsSibling
Item
IIF
Lag
LastChild
LastPeriods
LastSibling
Lead
Leaves
Left
Level
Levels
Max
Member_caption
Members
MembersAscendantsDescendants
Mid
Min
MTD
Name
NextMember
NOT
OpeningPeriod
OR
Ordinal
ParallelPeriod
Parent
PeriodsToDate
PrevMember
Properties
QTD
Range
Right
Siblings
StrToMember
StrToSet
StrToTuple
StrToValue
Subset
Sum
Tail

SAP HANA Developer Guide

334 PUBLIC Defining Web-based Data Access
 TopCount
Union
UniqueName
WTD
YTD

For more information about these functions, see Microsoft's Multidimensional Expressions (MDX) Reference.

Related Information

https://msdn.microsoft.com/en-us/library/ms145506.aspx

6.2.9 MDX Extensions

SAP HANA supports several extensions to the MDX language, including additional predefined functions and
support for variables.

6.2.9.1 Sibling_Ordinal Intrinsic Property

The object Member includes a property called Sibling_Ordinal, that is equal to the 0-based position of the
member within its siblings.

Example

WITH
MEMBER [Measures].[Termination Rate] AS
[Measures].[NET_SALES] / [Measures].[BILLED_QUANTITY]
SELECT
{
[Measures].[NET_SALES],
[Measures].[BILLED_QUANTITY],
[Measures].[Termination Rate]
} ON COLUMNS,
Descendants
(
[DISTRIBUTION_CHANNEL].[DISTRIBUTION_CHANNEL].[All].[(all)],
1,
SELF_AND_BEFORE
)
DIMENSION PROPERTIES SIBLING_ORDINAL ON ROWS
FROM SALES_DATA

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 335
6.2.9.2 MembersAscendantsDescendants Function

SAP HANA includes the MembersAscendantsDescendants function that enables you to get, for example, all
ascendants and descendants of a specific member.

This function improves on the standard MDX functions Ascendants and Descendants.

The function can be called as follows:

MembersAscendantsDescendants (<set>, <flag>)

● set: A set of members from a single hierarchy

● flag: Indicates which related members to return, and can be one of the following:
○ MEMBERS_AND_ASCENDANTS_AND_DESCENDANTS
○ MEMBERS_AND_ASCENDANTS
○ MEMBERS_AND_DESCENDANTS
○ ASCENDANTS_AND_DESCENDANTS
○ ONLY_ASCENDANTS
○ ONLY_DESCENDANTS

Example

SELECT
{ [Measures].[SALES] }
ON COLUMNS,
NON EMPTY
{ Hierarchize( MembersAscendantsDescendants([SALES_DATA_TIME].[TimeHier].
[QUARTER].[3]:[SALES_DATA_TIME].[TimeHier].[QUARTER].[4],
MEMBERS_AND_ASCENDANTS_AND_DESCENDANTS )) }
ON ROWS
FROM [SALES_DATA]

Example

SELECT
{ [Measures].[SALES] }
ON COLUMNS,
NON EMPTY
{ Hierarchize( MembersAscendantsDescendants([SALES_DATA_TIME].[TimeHier].
[QUARTER].[3]:[SALES_DATA_TIME].[TimeHier].[QUARTER].[4], ONLY_ASCENDANTS )) }
ON ROWS
FROM [SALES_DATA]

6.2.9.3 Variables in MDX

An MDX SELECT statement in SAP HANA enables you to send values for variables defined within modeling
views.

Analytic and calculation views can contain variables that can be bound to specific attributes. When calling the
view, you can send values for those variables. These variables can be used, for example, to filter the results.

SAP HANA Developer Guide

336 PUBLIC Defining Web-based Data Access
SAP HANA supports an extension to MDX whereby you can pass values for variables defined in views by adding
an SAP Variables clause in your SELECT statement. Here is the syntax for a SELECT statement:

<select_statement>:
[WITH <formula_specification> ]
SELECT [<axis_specification>[,<axis_specification>...]]
FROM <cube_specification>
[WHERE <slicer_specification>

SAP VARIABLES: <sap_variable> [[,] <sap_variable>…]]

<sap_variable>: <variable_name> <sign> [<option>] <variable_value>
<sign>: INCLUDING | EXCLUDING
<option>: = | > | >= | < | <= | <>
<variable_value>:
<unique_member_name>
| <unsigned_numeric_literal>
| <string_value_expression>
| <member> : <member>
| <character_string_literal> : <character_string_literal>
| <unsigned_numeric_literal> : <unsigned_numeric_literal>

Example
The following statement specifies a single value for variables VAR_VAT, VAR_K2, and
VAR_TARGET_CURRENCY.

SELECT
FROM [SALES_DATA_VAR]
WHERE [Measures].[M2_1_M3_CONV]
SAP VARIABLES [VAR_VAT] including 10,
[VAR_K2] including 112,
[VAR_TARGET_CURRENCY] including 'EUR'

Example
The following specifies an interval for variable VAR_K2.

SELECT NON EMPTY

{
[K2].[K2].Members
}ON ROWS
FROM [SALES_DATA_VAR_SIMPLE]
WHERE [Measures].[M3_CONV]
SAP VARIABLES [VAR_K2] including [K2].[K2].&[122]:[K2].[K2].&[221]

Metadata on Variables in Views

SAP HANA includes the following set of tables that contain information about the variables defined for views:

● BIMC_VARIABLE
● BIMC_VARIABLE_ASSIGNMENT
● BIMC_VARIABLE_VALUE

The tables enable, for example, an application to retrieve the variables defined for a view and create a user
interface so the user can enter values.

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 337
6.3 Using the SAP HANA REST API

The SAP HANA REST Application Programming Interface (REST API) is based on and extends the Orion server
and client APIs.

SAP HANA REST API supports the Orion protocol 1.0 which allows development tools to access the SAP HANA
Repository in a convenient and standards-compliant way. This not only makes access to the Repository easier
for SAP HANA tools, but it also enables the use of Orion-based external tools with the SAP HANA Repository.
For SAP tools, the Orion server protocol has been extended with the following SAP HANA-specific features

● Activate design-time artifacts in the Repository

● Perform change-tracking operations (assuming change-tracking is enabled in the target SAP HANA
system)
● Searching the database catalog

SAP HANA REST Application Programming Interfaces

API Description

File Enables access to services that you to browse and manipulate files and directories via HTTP

Workspace Enables you to create and manipulate workspaces and projects via HTTP

Transfer Enables you to import and export packages and files

Metadata Enables access to services that support search and auto-completion scenarios, for example, to
retrieve metadata from runtime, design-time, and other metadata locations

Change Tracking Enables the use of specific lifecycle-management features included with the SAP HANA Reposi­
tory via HTTP

Info Enables access to information about the current version of the SAP HANA REST API

The SAP HANA REST API uses an additional parameter called SapBackPack to send request parameters that
are specific to SAP HANA; the SapBackPack parameter is added to the HTTP header. The value of the
SapBackPack parameter is a JSON object with the attributes and values of the additional SAP-specific
parameters. For example, when you create or update the content of a design-time artifiact, you can use the
SapBackPack value {"Activate":true} to request that the new version of the file is immediately activated
in the SAP HANA Repository. If you only want to create an inactive version of a design-time artifact, you can use
the “workspace” attribute to specify the name of the the Repository workspace where the inactive version is
to be stored.

Related Information

SAP HANA REST Info API [page 339]

SAP HANA REST File API [page 339]
SAP HANA REST Change-Tracking API [page 345]
SAP HANA REST Metadata API [page 346]
SAP HANA REST Transfer API [page 347]
SAP HANA REST Workspace API [page 348]
SAP HANA REST API Reference

SAP HANA Developer Guide

338 PUBLIC Defining Web-based Data Access
6.3.1 SAP HANA REST Info API

The SAP HANA REST API includes an Info API that can be used to display information about the current version
of the REST API.

GET /sap/hana/xs/dt/base/info
Orion-Version: 1.0

The information displayed by the Info API includes a description of the current version of the delivery unit and
the number of commands (API entry points) that are currently supported by the REST API.

HTTP/1.1 200 OK
{
"DeliveryUnit":{
"name":"HANA_DT_BASE",
"version":"1",
"responsible":"x###007,x###077",
"vendor":"sap.com",
"version_sp":"0",
"version_patch":"8",
"ppmsID":"",
"caption":"",
"lastUpdate":1386163749544,
"sp_PPMS_ID":"",
"ach":""
},
"Commands":[
"/sap/hana/xs/dt/base/file",
"/sap/hana/xs/dt/base/workspace",
"/sap/hana/xs/dt/base/xfer/import",
"/sap/hana/xs/dt/base/metadata",
"/sap/hana/xs/dt/base/change",
"/sap/hana/xs/dt/base/info"
]
}

Related Information

Using the SAP HANA REST API [page 338]

SAP HANA REST API Reference

6.3.2 SAP HANA REST File API

The SAP HANA REST API includes a File API which uses the basic HTTP methods GET, PUT, and POST to send
requests. JSON is used as the default representation format.

The File API enables you to perform the following actions:

Action Description

Actions on files [page 340] Get, set, or change file content and metadata

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 339
Action Description

Actions on directories [page 341] Get and change directory metadata and list directory con­
tents

Create files and directories [page 342] Create files and directories with or without content

Copy and move files [page 342] Copy, move, or delete files and directories

Mass transfer actions [page 343] Get multiple files (or file metadata) from a list, repository
package, or a workspace

Change tracking [page 344] Activate selectively the latest approved versions of reposi­
tory objects

Actions on Files

GET /sap/hana/xs/dt/base/file/MyProj/myfile.txt
Orion-Version: 1.0
If-Match: "358768768767"
SapBackPack: "{'Workspace': 'ABC', 'Version': 12}"

The REST File API enables you to retrieve the content of a specific file, for example, myfile.txt.

Note
In the request illustrated in the example above, the parameters Version, If-Match, and SapBackPack are
optional

The response to the retrieval request is displayed in the following example:

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
This is the content

The REST File API enables you to retrieve the metadata associated with a specific file, for example,
myfile.txt.

Note
In the request illustrated in the example below, the parameters Version, If-Match, and SapBackPack are
optional

GET /sap/hana/xs/dt/base/file/MyProj/myfile.txt?parts=meta
Orion-Version: 1.0
SapBackPack: "{'History': 'false', 'Version': 12}"
If-Match: "35987989879"

The response to the retrieval request for metadata is displayed in the following example:

{
"Name": "myfile.txt",
"Location": "/sap/hana/xs/dt/base/file/MyProj/myfile.txt",

SAP HANA Developer Guide

340 PUBLIC Defining Web-based Data Access
 "RunLocation": "/MyProj/myfile.txt",
"ETag": "35987989879",
"Directory": false,
"LocalTimeStamp": 01234345009837,
"Attributes": {
"ReadOnly": false,
"Executable": false,
"SapBackPack" : {'Activated' : true}
}
"SapBackPack": {
"Version":60,
"ActivatedAt":1397644007537,
"ActivatedBy":"User"
}
}

Actions on Directories

You can use the REST File API to retrieve and change directory (repository package) metadata as well as list the
contents of a directory. The following example shows how to list the contents of a singel directory, for example,
myfolder.

Tip
To list all files from a directory recursively, use depth=infinity or -1. For security reasons the depth is
limited to 1000.

GET /sap/hana/xs/dt/base/file/MyProj/myfolder?depth=1

The following example shows the response to the directory listing request:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
{
"Name": "myfolder",
"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder",
"ContentLocation": "/MyProj/myfolder",
"LocalTimeStamp": 01234345009837,
"Directory": true
"Attributes": {
"ReadOnly": false,
"Executable": false
},
"Children": [
{
"Name": "myfile.txt",
"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/myfile.txt",
"RunLocation": "/MyProj/myfolder/myfile.txt",
"Directory": false
} ] }

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 341
File and Directory Creation

You can use the REST File API to create files and directories (repository packages) with or without content. The
following example shows how to create a new directory, for example, myfolder.

Note
If a parent directory (in which the new directory is created) is already assigned to a delivery unit, the created
directory will be assigned automatically to the same delivery unit.

POST /sap/hana/xs/dt/base/file/MyProj/
Content-Type: application/json
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
Slug: myfolder
{
"Name": "myfolder",
"Directory": "true"
}

The following example shows the response to the directory creation request:

HTTP/1.1 201 OK
{
"Name": "myfolder",
"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder",
"ContentLocation": "/MyProj/myfolder",
"ETag": "35fd43td3",
"LocalTimeStamp": 01234345009837,
"Directory": true
"Attributes": {
"ReadOnly": false,
"Executable": false
}
}

Copying and Moving Files

You can use the REST File API to copy, move, or delete files and directories (repository packages). You can also
use the File API to delete the workspace that contains files and directories used for development work. The
following example shows how to delete a directory, for example, myfolder.

DELETE /sap/hana/xs/dt/base/file/MyProj/myfile.txt
Orion-Version = 1.0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
If-Match: "35" (optional)

The following example shows how to delete a workspace.

Note
You need to include the parameters ProcessWorkspace=true and Workspace in the SapBackPack
parameter.

DELETE /sap/hana/xs/dt/base/file/MyProj/myfile.txt

SAP HANA Developer Guide

342 PUBLIC Defining Web-based Data Access
 Orion-Version = 1.0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
SapBackPack: "{'Workspace': 'ABC', 'ProcessWorkspace': true}"

Both requests should receive the following reponse:

HTTP/1.1 204 OK

Mass File Transfer

Mass transfer with the REST File API enables you to apply GET and PUT operations to multiple files in a single
HTTP request.

Note
The mass-transfer feature is not a part of the Orion specification; it was developed to optimize the
performance of GET and PUT requests when dealing with a large number of files.

There are different ways of specifying the file paths. One way is to point the request's URL to the root of the file
repository, as illustrated in the request example below. In this case, you must specify the complete path from
the root of the repository for each file. Another possibility is to point the request's URL to a specified sub-
package in the Repository, which is then considered to be the root package for the files to be retrieved in the
request. To request a file's meta-data, use the parameter parts=meta; the response contains a list of file
metadata formatted as a JSON string. If the request does not contain the parameter parts=meta, a multipart
response is returned.

GET /sap/hana/xs/dt/base/file?parts=meta
Orion-Version = 1.0
SapBackPack: '{"MassTransfer":true, "MassTransferData": [
{"Pkg":"MyProj/myfolder","Name":"destination1.txt","Dir":false}, ...]}'

The response expected should look like the following example:

HTTP/1.1 200 OK
Content-Type: application/json
[
{
"Name": "destination1.txt",
"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination1.txt",
"RunLocation": "/MyProj/myfolder/destination1.txt",
"ETag": "351234567",
"LocalTimeStamp": 01234345009837,
"Directory": false
"Attributes": { "ReadOnly": false, "Executable": true, "SapBackPack" :
{'Activated' : true}}
},
{
"Name": "destination2.txt",
"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination2.txt",
"RunLocation": "/MyProj/myfolder/destination2.txt",
"ETag": 251237891,
"LocalTimeStamp": 01234345009837,
"Directory": false,
"Attributes": { "ReadOnly": false, "Executable": true, "SapBackPack" :
{'Activated' : true} }
}

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 343
 ]

Change Tracking

Use can use the REST File API to perform change-tracking operations. Change tracking enables you to activate
selectively the latest approved versions of objects.

Note
This feature of the REST File API assumes that the change-tracking feature is enabled in the SAP HANA
repository.

PUT /sap/hana/xs/dt/base/file/PATH?parts=meta
Orion-Version = 1.0
X-CSRF-Token: securityToken
SapBackPack: '{"MassTransfer":true, "Activate":true, "ChangeId": "ABC//11111",
"ChangeIdList": [{"Path": "PATH/file1.txt", "ChangeId" = "ABC//12345"},
{"Path": "PATH/file2.txt", "ChangeId" = "ABC//12345"}]}'

If an object (or a set of objects) is activated using the default change-tracking handling (for example, without
setting SapBackPack.ChangeTrackingMode or by setting SapBackPack.ChangeTrackingMode explicitly
to 0), a dynamic change list is created, and the file(s) are activated in the SAP HANA Repository using the
generated change list.

In the explicit handling of change tracking the user is allowed to activate files that are already assigned to a
change list. Files can also be activated using an explicitly provided change list ID. In the change-tracking
request above, the files PATH/file1.txt and PATH/file2.txt are assigned to the change list ABC//12345.
All other files will be activated using the change list ABC//11111.

The response to the change-tracking request would look like the following example:

HTTP/1.1 200 OK
Content-Type: application/json
...

Related Information

Using the SAP HANA REST API [page 338]

SAP HANA REST API Reference

SAP HANA Developer Guide

344 PUBLIC Defining Web-based Data Access
6.3.3 SAP HANA REST Change-Tracking API

The SAP HANA REST API includes a Change Tracking API which enables you to make use of specific lifecycle-
management features that are included with the SAP HANA Repository via HTTP.

Change Tracking is integrated with the SAP HANA XS Repository transport tool set; with change tracking
enabled, you can ensure that an export operation (to build a delivery unit) includes only the latest approved
versions of repository objects.

Note
To use the Change-Tracking API, change tracking must enabled in the SAP HANA system whose repository
you are accessing.

To obtain the current status of change tracking in the system, for example, enabled or disabled, you can send a
GET request to the change entry point of the REST API.

GET /sap/hana/xs/dt/change

If the change tracking feature is enabled in the target system, the resulting response is true. If change
tracking is disabled in the target sytem or not supported by the system, the response to the the GET status
request is false

HTTP/1.1 200 OK
{
"ChangeTrackingStatus": true
}

You can also use the REST Change-Tracking API to manage change lists and track changes made to repository
objects. For example, to display all change lists, for which a specified user (“XYZ”) is a contributor:

GET /sap/hana/xs/dt/base/change
SapBackPack: {'User': 'XYZ', 'Status': 1}

The response would look like the following example:

HTTP/1.1 200 OK
[
{
"changeID":"ABC//1234",
"status":1,
"description":"",
"createdOn":"2014-04-09T13:26:58.868Z",
"createdBy":"XYZ"
},
{
"changeID":"ABC//1235",
"status":1,
"description":"",
"createdOn":"2014-04-09T14:08:53.024Z",
"createdBy":"XYZ"
}
]

To display the change status of a single file SomeFile.txt, use the following command:

GET /sap/hana/xs/dt/base/change/MyProj/SomeFile.txt

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 345
The response would look like the following example, which shows the change ID and the user responsible for
the change:

HTTP/1.1 200 OK
{
"ChangeId":"ABC//1234",
"User":"XYZ"
}

Related Information

Using the SAP HANA REST API [page 338]

SAP HANA REST API Reference

6.3.4 SAP HANA REST Metadata API

The SAP HANA REST API includes a Metadata API which provides services to support search and
autocompletion scenarios

The REST-based Metadata API enables you to retrieve metadata from runtime and design-time objects as well
as other metadata locations. The typical location of runtime metadata is the SAP HANA database catalog. It is
possible to retrieve metadata for tables, views, procedures, functions, sequences, and schemas. The design-
time location for metadata is the SAP HANA Repository. Also accessible is the metadata location used by Core
Data Services (CDS).

The following services are provided with the Metadata API in the default location /sap/hana/xs/dt/base/
metadata; the services are called by setting the HTTP parameter Service-Name to the appropriate value:

● checkMetadataExistence
Checks for the existence of a provided set of entities and returns an array of entries which indicates if a
specified entity exists or not.
● checkMetadataExistence URI
Checks for the existence of a specifc resource (entity) uniquely expressed as an HTTP universal resource
indicator (URI). checkMetadataExistence URI returns an array of entries which indicates if a given
entity exists or not.
● getMetadataSuggestion

Note
This part of the interface only supports HTTP GET requests.

The following example shows how to use checkMetadataExistence URI to check for the existence of a
specifc URI resource.

var strPayloadFromJava = "{}";

var strHeaderServiceName = "checkMetadataExistence";
var strSapBackPack = strPayloadFromJava;
var strAccessPath = cMetaDataAccessP + '/VIEW/RT/TABLES';
var request = new $.net.http.Request($.net.http.GET, strAccessPath);

SAP HANA Developer Guide

346 PUBLIC Defining Web-based Data Access
 request.headers.set('SapBackPack', strSapBackPack);
request.headers.set('Service-Name', strHeaderServiceName);
var response = client.request(request, destination).getResponse();

checkMetadataExistence URI returns an array of entries which indicates if a given entity exists or not.

List<metadata>
localName
isExist
List<exist> [6]
namespace
separator [7]
baseLocalName
baseType
type
mode [8]
desc

Related Information

Using the SAP HANA REST API [page 338]

SAP HANA REST API Reference

6.3.5 SAP HANA REST Transfer API

The SAP HANA REST Transfer API is used to import and export packages and files.

You can use the Transfer API to perform both import and export operations:

● Import [page 347]

Upload files to the SAP HANA Repository, for example, using POST, PUT, or FTP
● Export [page 348]
Download files from the SAP HANA Repository to a client

Importing Files

The following example shows how to use the Transfer API to start an operation to upload files to the SAP HANA
Respository. The request URL uses the POST command to perform the action and must indicate the target
location of the uploaded file when the upload operation is complete. The request must also indicate the total
size of the file the server should expect to receive during the upload operation.

POST /sap/hana/xs/dt/base/xfer/import/MyProj/SomeFile.jpg
Orion-Version: 1.0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
Slug: MyFile.jpg
X-Xfer-Content-Length: 901024
X-Xfer-Options: raw

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 347
The reponse to the request would look as follows:

HTTP/1.1 200 OK
Location: /sap/hana/xs/dt/base/xfer/import/fks3kjd7hf
ContentLocation: /xfer/fks3kjd7hf

After initiating the transfer, uploads are performed as many times as required using PUT actions.

PUT /sap/hana/xs/dt/base/xfer/import/fks3kjd7hf
Orion-Version: 1.0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
Content-Length: 32768
Content-Type: image/jpeg
Content-Range: bytes 0-32767/901024

For each successfull upload operation, you should see the following response:

HTTP/1.1 200 success

Range: bytes 0-32767

Exporting Files

You can use the REST Transfer API to export (download) files and packages to a designated client in a zip
archive, as illustrated in the following example:

GET /sap/hana/xs/dt/base/xfer/export/MyProj/SomeFolder.zip
Orion-Version: 1.0

For each successfull download operation, you should see the following response:

HTTP/1.1 201 OK
Content-Type: application/zip
File contents.

Related Information

Using the SAP HANA REST API [page 338]

SAP HANA REST API Reference

6.3.6 SAP HANA REST Workspace API

The Workspace API enables you to create and manipulate Repository workspaces and projects via HTTP.

With the Workspace API, you can perform the following types of operation on workspaces and projects:

● Workspaces
List available workspaces, create or delete a workspace, and display or change workspace metadata

SAP HANA Developer Guide

348 PUBLIC Defining Web-based Data Access
● Projects
Add projects to a workspace, move (or rename) a project, remove a project from a workspace

Workspace Actions

You can use the REST Workspace API to create a new workspace called “My Dev Workspace”, as illustrated in
the following example:

POST sap/hana/xs/dt/base/workspace
EclipseWeb-Version: 1.0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
Slug: My Dev Workspace

The response to the workspace-creation request should look like the following example:

HTTP/1.1 201 Created

Location: [http://example.com/sap/hana/xs/dt/base/file/sap/hana/xs/dt/base/
content/workspace/SAM_My_Dev_workspace_0]
ETag: "1"
Content-Type: application/json
{
"Id": "SAM_My_Dev_workspace_0",
"Name": "My Dev Workspace",
"Location": "http://example.com/sap/hana/xs/dt/base/file/sap/hana/xs/dt/base/
content/workspace/SAM_My_Dev_workspace_0",
"Projects": [],
"Children": []
}

Projects

You can also use the REST Workspace API to create a new SAP HANA XS project (“My Project”) and add it an
existing workspace (“My Dev Workspace”), as illustrated in the following example. The Workspace API creates
the new project as an SAP HANA XS subpackage in the specified workspace package. The new project is
assigned to the list of projects in the specified workspace's metadata.

Note
The new project is not an SAP HANA XS application package.

POST /sap/hana/xs/dt/base/workspace/SAM_My_Dev_workspace_0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
EclipseWeb-Version: 1.0
Slug: "My Project"

The response to the project-creation request should look like the following example:

{
"Id": "SAM_My_Dev_Workspace_0_My_Project_0",
"Location": "http://localhost:8080/sap/hana/xs/dt/base/file/sap/hana/xs/dt/base/
content/workspace/SAM_My_Dev_Workspace_0/My Project",
"ContentLocation": "http://localhost:8080/sap/hana/xs/dt/base/file/sap/
hana/xs/dt/base/content/workspace/SAM_My_Dev_Workspace_0/My Project",

SAP HANA Developer Guide

Defining Web-based Data Access PUBLIC 349
 "Name": "My Project"
}

Related Information

Using the SAP HANA REST API [page 338]

SAP HANA REST API Reference

SAP HANA Developer Guide

350 PUBLIC Defining Web-based Data Access
7 Writing Server-Side JavaScript Code

SAP HANA Extended Application Services (SAP HANA XS) provide applications and application developers
with access to the SAP HANA database using a consumption model that is exposed via HTTP.

In addition to providing application-specific consumption models, SAP HANA XS also host system services that
are part of the SAP HANA database, for example: search services and a built-in Web server that provides
access to static content stored in the SAP HANA repository.

The consumption model provided by SAP HANA XS focuses on server-side applications written in JavaScript.
Applications written in server-side JavaScript can make use of a powerful set of specially developed API
functions, for example, to enable access to the current request session or the database. This section describes
how to write server-side JavaScript code that enables you to expose data, for example, using a Web Browser or
any other HTTP client.

7.1 Data Access with JavaScript in SAP HANA XS

In SAP HANA Extended Application Services, the persistence model (for example, tables, views and stored
procedures) is mapped to the consumption model that is exposed via HTTP to clients - the applications you
write to extract data from SAP HANA.

You can map the persistence and consumption models in the following way:

● Application-specific code
Write code that runs in SAP HANA application services. Application-specific code (for example, server-side
JavaScript) is used in SAP HANA application services to provide the consumption model for client
applications.

Applications running in SAP HANA XS enable you to accurately control the flow of data between the
presentational layer, for example, in the Browser, and the data-processing layer in SAP HANA itself, where the
calculations are performed, for example in SQL or SQLScript. If you develop and deploy a server-side
JavaScript application running in SAP HANA XS, you can take advantage of the embedded access to SAP
HANA that SAP HANA XS provides; the embedded access greatly improves end-to-end performance.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 351
7.2 Using Server-Side JavaScript in SAP HANA XS

SAP HANA application services (XS server) supports server-side application programming in JavaScript. The
server-side application you develop can use a collection of JavaScript APIs to expose authorized data to client
requests, for example, to be consumed by a client GUI such as a Web browser or any other HTTP client.

The functions provided by the JavaScript APIs enable server-side JavaScript applications not only to expose
data but to update, insert, and delete data, too. You can use the JavaScript APIs to perform the following
actions:

● Interact with the SAP HANA XS runtime environment

● Directly access SAP HANA database capabilities
● Interact with services on defined HTTP destinations.

JavaScript programs are stored in the repository along with all the other development resources. When the
programs are activated, the code is stored in the repository as a runtime object.

Tip
To enable the Web Browser to display more helpful information if your JavaScript code causes an HTTP 500
exception on the SAP HANA XS Web server, ask someone with administrator privileges to start the SAP
HANA studio's Administration Console perspective and add the parameter developer_mode to the
xsengine.ini httpserver section of the Configuration tab and set it to true.

Related Information

JavaScript Security Considerations [page 361]

7.2.1 Tutorial: Write Server-Side JavaScript Application Code

SAP HANA Extended Application Services (SAP HANA XS) supports server-side application programming in
JavaScript. The server-side application you develop uses JavaScript APIs to expose authorized data to client
requests, for example, for consumption by a client GUI such as a Web browser, SAPUI5 applications, or mobile
clients.

Prerequisites

You have the privileges granted by the role sap.hana.ide.roles::EditorDeveloper; this role is included in the
parent role sap.hana.ide.roles::Developer.

SAP HANA Developer Guide

352 PUBLIC Writing Server-Side JavaScript Code
Context

In this introductory tutorial, you create a simple application that consists of the following files:

● hello.xsjs: a JavaScript file containing the application code.

● Application descriptors .xsaccess and .xsapp: mandatory for all applications deployed on SAP HANA
extended application services (SAP HANA XS).
● Access privileges file .xsprivileges: optional

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. From the context menu of the Content folder, choose Create Application.
3. Choose the Empty application (with XSAccess and XSApp) template.
4. Enter a package name, for example, helloxsjs, and choose Create.
The system creates an index.html file and the application descriptors (.xsaccess and .xsapp).
5. Delete the automatically created index.html file.
6. Select the .xsaccess file you just created for your new XSJS application and enter the following content:

{
"exposed" : true,
"authentication" : { "method": "Form" }
"authorization": // Optional: see xsprivileges file
[
"helloxsjs::Execute",
"helloxsjs::Admin"
]
}

7. Save the application-access file in the repository.

8. If you used the authorization keyword in the application-access file (.xsaccess) file for your application,
create an application-privileges file for the application and define the application privileges.

The application-privileges file does not have a name; it only has the file extension .xsprivileges. The
contents of the .xsprivileges file must be formatted according to JavaScript Object Notation (JSON)
rules. The privileges defined in a .xsprivileges file are bound to the package to which the file belongs
and can only be applied to this package and its subpackages.

Note
The .xsprivileges file lists the authorization levels available for granting to an application package;
the .xsaccess file defines which authorization level is assigned to which application package.

a. Select the helloxsjs package and from the context menu choose New File .
b. Enter the file name .xsprivileges and choose Create.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 353
 c. Enter the following content in the .xsprivileges file:

{
"privileges" :
[
{ "name" : "Execute", "description" : "Basic execution
privilege" },
{ "name" : "Admin", "description" : "Administration privilege" }
]
}

d. Save the application-privileges file in the repository.

9. Assign the application privilege to the users who require it.
After activation of the .xsprivileges object, the only user who by default has the application privileges
specified in the .xsprivileges file is the _SYS_REPO user. To grant the specified privilege to other users,
use the GRANT_APPLICATION_PRIVILEGE in the _SYS_REPO schema.
To grant the execute application privilege to a user, open the catalog and run the following command in the
SQL editor:

call
"_SYS_REPO"."GRANT_APPLICATION_PRIVILEGE"('"helloxsjs::Execute"','<UserName>')

10. Create the server-side JavaScript (XSJS) files that contain the application logic.
Server-side JavaScript files have the file suffix .xsjs, for example, hello.xsjs and contain the code that
is executed when SAP HANA XS handles a URL request.

a. Select the helloxsjs package and from the context menu choose New File .
b. Enter the file name hello.xsjs and choose Create.
c. Enter the following content in the .xsjs file:

$.response.contentType = "text/plain";
$.response.setBody( "Hello, World!");

d. Save the XSJS file in the repository.

11. Check the package structure.
Your application package structure should look like the example shown below:

.
\
helloxsjs
\
.xsapp
.xsaccess
.xsprivileges // optional
hello.xsjs

12. To view the results, select the hello.xsjs file and choose (Run) in the toolbar.

SAP HANA Developer Guide

354 PUBLIC Writing Server-Side JavaScript Code
7.2.2 JavaScript Editor

You can write server-side JavaScript using the JavaScript editor, which provides syntax validation and code
highlighting.

Code Validation

The JavaScript editor in the SAP HANA Web-based Development Workbench includes the ESLint open-source
library, which helps to validate Javascript code. All JavaScript files (.js, .xsjs, and .xsjslib) are checked.
The editor highlights any code that does not conform to ESLint standards and flags each issue detected
according to its severity as follows: error (red); warning (yellow); information (blue).

By hovering over a flag, you can display a tooltip that describes one or more detected issues with the following
information:

● Category: Classifies the issue, for example, possible error, best practice, stylistic issue, and others.
● Rule ID: Defines the issue. For example, the rule ID semi enforces the use of semicolons.
● Message: Details the issue.

Example

The ESLint code check is enabled by default. In the Editor settings, you can configure the severity level of the
code check, disable the code check entirely, or just so that it is not triggered every time you make a change to
the code.

Quick Fixes

ESLint quick fixes allow you to correct errors quickly and are supported for the following ESLint rules:

● http://eslint.org/docs/rules/eqeqeq
● http://eslint.org/docs/rules/quotes
● http://eslint.org/docs/rules/no-comma-dangle
● http://eslint.org/docs/rules/no-extra-semi
● http://eslint.org/docs/rules/no-space-before-semi
● http://eslint.org/docs/rules/semi

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 355
● http://eslint.org/docs/rules/space-infix-ops

You can apply the fixes available for the issues detected in your code by choosing Apply Selected Quick Fixes in
the context menu of the file. Alternatively, open the context menu on a line with a highlighted issue to display
and apply a specific quick fix, as shown in the example below:

Beautify

Beautify JavaScript to make the source code more readable. Once applied, the code is reformatted by parsing
the JavaScript source code into components, (for example, statements, blocks, and so on) and applying the
correct style and format to the code. The beautifier, for example:

● Removes superfluous lines and adds line breaks where necessary

● Removes or adds spaces, for example, before conditional if statements
● Corrects code indentation
● Corrects the positioning of curly braces (opening curly braces are placed on the same line as the
corresponding statement)

You can beautify any open JavaScript file by choosing Beautify from the context menu.

Related Information

ESLint Rules
Configuring ESLint

SAP HANA Developer Guide

356 PUBLIC Writing Server-Side JavaScript Code
7.2.3 Displaying the Function Flow

The function flow is a tool that allows you to view an outline list and code flow visualization of the functions
called within a JavaScript file. It also lets you display code previews of function definitions as well as navigate
directly to the function definitions in the source code.

Context

The function flow provides a graphical and list view of the functions in a file.

● Function graph: Shows the calls being made from and to the currently active function (based on your
cursor position):
○ Red node: the currently active function
○ Blue nodes: functions defined in the displayed file
○ Gray nodes: functions defined elsewhere
○ Dotted arcs: calls to functions defined in the same file
○ Solid arcs: calls to functions defined elsewhere
● Function list: Shows an outline of the functions and objects (which in turn contain functions) present in the
code. The active function shows, when expanded, the calls being made from and to it:

○ Calls this function

○ Is called by this function

Procedure

1. Open a JavaScript file and choose (Show function flow) in the toolbar.
The Outline panel opens on the right. The caller-callee relationships of the function or object in which the
cursor is positioned are shown in both the graph and list.

Example:

2. Choose an option.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 357
 Function Graph Description

Navigate to a function ○ Double-click the blue node in the function graph.

○ Double-click the gray node in the function graph (if the function is defined
within the same package).

The cursor focus changes in both the list and graph. The graph is now centered on
the newly selected function.

Note
The function flow reacts only to cursor position changes. A double-click causes
the cursor position to change, placing it inside the selected entity and making
the function flow (both graph and list) react and update accordingly. Similarly,
whenever the cursor is moved inside the code, the information in the Outline
panel is updated automatically.

Navigate backward and for­ Choose the back arrow button located in the function graph toolbar to navigate
ward in the graph back to the previously selected function. Navigate forward again by choosing the
forward arrow.

Highlight a function in the Click the function node in the graph.

code
The corresponding entity is highlighted in the code.

Highlight a function call in the Click the arc in the graph.

code
The section of code is highlighted where the corresponding call is made.

Move the cursor freely within Choose the (Lock) button in the function graph toolbar.
the file while retaining the cur­
rent state of the graph The graph is now locked and will not respond to cursor changes until you release

the lock by choosing (Unlock).

Function List Description

Navigate to a function Double-click a function in the function list.

The cursor focus changes in both the list and graph. The graph is now centered on
the newly selected function.

Highlight a function in the Click the function in the list.

code
The corresponding entity is highlighted in the code.

Highlight a function call in the Click the function call in the list.
code
The section of code is highlighted where the corresponding call is made.

Exclude functions from the

1. In the function list toolbar, choose (Settings).
function list
2. Choose + to add functions to the calls exclude list.
3. Enter all or the first part of the function name (for example, set or get to
remove all setters or getters).
4. Save the list.

Sort the function list alphabet­

1. In the function list toolbar, choose (Settings).
ically (by default, the entities
are displayed in the order of 2. Select the Sort alphabetically checkbox.
their appearance in the code) 3. Apply the changes.

SAP HANA Developer Guide

358 PUBLIC Writing Server-Side JavaScript Code
 Code Preview and Code Navi­ Description
gation

Display a function definition as In the source code, press CTRL and hover over the function call for a couple of sec­
hover text onds.

Note that the code preview only works across files if the files are located within the
same package.

Go to a function definition In the source code, press CTRL + CLICK on the function call.

Note that code navigation only works across files if the files are located within the
same package.

7.2.4 Getting Immediate Feedback

You can use an immediate feedback session to get a better understanding of how your XSJS function works
and performs.

Prerequisites

You have established a web socket debug connection. To do this:

1. Start the SAP HANA studio and open the Administration perspective.
2. On the Configuration tab, add a section called xsengine.ini debugger (if it does not exist) and add (or
set) the following parameter: enabled=true

Context

An immediate feedback session is similar to a debug session. It allows you to evaluate an XSJS function by
stepping through code execution, inspecting variables, and modifying statements. The details of the function
execution are displayed in the Immediate Feedback panel:

● Function Evaluation
The time slider indicates which steps of the function have been executed. The variable list shown just
below the time slider displays the values of the variables in each step.
● Called Function List
If other functions are called by the selected function, they are listed here.
● Database Performance

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 359
 Shows the time that was required to execute any SQL queries contained in the function.
● Query Results
Provides a preview of the data returned by the function, that is, the first few records, so that you can see
what a typical result set looks like.

Procedure

1. In an XSJS JavaScript file, position the cursor inside a JavaScript function declaration on the top level and

choose (Show immediate feedback) in the toolbar.

Note
The function must be an XSJS JavaScript function that is defined as a function declaration, for example,
in the following form:

function x() {…}

Other types of function declarations are not supported. In addition, the function to be investigated must
be on the top level in the XSJS file, that is, it must not be nested.

The Immediate Feedback panel opens on the right and shows how the function is evaluated when it is
called without arguments. The execution step shown on the slider reflects your current cursor position in
the source code.
2. Choose an option.

To... Do the following...

Step through the execution In the Function Evaluation panel, use the time slider to move step execution forward
or backward.

The variable list shows the values of the variables as evaluated in each step. Each
variable newly assigned in a step is marked with an asterisk (*).

Whichever execution step is selected on the slider, the corresponding position is

highlighted in the source code.

Modify the statement with

1. In the Function Evaluation panel, choose (Edit).
which the function is called
2. In the Explore Function dialog box, enter a call statement that will be used to
invoke the function to be evaluated:
○ Select a call statement from the dropdown box.
○ Edit a JavaScript call statement.
3. Choose Evaluate to re-start the evaluation.
The function is called by the new statement and the Immediate Feedback panel
updated accordingly.

Step into called functions 1. In the Called Function List pane, select the checkboxes of the functions that
you want to step into and evaluate in the next immediate feedback run.

2. Start immediate feedback again by choosing (Edit) and then Evaluate.

3. Use the time slider to inspect the newly included steps.

SAP HANA Developer Guide

360 PUBLIC Writing Server-Side JavaScript Code
Related Information

Web-based Performance Tools

7.2.5 Server-Side JavaScript Security Considerations

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) external attacks such as cross-site scripting and forgery, and insufficient
authentication.

The following list illustrates the areas where special attention is required to avoid security-related problems
when writing server-side JavaScript. Each of the problems highlighted in the list is described in detail in its own
dedicated section:

● SSL/HTTPS
Enable secure HTTP (HTTPS) for inbound communication required by an SAP HANA application.
● Injection flaws
In the context of SAP HANA Extended Application Services (SAP HANA XS) injection flaws concern SQL
injection that modifies the URL to expand the scope of the original request.
● Cross-site scripting (XSS)
Web-based vulnerability that involves an attacker injecting JavaScript into a link with the intention of
running the injected code on the target computer.
● Broken authentication and session management
Leaks or flaws in the authentication or session management functions allow attackers to impersonate
users and gain access to unauthorized systems and data.
● Insecure direct object references
An application lacks the proper authentication mechanism for target objects.
● Cross-site request forgery (XSRF)
Exploits the trust boundaries that exist between different Web sites running in the same web browser
session.
● Incorrect security configuration
Attacks against the security configuration in place, for example, authentication mechanisms and
authorization processes.
● Insecure cryptographic storage
Sensitive information such as logon credentials is not securely stored, for example, with encryption tools.
● Missing restrictions on URL Access
Sensitive information such as logon credentials is exposed.
● Insufficient transport layer protection
Network traffic can be monitored, and attackers can steal sensitive information such as logon credentials
or credit-card data.
● Invalid redirects and forwards
Web applications redirect users to other pages or use internal forwards in a similar manner.
● XML processing issues
Potential security issues related to processing XML as input or to generating XML as output

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 361
Related Information

SSL/HTTPS [page 362]

Injection flaws [page 363]
Cross-site scripting (XSS) [page 364]
Broken authentication and session management [page 365]
Insecure direct object references [page 365]
Cross-site request forgery (XSRF) [page 366]
Incorrect security configuration [page 368]
Insecure cryptographic storage [page 368]
Missing restrictions on URL Access [page 369]
Insufficient transport layer protection [page 370]
XML processing issues [page 371]

7.2.5.1 Server-Side JavaScript: SSL/HTTPS

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) external attacks such as cross-site scripting and forgery, and insufficient
authentication. You can set up SAP HANA to use secure HTTP (HTTPS).

SSL/HTTPS Problem

Incoming requests for data from client applications use secure HTTP (HTTPS), but the SAP HANA system is
not configured to accept the HTTPS requests.

SSL/HTTPS Recommendation

Ensure the SAP Web Dispatcher is configured to accept incoming HTTPS requests. For more information, see
the SAP HANA Security Guide.

Note
The HTTPS requests are forwarded internally from the SAP Web Dispatcher to SAP HANA XS as HTTP (clear
text).

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

SAP HANA Developer Guide

362 PUBLIC Writing Server-Side JavaScript Code
7.2.5.2 Server-Side JavaScript: Injection Flaws

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) injection flaws. Typically, injection flaws concern SQL injection and involve modifying
the URL to expand the scope of the original request.

The XS JavaScript API provides a number of different ways to interact with the SAP HANA database by using
SQL commands. By default, these APIs allow you to read data, but they can also be used to update or delete
data, and even to grant (or revoke) access rights at runtime. As a general rule, it is recommended to write a
query which is either a call to an SQLScript procedure or a prepared statement where all parameters specified
in the procedure or statement are escaped by using either setString or setInt, as illustrated in the
examples provided in this section. Avoid using dynamic SQL commands with parameters that are not escaped.

Injection Flaws Problem

In the context of SAP HANA XS, injection flaws mostly concern SQL injection, which can occur in the SAP
HANA XS JavaScript API or SQL script itself (both standard and dynamic). For example, the URL http://
xsengine/customer.xsjs?id=3 runs the code in the JavaScript file customer.xsjs shown below:

var conn = $.db.getConnection();

var pstmt = conn.prepareStatement( " SELECT * FROM accounts WHERE custID='" +
$.request.parameters.get("id"));
var rs = pstmt.executeQuery();

By modifying the URL, for example, to http://xsengine/customer.xsjs?id=3 'OR 1=1', an attacker

can view not just one account but all the accounts in the database.

Note
SAP HANA XS applications rely on the authorization provided by the underlying SAP HANA database.

Users accessing an SAP HANA XS based application require the appropriate privileges on the database objects
to execute database queries. The SAP HANA authorization system will enforce the appropriate authorizations.
This means that in those cases, even if the user can manipulate a query, he will not gain more access than is
assigned to him through roles or privileges. Definer mode SQL script procedures are an exception to this rule
that you need to take into consideration.

Injection Flaws Recommendation

To prevent injection flaws in the JavaScript API, use prepared statements to create a query and place-holders
to fill with results of function calls to the prepared-statement object; to prevent injection flaws in standard SQL
Script, use stored procedures that run in caller mode; in caller mode, the stored procedures are executed with
the credentials of the logged-on HANA user. Avoid using dynamic SQL if possible. For example, to guard against
the SQL-injection attack illustrated in the problem example, you could use the following code:

var conn = $.db.getConnection();

var pstmt = conn.prepareStatement( " SELECT * FROM accounts WHERE custID=?' );

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 363
 pstmt.setInt(1, $.request.parameters.get("id"), 10);
var rs = pstmt.executeQuery();

Prepared statements enable you to create the actual query you want to run and then create several
placeholders for the query parameters. The placeholders are replaced with the proper function calls to the
prepared statement object. The calls are specific for each type in such a way that the SAP HANA XS JavaScript
API is able to properly escape the input data. For example, to escape a string, you can use the setString
function.

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide and the SAP HANA
SQL System Views and Reference.

7.2.5.3 Server-Side JavaScript: Cross-Site Scripting

If you use server-side JavaScript to write your application code, bear in mind the potential for (and risk of)
cross-site scripting (XSS) attacks. Cross-site scripting is a Web-based vulnerability that involves an attacker
injecting JavaScript into a link with the intention of running the injected code on the target computer.

Cross-Site Scripting Problem

The vulnerability to cross-site scripting attacks comes in the following forms:

● Reflected (non-persistent)
Code affects individual users in their local Web browser
● Stored (persistent)
Code is stored on a server and affects all users who visit the served page

A successful cross-site scripting attack could result in a user obtaining elevated privileges or access to
information that should not be exposed.

Cross-Site Scripting Recommendation

Since there are currently no libraries provided by the standard SAP HANA XS JavaScript API to provide proper
escaping, the best solution for generating HTML on SAP HANA XS is to use the ESAPI JavaScript libraries as a
starting point. In addition, we recommend not to write custom interfaces but to rely on well-tested technologies
supplied by SAP, for example, OData or JSON together with SAPUI5 libraries.

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

SAP HANA Developer Guide

364 PUBLIC Writing Server-Side JavaScript Code
7.2.5.4 Server-Side JavaScript: Broken Authentication

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) attack against authentication infrastructure. Leaks or flaws in the authentication or
session management functions allow attackers to impersonate users and gain access to unauthorized systems
and data.

Authentication Problem

Leaks or flaws in the authentication or session management functions allow attackers to impersonate users;
the attackers can be external as well as users with their own accounts to obtain the privileges of those users
they impersonate.

Authentication Recommendation

Use the built-in SAP HANA XS authentication mechanism and session management (cookies). For example,
use the "authentication" keyword to enable an authentication method and set it according to the
authentication method you want implement, for example: SAP logon ticket, form-based, or basic (user name
and password) in the application's .xsaccess file, which ensures that all objects in the application path are
available only to authenticated users.

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

7.2.5.5 Server-Side JavaScript: Insecure Object Reference

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) attacks using insecure references to objects.

Object Reference Problem

An SAP HANA XS application is vulnerable to insecure direct object reference if the application lacks the proper
authentication mechanism for target objects.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 365
Object Reference Recommendation

Make sure that only authenticated users are allowed to access a particular object. In the context of SAP HANA
XS, use the "authentication" keyword to enable an authentication method and set it according to the
authentication method you implement, for example: SAP logon ticket, form-based, or basic (user name and
password) in the application's .xsaccess file, which ensures that all objects in the application path are
available only to authenticated users.

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

7.2.5.6 Server-Side JavaScript: Cross-Site Request Forgery

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) cross-site request forgery (XSRF). Cross-site scripting is a web-based vulnerability
that exploits the trust boundaries that exist between different websites running in the same web browser
session.

Cross-Site Request-Forgery Problem

Since there are no clear trust boundaries between different Web sites running in the same Web-browser
session, an attacker can trick users (for example, by luring them to a popular Web site that is under the
attacker's control) into clicking a specific hyperlink. The hyperlink displays a Web site that performs actions on
the visitor's behalf, for example, in a hidden iframe. If the targeted end user is logged in and browsing using an
account with elevated privileges, the XSRF attack can compromise the entire Web application.

Cross-Site Request-Forgery Recommendation

SAP HANA XS provides a way to include a random token in the POST submission which is validated on the
server-side. Only if this token is non-predictable for attackers can one prevent cross-site, request-forgery
attacks. The easiest way to prevent cross-site, request-forgery attacks is by using the standard SAP HANA XS
cookie. This cookie is randomly and securely generated and provides a good random token which is
unpredictable by an attacker ($.session.getSecurityToken()).

To protect SAP HANA XS applications from cross-site request-forgery (XSRF) attacks, make sure you always
set the prevent_xsrf keyword in the application-acess (.xsaccess) file to true, as illustrated in the following
example:

{
"prevent_xsrf" : true
}

SAP HANA Developer Guide

366 PUBLIC Writing Server-Side JavaScript Code
The prevent_xsrf keyword prevents the XSRF attacks by ensuring that checks are performed to establish that a
valid security token is available for given Browser session. The existence of a valid security token determines if
an application responds to the client's request to display content. A security token is considered to be valid if it
matches the token that SAP HANA XS generates in the backend for the corresponding session.

Note
The default setting is false, which means there is no automatic prevention of XSRF attacks. If no value is
assigned to the prevent_xsrf keyword, the default setting (false) applies.

The following client-side JavaScript code snippet show how to use the HTTP request header to fetch, check,
and apply the XSRF security token required to protect against XSRF attacks.

<html>
<head>
<title>Example</title>
<script id="sap-ui-bootstrap" type="text/javascript"
src="/sap/ui5/1/resources/sap-ui-core.js"
data-sap-ui-language="en"
data-sap-ui-theme="sap_goldreflection"
data-sap-ui-libs="sap.ui.core,sap.ui.commons,sap.ui.ux3,sap.ui.table">
</script>
<script type="text/javascript" src="/sap/ui5/1/resources/jquery-sap.js"></
script>
<script>
function doSomething() {
$.ajax({
url: "logic.xsjs",
type: "GET",
beforeSend: function(xhr) {
xhr.setRequestHeader("X-CSRF-Token", "Fetch");
},
success: function(data, textStatus, XMLHttpRequest) {
var token = XMLHttpRequest.getResponseHeader('X-CSRF-Token');
var data = "somePayLoad";
$.ajax({
url: "logic.xsjs",
type: "POST",
data: data,
beforeSend: function(xhr) {
xhr.setRequestHeader("X-CSRF-Token", token);
},
success: function() {
alert("works");
},
error: function() {
alert("works not");
}
});
}
});
}
</script>
</head>
<body>
<div>
<a href="#" onClick="doSomething();">Do something</a>
</div>
</body>
</html>

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 367
 Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

7.2.5.7 Server-Side JavaScript: Security Misconfiguration

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) attacks against the security configuration in place, for example, authentication
mechanisms and authorization processes.

Insecure Configuration Problem

No or an inadequate authentication mechanism has been implemented.

Insecure Configuration Recommendation

Applications should have proper authentication in place, for example, by using SAP HANA built-in
authentication mechanisms and, in addition, the SAP HANA XS cookie and session handling features.
Application developers must also consider and control which paths are exposed by HTTP to the outside world
and which of these paths require authentication.

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

7.2.5.8 Server-Side JavaScript: Insecure Storage

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) attacks against the insecure or lack of encryption of data assets.

Storage-Encryption Problem

Sensitive information such as logon credentials is exposed.

SAP HANA Developer Guide

368 PUBLIC Writing Server-Side JavaScript Code
Storage-Encryption Recommendation

To prevent unauthorized access, for example, in the event of a system break-in, data such as user logon
credentials must be stored in an encrypted state.

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

7.2.5.9 Server-Side JavaScript: Missing URL Restrictions

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) unauthorized access to URLs.

URL Access Problem

Unauthenticated users have access to URLs that expose confidential (unauthorized) data.

URL Access Recommendation

Make sure you have addressed the issues described in "Broken Authentication and Session Management" and
"Insecure Direct Object References". In addition, check if a user is allowed to access a specific URL before
actually executing the code behind that requested URL. Consider putting an authentication check in place for
each JavaScript file before continuing to send any data back to the client's Web browser.

Tip
For more information about Security in SAP HANA, see the SAP HANA Security Guide.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 369
7.2.5.10 Server-Side JavaScript: Transport Layer Protection

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) insufficient protection of the transport layer.

Transport Layer Protection Problem

Without transport-layer protection, the user's network traffic can be monitored, and attackers can steal
sensitive information such as logon credentials or credit-card data.

Transport Layer Protection Recommendation

Turn on transport-layer protection in SAP HANA XS; the procedure is described in the SAP HANA security
guide.

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

7.2.5.11 Server-Side JavaScript: Invalid Redirection

If you use server-side JavaScript to write your application code, bear in mind the potential for (and risk of)
redirection and internal fowarding from the requested Web page.

Invalid Redirection Problem

Web applications frequently redirect users to other pages or use internal forwards in a similar manner.
Sometimes the target page is specified in an invalid (not permitted) parameter. This enables an attacker to
choose a destination page leading to the possibility of phishing attacks or the spamming of search engines.

Invalid Redirection Recommendation

To prevent invalidated redirects or forwards, application developers should validate the requested destination
before forwarding, for example, by checking if the destination is present in a white list. If the destination URL
specified in the redirection request is not present in the white list, the redirection is refused.

SAP HANA Developer Guide

370 PUBLIC Writing Server-Side JavaScript Code
 Tip
Avoid using redirection if you cannot control the final destination.

Alternatively, you can refuse to allow any direct user input; instead, the input can be used to determine the final
destination for the redirection, as illustrated in the following example:

var destination = $.request.parameters.get("dest");

switch (destination) {
case "1": $.response.headers.set("location", "http://
FirstWhitelistedURL.com"); break;
case "2": $.response.headers.set("location", "http://
SecondWhitelistedURL.com"); break;
default: $.response.headers.set("location", "http://
DefaultWhitelistedURL.com");
}

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

7.2.5.12 Server-Side JavaScript: XML Processing Issues

If you choose to use server-side JavaScript to write your application code, you need to bear in mind the
potential for (and risk of) attacks aimed at the process used to parse XML input and generate the XML output.

XML Processing Problem

There are several potential security issues related to processing XML as input or to generating XML as output.
In addition, problems with related technologies (for example, XSL Transformations or XSLT) can enable the
inclusion of other (unwanted) files.

XML Processing Recommendation

Turn on transport-layer protection in SAP HANA XS; the procedure is described in the SAP HANA security
guide.

Bear in mind the following rules and suggestions when processing or generating XML output:

● When processing XML that originates from an untrusted source, disable DTD processing and entity
expansion unless strictly required. This helps prevent Billion Laugh Attacks (Cross-Site Request Forgery),
which can bring down the processing code and, depending on the configuration of the machine, an entire
server.
● To prevent the inclusion (insertion) of unwanted and unauthorized files, restrict the ability to open files or
URLs even in requests included in XML input that comes from a trusted source. In this way, you prevent the
disclosure of internal file paths and internal machines.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 371
● Ensure proper limits are in place on the maximum amount of memory that the XML processing engine can
use, the amount of nested entities that the XML code can have, and the maximum length of entity names,
attribute names, and so on. This practice helps prevent the triggering of potential issues.

Tip
For more information about security in SAP HANA, see the SAP HANA Security Guide.

7.3 Using Server-Side JavaScript Libraries

The elements defined in normal server-side JavaScript programs cannot be accessed from other JavaScript
programs. To enable the reuse of program elements, SAP HANA Extended Application Services support server-
side JavaScript libraries.

Server-side JavaScript libraries are a special type of JavaScript program that can be imported and called in
other JavaScript programs. You can use JavaScript libraries to perform simple, repetitive tasks, for example, to
handle forms and form date, to manipulate date and time strings, to parse URLs, and so on.

Note
JavaScript libraries are internally developed extensions for SAP HANA.

The following example shows how to import a JavaScript mathematics library using the import function:

// import math lib

$.import("sap.myapp.lib","math");
// use math lib
var max_res = $.sap.myapp.lib.math.max(3, 7);

The import function requires the following parameters:

● Package name
Full name of the package containing the library object you want to import, for example, sap.myapp.lib
● Library name
Name of the library object you want to import, for example, math

Note
Restrictions apply to the characters you can use in the names of JavaScript libraries and application
packages. Permitted characters are: upper- and lower-case letters (Aa-Zz), digits 0-9, and the dollar sign
($).

The standard JavaScript limitations apply to the characters you can use in either the name of the XSJS library
you create or the name of the package where the library is deployed. For example, you cannot use the hyphen
(-) in the name of an XSJS library or, if you are referencing the library, the name of a package in the application
package path. To prevent problems with activation of the object in the SAP HANA repository, you must follow
the standard rules for accessing JavaScript property objects by name. The following example, shows how to

SAP HANA Developer Guide

372 PUBLIC Writing Server-Side JavaScript Code
use square brackets and quotes (["<STRING>"]) to access an object whose name uses non-permitted
characters such as a hyphen (-):

// import math lib

$.import("sap.myapp.lib.XS-QGP-SPS7","math");
// use math lib
var max_res = $.sap.myapp.lib["XS-QGP-SPS7"].math.max(3, 7);

Related Information

Import Server-Side JavaScript Libraries [page 373]

7.3.1 Import Server-Side JavaScript Libraries

Server-side JavaScript libraries are a special type of JavaScript program that can be imported and called in
other JavaScript programs. You can use JavaScript libraries to perform simple, repetitive tasks, for example:
handle forms and form date, manipulate date and time strings, parse URLs, and so on.

Context

JavaScript libraries are internally developed extensions for SAP HANA. The libraries exist in the context of a
package, which is referenced when you import the library. The following example of a JavaScript library
displays the word "Hello" along with a name and an exclamation mark as a suffix.

var greetingPrefix = "Hello, ";

var greetingSuffix = "!";
function greet (name) {
return greetingPrefix + name + greetingSuffix;
}

Note
This procedure uses the illustrated example JavaScript library to explain what happens when you import a
JavaScript library, for example, which objects are created, when, and where. If you have your own library to
import, substitute the library names and paths shown in the steps below as required.

To import a JavaScript library for use in your server-side JavaScript application, perform the following tasks

Procedure

1. Import the JavaScript library into a JavaScript application.

Open the server-side JavaScript file into which you want to import the JavaScript library.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 373
 Use the $.import function, as follows:

$.import("<path.to.your.library.filename>","greetLib");
var greeting = $.<path.to.your.library.filename>.greet("World");
$.response.setBody(greeting);

2. Save and activate the changes to the JavaScript file.

Although the operation is simple, bear in mind the following points:
○ Additional objects in the package hierarchy
The import operation generates a hierarchy of objects below $ that resemble the library's location in
the repository, for example, for the library path/to/your/library/greetLib.xsjslib, you would
see the following additional object:

$.path.to.your.library.greetLib

○ Additional properties for the newly generated library object:

$.path.to.your.library.greetLib.greet()
$.path.to.your.library.greetLib.greetingSuffix
$.path.to.your.library.greetLib.greetingPrefix

○ Pre-import checks:
○ It is not possible to import the referenced library if the import operation would override any
predefined runtime objects.
○ Do not import the referenced library if it is already present in the package.
○ Library context
Imported libraries exist in the context defined by their repository location.

7.3.2 Write Server-Side JavaScript Libraries

Server-side JavaScript libraries are a special type of JavaScript program that can be imported and called in
other JavaScript programs. You can use JavaScript libraries to perform simple, repetitive tasks, for example, to
handle forms and form date, to manipulate date and time strings, to parse URLs, and so on.

Context

JavaScript libraries are internally developed extensions for SAP HANA. However, you can write your own
libraries, too. JavaScript libraries exist in the context of a package, which is referenced when you import the
library. To write a JavaScript library to use in your server-side JavaScript application, perform the following
steps:

Procedure

1. Create the file that contains the JavaScript library you want to add to the package and make available for
import.

SAP HANA Developer Guide

374 PUBLIC Writing Server-Side JavaScript Code
 In SAP HANA XS, server-side JavaScript libraries have the file extension .xsjslib, for example
greetLib.xsjslib.
a. Select the package where you want to create the new JavaScript library file and from the context menu
choose New File .
b. Enter a file name, for example, greetLib.xsjslib, and choose Create.
c. Enter the following content in the greetLib.xsjslib file.
This example creates a simple library that displays the word “Hello” along with a supplied name and
adds an exclamation point (!) as a suffix.

var greetingPrefix = "Hello, ";

var greetingSuffix = "!";
function greet (name) {
return greetingPrefix + name + greetingSuffix;
}

2. Save the new JavaScript library.

Now that it has been saved and activated in the repository it is available for import by other JavaScript
applications. It is important to remember where the JavaScript library is located; you have to reference the
package path when you import the library.

7.4 Using the Server-Side JavaScript APIs

SAP HANA Extended Application Services (SAP HANA XS) provides a set of server-side JavaScript application
programming interfaces (API) that enable you to configure your applications to interact with SAP HANA.

The SAP HANA XS JavaScript Reference lists all the functions that are available for use when programing
interaction between your application and SAP HANA. For example, you can use the database API to invoke SQL
statements from inside your application, or access details of the current HTTP request for SAP HANA data with
the request-processing API.SAP HANA XS includes the following set of server-side JavaScript APIs:

XS JavaScript Application Programming Interfaces

API Description

Database Enables access to the SAP HANA by means of SQL statements. For example, you can open a
connection to commit or rollback changes in SAP HANA, to prepare stored procedures (or SQL
statements) for execution or to return details of a result set or a result set's metadata.

Outbound connectivity Enables outbound access to a defined HTTP destination that provides services which an appli­
cation can use. For example, you can read the connection details for an HTTP destination, re­
quest data, and set details of the response body. You can also set up an SMTP connection for
use by outgoing multipart e-mails.

Request processing Enables access to the context of the current HTTP request, for example, for read requests and
write responses. You can use the functions provided by this API to manipulate the content of the
request and the response.

Session Enables access to the SAP HANA XS session, for example, to determine the language used in
the session or if a user has the privileges required to run an application.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 375
API Description

Job Schedule Enables access to the job-scheduling interface which allows you to define and trigger recurring
tasks that run in the background. The XS jobs API allows you to add and remove schedules from
jobs.

Security Enables access to the $.security.crypto namespace and the classes AntiVirus and
Store, which provide tools that allow you to configure a secure store, set up anti-virus scans,
and generate hashes..

Trace Enables access to the various trace levels you can use to generate and log information about ap­
plication activity. You can view trace files in the diagnosis Files tab of the SAP HANA studio's
Administration perspective.

Utilities Enables access to utilities that you can use to parse XML and manipulate Zip archives, for exam­
ple, to zip and unzip files, add and remove entries from Zip archives, and encrypt Zip archives
with password protection.

XS Data Services Provides access to a library of JavaScript utilities, which can be used to enable server-side Java­
Script applications to consume data models that are defined using Core Data Services.

XS Procedures Provides access to a library of JavaScript utilities, which can be used to enable server-side Java­
Script applications to call SAP HANA stored procedures as if the procedures were JavaScript
functions.

Restriction
XSProc is intended only for use with database connections made with the old $.db API. It
is not recommended to use XSProc with $.hdb connections. For $.hdb connections, use
$hdb.loadProcedure instead.

Database API

The SAP HANA XS Database API ($.hdb) provides tools that enable simple and convenient access to the
database.

Caution
The $.hdb namespace is intended as a replacement for the older $.db namespace. Since different
database connections are used for the $.hdb and $.db APIs, avoid using both APIs in a single http-request,
for example, to update the same tables as this can lead to problems, including deadlocks.

You can use the Database API for the following operations

● $.hdb.Connection
Estalish a connection to the SAP HANA database
● $.hdb.ProcedureResult
Represents the result of a stored procedure call to the SAP HANA database
● $.hdb.ResultSet
Represents the result of a database query

The following example shows how to use the database API to connect to the SAP HANA database, commit
some changes, and end the current transaction.

SAP HANA Developer Guide

376 PUBLIC Writing Server-Side JavaScript Code
 Note
By default, auto-commit mode is disabled, which means that all database changes must be explicitly
commited.

var connection = $.hdb.getConnection();

connection.executeUpdate('UPDATE "DB_EXAMPLE"."ICECREAM" SET QUANTITY=? WHERE
FLAVOR=?', 9, 'CHOCOLATE');
connection.commit();

The following example of usage of the SAP HANA XS database API shows how to establish a connection with
SAP HANA and return a result set from the specified procedure call. The example code assumes that a
procedure exists with the following signature:

PROCEDURE 'DB_EXAMPLE'.icecream.shop::sell(
IN flavor VARCHAR,
IN quantity INTEGER,
IN payment DECIMAL,
OUT change DECIMAL)

Note that the result can be accessed as if it were a JSON object with a structure similar to the following
example: {change: 1.50, $resultSets:[....]} .

Tip
$resultSets is not enumerable; it does not show up in a for-each loop.

var fnSell = connection.loadProcedure('DB_EXAMPLE', 'icecream.shop::sell');

var result = fnSell('CHOCOLATE', 3, 30.0);
// value of output parameter 'change'
var change = result['change'];
// array of $.hdb.ResultSet returned by the stored procedure
var resultSets = result['$resultSets'];
// iterate over all output parameters.
var params;
for (var outputParam in result) {
params += outputParam + ' ';
}

Outbound API

The Outbound API ($.net) provides tools that you can use to perform the following actions:

● $.net.SMTPConnection
For sending $.net.Mail objects by means of an SMTP connection
● $.net.Mail
For constructing and sending multipart e-mails
● $.net.http
HTTP(s) client (and request) classes for outbound connectivity and an HTTP(s) destination class that hold
metadata, for example: host, port, useSSL.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 377
The following example shows how to use the $.net.SMTPConnection class to send e-mail objects
($.net.Mail) by means of an SMTP connection object:

subscribers = ["[email protected]", "[email protected]"];

smtpConnection = new SMTPConnection();
var mail = new $.net.Mail({ sender: "[email protected]",
subject: "Promotion Notice",
subjectEncoding: "UTF-8",
parts: [new $.net.Mail.Part({
type: $.net.Mail.Part.TYPE_TEXT,
contentType: "text/html",
encoding: "UTF-8"
})]
});
for (var i = 0; i < subscribers.length; ++i) {
mail.to = subscribers[i];
mail.parts[0].text = "Dear " + subscribers[i].split("@")[0] + ", \
you have been promoted. Congratulations!";
smtpConnection.send(mail);
}
smtpConnection.close();

The following example shows how to use the $.net.Mail class to create an e-mail from an XS JavaScript
object and send it to the named recipients:

Note
If mandatory information is missing or an error occurs during the send operation, the mail.send() call
fails and returns an error.

var mail = new $.net.Mail({

sender: {address: "[email protected]"},
to: [{ name: "John Doe", address: "[email protected]", nameEncoding: "US-
ASCII"}, \
{name: "Jane Doe", address: "[email protected]"}],
cc: ["[email protected]", {address: "[email protected]"}],
bcc: [{ name: "Jonnie Doe", address: "[email protected]"}],
subject: "subject",
subjectEncoding: "UTF-8",
parts: [ new $.net.Mail.Part({
type: $.net.Mail.Part.TYPE_TEXT,
text: "The body of the mail.",
contentType: "text/plain",
encoding: "UTF-8",
})]
});
var returnValue = mail.send();
var response = "MessageId = " + returnValue.messageId + ", final reply = " +
returnValue.finalReply;
$.response.status = $.net.http.OK;
$.response.contentType = "text/html";
$.response.setBody(response);

The following example of server-side JavaScript shows how to use the outbound API to get (read) an HTTP
destination. You can also set the contents of the response, for example, to include details of the header, body,
and any cookies. For HTTPs connections you need to maintain a certificate (CA or explicit server certificate) in
a Trust Store; you use the certificate to check the connection against.

var dest = $.net.http.readDestination("inject", "ipsec");

var client = new $.net.http.Client();
var req = new $.web.WebRequest($.net.http.GET, "");
client.request(req, dest);

SAP HANA Developer Guide

378 PUBLIC Writing Server-Side JavaScript Code
 var response = client.getResponse();
var co = [], he = [];
for(var c in response.cookies) {
co.push(response.cookies[c]);
}
for(var c in response.headers) {
he.push(response.headers[c]);
}
var body = undefined;
if(response.body)
var body = response.body.asString();
$.response.contentType = "application/json";

Tip
You define the HTTP destination in a text file using keyword=value pairs. You must activate the HTTP
destination in the SAP HANA repository. After activation, you can view details of the HTTP destination in the
SAP HANA XS Administration tool.

Request-Processing API

The Request-Processing API ($.web) provides access to the body of HTTP request and response entities. For
example, you can use the following classes:

● $.web.Body
Represents the body of an HTTP request entity and provides access to the data included in the body of the
HTTP request entity
● $.web.EntityList
Represents a list of request or response entities; the EntityList holds WebEntityRequest or
WebEntityResponse objects.
● $.web.TupelList
Represents a list of name-value pairs. The TupelList is a container that provides tuples for cookies,
headers, and parameters. A “tuple” is a JavaScript object with the properties “name” and “value”.
● $.web.WebRequest
Enables access to the client HTTP request currently being processed
● $.web.WebResponse
Enables access to the client HTTP response currently being processed for the corresponding request
object (
● $.web.WebEntityRequest
Represents an HTTP request entity and provides access to the entity's metadata and (body) content.
● $.web.WebEntityResponse
Represents the HTTP response currently being populated

The following example shows how to use the request-processing API to display the message “Hello World” in a
browser.

$.response.contentType = "text/plain";
$.response.setBody( "Hello, World !");

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 379
In the following example, you can see how to use the request-processing API to get the value of parameters
describing the name and vendor ID of a delivery unit (DU) and return the result set in JSON-compliant form.

var duName = $.request.parameters.get("du_name");

var duVendor = $.request.parameters.get("du_vendor");
result = {
content_id : contentId.toString()
};
$.response.status = $.net.http.OK;
$.response.contentType = 'application/json';
$.response.setBody(JSON.stringify(result));

In the following example of use of the request-processing API, we show how to access to the request's meta
data (and body) and, in addition, how to set and send the response.

if($.request.method === $.net.http.GET) {

// get query parameter named id
var qpId = $.request.parameters.get("id");

// handle request for the given id parameter...

var result = handleRequest(qpId);

// send response
$.response.contentType = "plain/test";
$.response.setBody("result: " + result);
$.response.status = $.net.http.OK;
} else {
// unsupported method
$.response.status = $.net.http.INTERNAL_SERVER_ERROR;
}

Session API

Enables access to the SAP HANA XS session, for example, to determine the language used in the session or
check if a user has the privileges required to run an application.

You can use the XS JavaScript $.session API to request and check information about the currently open
sessions. For example, you can find out the name of a user who is currently logged on to the database or get
the session-specific security token. The $.session API also enables you to check if a user has sufficient
privileges to call an application. The following example checks if the user has the execute privilege that is
required to run an application. If the check reveals that the user does not have the required privilege, an error
message is generated indicating the name of the missing privilege.

if (!$.session.hasAppPrivilege("sap.xse.test::Execute")) {
$.response.setBody("Privilege sap.xse.test::Execute is missing");
$.response.status = $.net.http.INTERNAL_SERVER_ERROR;
}

SAP HANA Developer Guide

380 PUBLIC Writing Server-Side JavaScript Code
Job Schedule API

In SAP HANA XS, a scheduled job is created by means of an .xsjob file, a design-time file you commit to (and
activate in) the SAP HANA repository. The .xsjob file can be used to define recurring tasks that run in the
background; the Job Schedule API allows developers to add and remove schedules from such jobs.

The Job Schedule API provides the following tools:

● Job
$.jobs.Job represents a scheduled XS job
● JobLog
$.jobs.JobLog provide access to the log entries of a scheduled job
● JobSchedules
$.jobs.JobSchedules enables control of an XS job's schedules.

Note
It is not possible to call the $.request and $.response objects as part of an XS job.

The XS jobs API $.jobs.Job enables you to add schedules to (and remove schedules from) jobs defined in
an .xsjob file.

The following example of server-side JavaScript shows how to use the Job Schedule API to add a schedule to a
existing job and delete a schedule from an existing job.

var myjob = new $.jobs.Job({uri:"myJob.xsjob", sqlcc:"sqlcc/otheruser.xssqlcc"});

// add schedule to a job
var id = myjob.schedules.add({
description: "Added at runtime, run every 10 minutes",
xscron: "* * * * * */10 0",
parameter: {
a: "c"
}
});
// delete a schedule from a job
myjob.schedules.delete({id: id});

If the XS job file referred to in the URI is not in the same package as the XS JavaScript or SQLScript function
being called, you must add the full package path to the XS job file specified in the URI illustrated in line 1 of the
example above, for example, </path/to/package.>MyXSjob.xsjob.

Note
The path specified in </path/to/package.> can be either absolute or relative.

In addition, the SQL connection defined in sqlcc/otheruser.xssqlcc is used to modify the job; it is not
used to execute the job specified in myJob.xsjob.

To understand the cron-like syntax required by the xscron job scheduler, use the following examples:

● 2013 * * fri 12 0 0
Run the job every Friday in 2013 at 12:00.

● * * 3:-2 * 12:14 0 0

Run every hour between 12:00 and 14:00 every day between the third and second-to-last day of the month.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 381
● * * * -1.sun 9 0 0
Run the job on the last Sunday of every month at 09:00.

Security API

The SAP HANA XS JavaScript security API $.security includes the $.security.crypto namespace and
the following classes:

● $.security.AntiVirus
Scan data with a supported external anti-virus engine
● $.security.Store
Store data securely in name-value form

The $.security.crypto namespace includes methods (for example, md5(), sha1(), and sha256()) that
enable you to compute an MD5 or SHA1/256 hash (or HMAC-MD5, HMAC-SHA1, and HMAC-SHA256).

The AntiVirus class includes a method scan() that enables you to set up a scan instance using one of the
supported anti-virus engines. The Store class enables you to set up a secure store for an SAP HANA XS
application; the secure store can be used to store sensitive information either at the application level
(store()) or per user (storeForUser()).

The following code example shows how to use the SAP HANA XS virus-scan interface (VSI) to scan a specific
object type: a Microsoft Word document.

Note
For more information about which antivirus engines SAP HANA supports, see SAP Note 786179.

var data = //Some data to be checked

var av = new $.security.AntiVirus();
//AV scan data as Word document
av.scan(data, "myDocument.docx");

The following code example shows how to set up a simple scan for data uploads using the SAP HANA XS virus-
scan interface.

//scan a buffer with own "upload" profile

var av = new $.security.AntiVirus("upload");
av.scan(buffer);

The SAP HANA XS $.security.Store API can be used to store data safely and securely in name-value form.
The security API enables you to define a secure store (in a design-time artifact) for each application and refer
to this design time object in the application coding.

Note
The design-time secure store is a file with the file extension “.xssecurestore”, for example,
localStore.xssecurestore; the secure-store file must include only the following mandatory content:
{}.

SAP HANA Developer Guide

382 PUBLIC Writing Server-Side JavaScript Code
SAP HANA XS looks after the encryption and decryption of data and also ensures the persistency of the data.
For the stored data, you can choose between the following visibility options:

● Application-wide data visibility

Use store(<parameters>) to ensure that all users of the corresponding application have access to one
secure store where they can share the same data and can decrypt or encrypt data, for example, passwords
for a remote system.
● Application-wide data visibility but with user-specific stores separation
Use storeForUser(<parameters>) to ensures that each user of the corresponding application has a
separate container to securely store personal, encrypted data, for example, credit card numbers or
personal-information-number (PIN) codes; the encrypted data can only be decrypted by the owner of the
secure store; the user who encrypted it.

function store() {
var config = {
name: “foo”,
value: “bar”
};
var aStore = new $.security.Store("localStore.xssecurestore");
aStore.store(config);
}
function read() {
var config = {
name: “foo”
};
try {
var store = new $.security.Store("localStore.xssecurestore");
var value = store.read(config);
}
catch(ex) {
//do some error handling
}
}

Trace API

Enables access to the various trace levels you can use to generate and log information about application
activity. The specified error message is written to the appropriate trace file.

$.trace.error("This is an error message")

You can set the following trace levels:

● $.trace.debug(message)
Writes the string defined in (message) to the application trace with debug level
● $.trace.error(message)
Writes the string defined in (message) to the application trace with error level
● $.trace.fatal(message)
Writes the string defined in (message) to the application trace with fatal level
● $.trace.info(message)
Writes the string defined in (message) to the application trace with info level
● $.trace.warning(message)
Writes the string defined in (message) to the application trace with warning level

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 383
 Note
If tracing is enable, messages generated by the $.trace API are logged in the SAP HANA trace file
xsengine_<host>_<Instance>_<#>.trc on the SAP HANA server, for example, in
<installation_path>/<SID>/HDB<nn>/<hostname>/trace. Trace messages with severity status
“warning”, “error” and “fatal” are also written to a similarly named alert file, for example,
xsengine_alert_<host>.trc.

Utilities API

The SAP HANA XS JavaScript Utilities API includes the $.util namespace, which contains the following
classes

● $.util.SAXParser
Tools for parsing XML content (for example, strings, array buffers, and the content of Web response body
objects)
● $.util.Zip
Compression tools for building, modifying, extracting, and encrypting archives

With the XS JavaScript Utilities API$.util.SAXParser class, you can create a new parser object and parse
the XML content of an XMLstring, an XML array buffer, or a $.web.Body object. The following example shows
how to use the XML parsing capabiliites of the $.util.SAXParser class:

Note
You can stop, reset, and resume a parsing operation. If the content to be parsed does not contain XML, the
parser throws an error.

var parser = new $.util.SAXParser();

var xml = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n\
<!-- this is a note -->\n\
<note noteName='NoteName'>\n\
<to>To</to>\n\
<from>From</from>\n\
<heading>Note heading</heading>\n\
<body>Note body</body>\n\
<note>\n";
var startElementHandlerConcat = "";
var endElementHandlerConcat = "";
var characterDataHandlerConcat = "";
parser.startElementHandler = function(name, atts) {
startElementHandlerConcat += name;
if (name === "note") {
startElementHandlerConcat += " noteName = '" + atts.noteName + "'";
}
startElementHandlerConcat += "\n";
};
parser.endElementHandler = function(name) {
endElementHandlerConcat += name + "\n";
};
parser.characterDataHandler = function(s) {
characterDataHandlerConcat += s;
};
parser.parse(xml);

SAP HANA Developer Guide

384 PUBLIC Writing Server-Side JavaScript Code
 ...

The following code snippet shows how to use the $.util.SAXParser tools to parse the content of a
$.web.Body object.

var body = $.request.body

var parser = new $.util.SAXParser()
//... set handlers
parser.parse(body);

The following encodings are supported:

● UTF-8 (default)
● UTF-16
● US-ASCII

The SAP HANA XS JavaScript Utilities API also includes the$.util.Zip tool, which enables you to perform a
series of actions on Zip archives, for example:

● Compress files into (zip) and extract files from (unzip) a Zip archive
● Add new entries to, update existing entries in, and remove entries from a Zip archive
● Encrypt Zip archives with password protection

The following code illustrates a simple usage of the Zip tool:

var zip = new $.util.Zip("myPassword");

zip["entry.txt"] = "Two fish are in a tank. One turns to the other and asks 'How
do you drive this thing?'";
$.response.status = $.net.http.OK;
$.response.contentType = "application/zip";
$.response.headers.set("Content-Disposition", "attachment; filename =
Encrypted.zip");
$.response.setBody(zip.asArrayBuffer());

The following code snippets show how to use the $.util.Zip tools to work with Zip file content, for example,
by adding, updating, extracting, and deleting entries. When modeling folder hierarchies, the Zip object behaves
like an associative array; the entry names are the keys (the full paths to the indicated files). In the following
example, we add an entry to a Zip file:

Note
“zip["entry1"]” is equivalent to “zip.entry1”.

var zip = new $.util.Zip();

zip["entry1"] = "old entry";

In the following example, we update an entry in a Zip file:

var zip = new $.util.Zip();

zip["entry1"] = "new entry";

In the following example, we extract an entry from a Zip file: if the entry does not exist, this returns undefined.

var zip = new $.util.Zip();

var content = zip["entry1"];

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 385
In the following example, we delete an entry from a Zip file: if the entry does not exist, nothing happens.

var zip = new $.util.Zip();

delete zip["entry1"];

Note
There is a restriction on the amount of uncompressed data that can be extracted from a Zip archive using
the XS JS utilities API.

When using the XS JS utilities API to extract data from a Zip archive, the maximum amount of uncompressed
data allowed during the extraction process is defined with the parameter
max_uncompressed_size_in_bytes, which you can set in the zip section of the xsengine.ini
configuration file for a given SAP HANA system. If the zip section does not already exist, you must create it
and add the parameter to it, for example, using the SAP HANA Administration Console in SAP HANA studio. If
the parameter max_uncompressed_size_in_bytes is not set, a default value is assumed. The default value
is the value assigned to the property max_runtime_bytes in section jsvm section of the xsengine.ini file.

You can deactivate the global check on the amount of uncompressed data. If the global system
parametermax_uncompressed_size_in_bytes is set to -1, no check is performed on the amount of
uncompressed data generated by an extraction process using the Utilities API, unless there is a specific user
limitation in the XS JavaScript code, for example, with the maxUncompressedSizeInBytes parameter.

With the $.util.Zip class or the $.util.compression namespace, you can use the property
maxUncompressedSizeInBytes to override the global setting and reduce the amount of uncompressed data
allowed.

Note
Note that the parameter max_uncompressed_size_in_bytes cannot be used to increase the amount of
uncompressed data allowed beyond the value specified in the global setting.

XS Data Services API

SAP HANA XS Data Services (XSDS) is a collection of tools that includes a native client for Core Data Services
(CDS) and a query builder for SAP HANA Extended Application Services (SAP HANA XS) JavaScript. The XSDS
API provides a high-level abstraction of the database API ($.db, $.hdb) and gives access to SAP HANA
artifacts such as CDS entities or stored procedures. XSDS enables server-side JavaScript applications to
consume data models that are defined using Core Data Services more efficiently.

The following example shows how to import a CDS entity and how to update a given entity instance in XSDS
managed mode.

// import CDS client library

var XSDS = $.import("sap.hana.xs.libs.dbutils", "xsds");
// import CDS entity
var MyEntity = XSDS.$importEntity("cds.namespace", "cds_context.cds_entity");
// retrieve entity instance
var instance = MyEntity.$get({ id: 69 });
// update instance
instance.stringProp = "new value";

SAP HANA Developer Guide

386 PUBLIC Writing Server-Side JavaScript Code
 instance.intProp++;
instance.assocProp.dateProp = new Date();
// persist changes
instance.$save();

The following example shows how to query the database using CDS model data in XSDS unmanaged mode.

// import CDS client library

var XSDS = $.import("sap.hana.xs.libs.dbutils", "xsds");
// import CDS entity
var MyEntity = XSDS.$importEntity("cds.namespace", "cds_context.cds_entity");
// build query
var query = MyEntity.$query();
var projection = query.$project({
stringProp: true,
aliasProp: "aliasName",
assocProp: { dateProp: true }
});
var filter = query.$where({ stringProp: { $like: "A%" } });
// retrieve result
var result = projection.$execute();
// process result
for (var i = 0; i < result.length; i++) {
var diff = result[i].assocProp.dateProp – Date.now();
// ...
}

XS Procedures API

SAP HANA XS Procedures is a library of JavaScript tools which enable you to call SAP HANA stored procedures
from server-side JavaScript (XS JS) as if the stored procedures were native JavaScript functions.

Restriction
XSProc is intended only for use with database connections made with the old $.db API. It is not
recommended to use XSProc with $.hdb connections. For $.hdb connections, use $hdb.loadProcedure
instead.

The following example shows how to consume a stored procedure using the XS Procedures API.

// import XS Procedures library

var XSProc = $.import("sap.hana.xs.libs.dbutils", "procedures");
// set a schema where temporary tables can be created for passing table-valued
parameters to the procedure
XSProc.setTempSchema($.session.getUsername().toUpperCase());
// load the procedure
var proc = XSProc.procedure("schema", "namespace", "procedureName”);
// call the procedure
var result = proc(1, [{col1: 0, col2:1}, {col1: 1, col2:2}]);
// result is a JavaScript object

Related Information

SAP HANA XS JavaScript API Reference

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 387
Maintaining HTTP Destinations [page 80]
XS Job File Keyword Options [page 417]
SAP Note 786179

7.4.1 Tutorial: Use the XSJS Outbound API

The application package you create in this tutorial includes all the artifacts you need to enable your server-side
JavaScript application to use the Outbound Connectivity API to request and obtain data via HTTP from a
service running on a remote host.

Prerequisites

● You have the privileges granted by the role sap.hana.ide.roles::EditorDeveloper; this role is included in the
parent role sap.hana.ide.roles::Developer.
● You have been assigned the HTTPDestViewer or HTTPDestAdministrator user role.

Context

SAP HANA Extended Application Services (SAP HANA XS) includes a server-side JavaScript API that enables
outbound access to a defined HTTP destination. The HTTP destination provides services which an application
can use, for example, to read live data. In this tutorial, you create a JavaScript application that queries financial
services to display the latest stock values. The financial services are available on a remote server, whose details
are specified in an HTTP destination configuration.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the application package structure that will contain the artifacts required for this tutorial:
a. From the context menu of the Content folder, choose Create Application.
b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter a package name, for example, testApp, and choose Create.
The system creates the index.html, .xsaccess, and .xsapp files.
d. Delete the index.html file.
3. Define the details of the HTTP destination.
You define the details of an HTTP destination in a configuration file that requires a specific syntax. The
configuration file containing the details of the HTTP destination must have the file
extension .xshttpdest.

SAP HANA Developer Guide

388 PUBLIC Writing Server-Side JavaScript Code
 Caution
You must place the HTTP destination configuration and the XSJS application that uses it in the same
application package. An application cannot reference an HTTP destination configuration that is located
in another application package.

a. From the context menu of the testApp folder, choose New File .
b. Enter a file name, for example, yahoo.xshttpdest, and choose Create.
c. Enter the following code in the new file yahoo.xshttpdest.

host = "download.finance.yahoo.com";
port = 80;
description = "my stock-price checker";
useSSL = false;
pathPrefix = "/d/quotes.csv?f=a";
authType = none;
proxyType = none;
proxyHost = "";
proxyPort = 0;
timeout = 0;

d. If necessary, set proxyType to http and enter your proxy host and port number.
e. Save the file.
4. View the activated HTTP destination.
You can use the SAP HANA XS Administration Tool to check the contents of an HTTP destination
configuration.

Note
To make changes to the HTTP Destination configuration, you must use a text editor, save the changes
and reactivate the file.

To start the SAP HANA XS Administration Tool, select the yahoo.xshttpdest file and choose
(Maintain Credentials) in the toolbar. The details of the HTTP destination are displayed.
5. Create a server-side JavaScript application that uses the HTTP destination you have defined.
The XSJS file must have the file extension .xsjs, for example, sapStock.xsjs.

Caution
You must place the XSJS application and the HTTP destination configuration it references in the same
application package. An application cannot use an HTTP destination configuration that is located in
another application package.

a. From the context menu of the testApp folder, choose New File .
b. Enter the file name sapStock.xsjs and choose Create.
c. Enter the following code in the new file sapStock.xsjs.
In this example, you define the following:
○ A variable (<stock>) that defines the name of the stock whose value you want to check, for
example SAP.DE
○ A variable (<amount>) that defines the number of stocks you want to check, for example, 100

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 389
 ○ A variable (<dest>) that retrieves metadata defined for the specified HTTP(S) destination, for
example: host, port, useSSL
○ A variable (<client>) that creates the client for the outbound connection
○ A variable (<req>) that enables you to add details to the request URL
○ A variable (<res>) that calculates the value of the stock/amount
○ The format and content of the response body displayed in the browser

var stock = $.request.parameters.get("stock");

var amount = $.request.parameters.get("amount");
var dest = $.net.http.readDestination("testApp", "yahoo");
var client = new $.net.http.Client();
var req = new $.web.WebRequest($.net.http.GET, "&s=" + stock);
client.request(req, dest);
var response = client.getResponse();
var co = [],
he = [];
for (var c in response.cookies) {
if (response.cookies.hasOwnProperty(c)) {
co.push(response.cookies[c]);
}
}
for (var h in response.headers) {
if (response.headers.hasOwnProperty(h)) {
he.push(response.headers[h]);
}
}
if (response.body) {
var body = response.body.asString();
}
$.response.contentType = "application/json";
var res = parseInt(response.body.asString(), 10) * amount;
$.response.setBody(amount + " of your " + stock + " stocks" + " are worth:
" + res);

d. Save the file.

6. Call the service provided by the application sapStock.xsjs.

a. Select the sapStock.xsjs file and choose (Run) in the toolbar.

b. Edit the URL parameters as follows and press Enter :

/testApp/sapStock.xsjs?amount=100&stock=SAP.DE

The current value of your specified number of stocks is shown, for example:

100 of your SAP.DE stocks are worth: 5700

7. Enter different values for the parameters amount and stock in the URL:
○ amount=250
Change the number of stocks from 100 to 250.
○ stock=MCRO.L
Change the name of the stock to check from SAP.DE to MCRO.L.

SAP HANA Developer Guide

390 PUBLIC Writing Server-Side JavaScript Code
7.4.2 Tutorial: Call an XS Procedure with Table-Value
Argument

You can use the XS Procedures library to call stored procedures as if they were JavaScript functions.

Prerequisites

● The delivery unit HANA_XS_DBUTILS contains the XS procedures library. The content is available in the
package sap.hana.xs.libs.dbutils.
● Create a new (or use an existing) stored procedure.
This tutorial refers to the stored procedure get_product_sales_price, which is included in the
demonstration content provided with the SAP HANA Interactive Education (SHINE) delivery unit (DU). The
SHINE DU is available for download in the SAP Software Download Center.

Note
Access to the SAP Software Download Center is only available to SAP customers and requires logon
credentials.

Context

You can call stored procedures by using the contents of the XS Procedures library as if they were JavaScript
functions. For example, the library allows you to pass arguments as a JavaScript object to a stored procedure
that expects table arguments; XS Procedures manages the creation and use of the temporary tables needed to
pass arguments to a table-valued procedure. You can use the functions provided with the XS procedures library
to enable programmatic access to stored procedures in the SAP HANA database from an XS JavaScript
service; the access is provided by binding the stored procedure to a JavaScript function. The result of the call to
the bound function is a JavaScript object, whose properties are the outbound parameters of the procedure.

Procedure

1. Import the XS procedures library.

In your server-side (XS) JavaScript code, ensure that the XS procedures are made available.

var XSProc = $.import("sap.hana.xs.libs.dbutils", "procedures");

2. Specify a schema where temporary tables can be created and filled with the values that are passed as
arguments to the stored procedure.
XS procedures use temporary tables to pass table-valued parameters. As a user of XS procedures you
must specify the name of a schema where these temporary tables reside, for example, a user's own
schema.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 391
 Note
The application code using XS procedures must ensure that the necessary privileges have been granted
to enable the creation and update of (and selection from) temporary tables in the specified schema.

XSProc.setTempSchema($.session.getUsername().toUpperCase());

3. Bind the stored procedure to a JavaScript function.

This step creates one or more JavaScript functions which can later be used to call the stored procedure.
You can also define functions which map your call arguments to the parameters of the stored procedure.

var createPurchaseOrder = XSProc.procedure("SAP_HANA_DEMO",

"sap.hana.democontent.epm.Procedures", "poCreate", {connection: conn});

Note
XS procedures uses the connection {connection: conn} passed in a configuration object as a
parameter. If no connection object is passed, the XS procedure library opens a separate connection for
the call and closes the connection after the call completes.

4. Call the procedure.

Use the imported procedure like a normal JavaScript function using JavaScript object argument lists.

var result = createPurchaseOrder([{

"PURCHASEORDERID": '0300009001',
"HISTORY.CREATEDBY": '0000000044',
"HISTORY.CREATEDAT": new Date(),
"HISTORY.CHANGEDBY": '0000000044',
"HISTORY.CHANGEDAT": new Date()
}]);

Table-valued input arguments are passed to the stored procedure using a Javascript array that
corresponds to the rows of the table containing the values to pass. The row objects should contain the
properties of the name of the columns. Skipped columns are filled with NULL; properties without a same-
named column are ignored.

Example

var XSProc = $.import("sap.hana.xs.libs.dbutils", "procedures");

XSProc.setTempSchema($.session.getUsername().toUpperCase());
var conn = $.db.getConnection();
var createPurchaseOrder = XSProc.procedure(
"SAP_HANA_DEMO", "sap.hana.democontent.epm.Procedures",
"poCreate", {connection: conn}
);
var result = createPurchaseOrder([{
"PURCHASEORDERID": '0300009001',
"HISTORY.CREATEDBY": '0000000044',
"HISTORY.CREATEDAT": new Date(),
"HISTORY.CHANGEDBY": '0000000044',
"HISTORY.CHANGEDAT": new Date()
}]);
if (result && result.ERROR.length > 0) {
$.response.setBody(result.ERROR.length + " errors occurred.");
} else {
$.response.setBody("no error occurred");
}

SAP HANA Developer Guide

392 PUBLIC Writing Server-Side JavaScript Code
7.4.2.1 Accessing Stored Procedures from XS JavaScript

Call stored SAP HANA procedures from XS server-side JavaScript (XSJS) and process the results of the calls in
JavaScript.

XS procedures provide a convenient way to call stored procedures in SAP HANA from XS server-side Javascript
(XSJS) and process the results of the calls in JavaScript. The XS procedures library extends the features
already available with the SAP HANA XS JavaScript database API. Using XS procedures, SAP HANA stored
procedures can be considered as simple XS JavaScript functions for anyone developing XS JavaScript services.

For example, where an SAP HANA stored procedure uses a table as input parameter and a table as output, XS
Procedures use JavaScript objects (or an array of objects) which can be passed to the procedure. Similarly, the
result of the procedure call is provided as an array of JavaScript objects. You declare a stored procedure as an
XS JavaScript function and then call the stored procedure as if it were a JavaScript function delivering a
JavaScript object.

To use a stored procedure as an XS JavaScript function, the following steps are required:

Step Action Description

1 Import the XS Procedures library Provide access to the XS procedures

Restriction
XSProc is intended only for use with database connec­
tions made with the old $.db API. It is not recommended
to use XSProc with $.hdb connections. For $.hdb
connections, use $hdb.loadProcedure instead.

2 Specify a schema for temporary tables Temporary tables are used to store the JavaScript arguments
provided for the function.

3 Import the procedure Create the XS JavaScript functions, which can later be used
to call the stored SAP HANA procedure. You can define func­
tions which map your call arguments to the parameters of
the stored procedure.

4 Call the procedure Use the imported procedure in the same way as any normal
JavaScript function, for example, using JavaScript object ar­
gument lists.

Restriction
XSProc is intended only for use with database connec­
tions made with the old $.db API. For $.hdb connec­
tions, use $hdb.loadProcedure instead.

Use Arguments that Reference an Exist­ (Optional) Write the results or a procedure call into a physi­
ing Table [page 394] cal table and pass the table as an argument rather than a
JavaScript object

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 393
Step Action Description

Use Table-Valued Arguments [page 394] (Optional) Call a procedure with arguments stored as values
in a table

Calling Procedures with Arguments that Reference an Existing Table

If you want to pass a table as an argument rather than a JavaScript object, you must specify the name of the
table (as a string) in the call statement as well as the name of the schema where the table is located. The
following example shows how to reference the table rating_table.

getRating('schema.rating_table', 3);

The SAP HANA database enables you to materialize the results of a procedure call; that is, to write the results
into a physical table using the WITH OVERVIEW expression. In the WITH OVERVIEW expression, you pass a
string value to the output parameter position that contains the result you want to materialize. The value
returned is not the rating itself, but a reference to the table into which the results have been written. The results
of the procedure call can now be retrieved from the specified table, in this example, OUTPUT_TABLE.

var resCall = getRating(rating, 3, "schema.output_table");

// {"RESULT": [{"variable":"RESULT","table":"\"SCHEMA\".\"OUTPUT_TABLE\""}]}

The WITH OVERVIEW expression also allows you to write the results of a procedure into a global temporary
table; that is, a table that is truncated at session close. To use XS Procedures to write the results of a procedure
into a global temporary table, you do not specify a name for the result table; you include an empty string (''),
as illustrated in the following example:

var conn = $.db.getConnection();

resCall = getRating(rating, 3, '', conn);
// {"RESULT": [{"variable":"RESULT","table":"\"SCHEMA\".
\"RESULT_5270ECB8F7061B7EE10000000A379516\""}]}

The returned reference points to a global temporary table which can be queried for the procedure results with
the same connection.

Note
To ensure access to the global temporary table, it is necessary to specify the connection object conn.

Using Table-Valued Arguments

XS Procedures enables you to call procedures with arguments stored as values in a table, as illustrated in the
following example. Table-valued input arguments are passed using a JavaScript array that corresponds to the
rows of the table to pass. These row objects must contain properties that correspond to the name of the

SAP HANA Developer Guide

394 PUBLIC Writing Server-Side JavaScript Code
columns. Skipped columns are filled with NULL, and properties that do not correspond to an identically named
column are ignored.

var XSProc = $.import("sap.hana.xs.libs.dbutils", "procedures");

XSProc.setTempSchema($.session.getUsername().toUpperCase());
var conn = $.db.getConnection();
var createPurchaseOrder = XSProc.procedure("SAP_HANA_DEMO",
"sap.hana.democontent.epm.Procedures::poCreate", {
connection: conn
});
var result = createPurchaseOrder([{
"PURCHASEORDERID": '0300009001',
"HISTORY.CREATEDBY": '0000000044',
"HISTORY.CREATEDAT": new Date(),
"HISTORY.CHANGEDBY": '0000000044',
"HISTORY.CHANGEDAT": new Date()
}]);
if (result && result.ERROR.length > 0) {
$.response.setBody(result.ERROR.length + " errors occurred.");
} else {
$.response.setBody("no error occurred");
}

Related Information

SAP HANA XS JavaScript API Reference

7.4.3 Tutorial: Query a CDS Entity using XS Data Services

You can use the SAP HANA XS Data Services (XSDS) library to query CDS entities as if they were JavaScript
objects.

Prerequisites

This tutorial refers to CDS models that are included in the demonstration content provided with the SAP HANA
Interactive Education (SHINE) delivery unit (DU). The SHINE DU is available for download in the SAP Software
Download Center.

Note
Access to the SAP Software Download Center is only available to SAP customers and requires logon
credentials.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 395
Context

XS Data Service queries are used to build incrementally advanced queries against data models that are defined
with Core Data Service. Query results are arrays of nested JSON objects that correspond to instances of CDS
entities and their associations.

Procedure

1. Import the XS DS library and reference it through a variable.

var XSDS = $.import("sap.hana.xs.libs.dbutils", "xsds");

2. Import the CDS entities you want to query.

As a first step to working with CDS entities in SAP HANA XS JavaScript, you must import the CDS entities.
The following example shows how to import to the entities as defined in the SHINE demonstration content:

var soItem = XSDS.$importEntity("sap.hana.democontent.epm.data",

"EPM.SO.Item");
var soHeader = XSDS.$importEntity("sap.hana.democontent.epm.data",
"EPM.SO.Header", {
items: {
$association: {
$entity: soItem,
$viaBacklink: "SALESORDERID"
}
}
});

In addition to the basic CDS definition, the code in the example above shows how to extend the definition of
soHeader by an explicit association called items. This is done by using the keyword $association
together with the referenced entity (soItem) and the type of the association. In this case, $viaBacklink
is used as type, that is; the items of soHeader stored in soItem have a foreign key SALESORDERID
referencing the key of the soHeader table.
3. Add a query.
A general query related to an entity is built by calling the $query() method of the entity constructor.

var qOrders = soHeader.$query();

4. Refine the query if required.

You can refine the query object as necessary to suit your use case. For example, you can specify that the
query returns only the first three (3) entries.

qOrders = qOrders.$limit(3);

5. Execute the query.

Use the $execute method to run the query.

var result = qOrders.$execute();

result contains an array of unmanaged values, each of which represents a row of the Post entity.

SAP HANA Developer Guide

396 PUBLIC Writing Server-Side JavaScript Code
 Note
In the refinements to the query, you must call $execute to send the query to the database.

6. Specify the fields the query should return.

Use the $project() method to create a query which specifies the fields the query should return. For
example, you can return the IDs of the sales orders together with the net amount of the header and the net
amount of all items.

var qOrderAndItemTitles = qOrders.$project({

SALESORDERID: true,
NETAMOUNT: "TotalNet",
items: {
NETAMOUNT: true
}
});

The list of projected fields is a JavaScript object, where desired fields are marked by either true or a String
literal such as "TotalNet" denoting an alias name. The query illustrated in the example above would
return the following result.

[{
"SALESORDERID": "0500000236",
"TotalNet": 273.9,
"items": {
"NETAMOUNT": 29.9
}
}, {
"SALESORDERID": "0500000236",
"TotalNet": 273.9,
"items": {
"NETAMOUNT": 102
}
}, {
"SALESORDERID": "0500000236",
"TotalNet": 273.9,
"items": {
"NETAMOUNT": 55
}
}]

The actual database query automatically JOINs all required tables based on the associations involved. In
the example above, the generated SQL looks like the following:

Note
In the following code example, the names of table are abbreviated to help readability.

SELECT "t0"."SALESORDERID" AS
"t0.SALESORDERID",
"t0"."NETAMOUNT" AS "t0.NETAMOUNT",
"t0.items"."NETAMOUNT" AS "t0.items.NETAMOUNT"
FROM "Header" "t0"
LEFT OUTER JOIN "Item" "t0.items"
ON "t0"."SALESORDERID"="t0.items"."SALESORDERID"
LIMIT 10

7. Use conditions to restrict the result set.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 397
 You can use the $where() method to set conditions that restrict the result set returned by the query. The
following example show how to select all items with a net amount equal to a half (or more) of their order's
net amount.

var qSelectedOrders =
qOrderAndItemTitles.$where(soHeader.items.NETAMOUNT.
$div(soHeader.NETAMOUNT).$gt(0.5))

References to fields and associations such as items are available as properties of the entity constructor
function, for example, soHeader.items. As in the case with projections, XSDS generates all required
JOINs for associations referenced by the conditions automatically, even if they are not part of the current
projection. To build more complex expressions in $where, see the SAP HANA XS Data Services JavaScript
API Reference.
8. Refine the query conditions to a specific matching pattern.
With the $matching() method you can specify conditional expressions using the JSON-like syntax of the
$find() and $findAll() methods. The following code example shows how to further refine the selection
returned by the result set, for example, to accept only those items with a EUR currency and quantity
greater than 2.

qSelectedOrders = qSelectedOrders.$matching({
items: {
CURRENCY: 'EUR',
QUANTITY: {
$gt: 2
}
}
});

Tip
Unlike $findAll(), $matching() returns an unmanaged plain value and ignores all unpersistent
changes to any entity instances.

9. Add arbitrary values to the result set.

You can add arbitrary calculated values to the result set by using the $addFields() method. The
following example shows how to query the days passed since the delivery of the sales item.

qSelectedOrders = qSelectedOrders.$addFields({
"DaysAgo": soHeader.items.DELIVERYDATE.$prefixOp("DAYS_BETWEEN", new
Date())
});

Note
This query refers to the SQL function DAYS_BETWEEN, which is not a pre-defined function in XSDS.
Instead, you can use the generic operator $prefixOp, which can be used for any SQL function f, for
example, with the syntax f(arg1, … argN).

10. Use aggregations with calculated fields.

Aggregations are a special case of calculated fields that combine the $addFields() operator with an
additional $aggregate() method. The following example shows to retrieve the average quantity of the
first 100 sales order IDs together with their product ID.

var qAverageQuantity = soItem.$query().$limit(100).$aggregate({

SAP HANA Developer Guide

398 PUBLIC Writing Server-Side JavaScript Code
 SALESORDERID: true,
PRODUCTID: true
}).$addFields({
averageQuantity: soItem.QUANTITY.$avg()
});

Tip
In SQL terms, the $aggregate() operator creates a GROUP BY expression for the specified paths and
automatically projects the result.

If you need to use a more restrictive projection, you can replace true with false in the $aggregate call,
as illustrated in the following example, which removes the sales order IDs for the result set.

var qAverageQuantity = soItem.$query().$limit(100).$aggregate({

SALESORDERID: false,
PRODUCTID: true
}).$addFields({
averageQuantity: soItem.QUANTITY.$avg()
});

11. Specify the order of the result set.

To specify the order in the result set, you can use the $order() method, including a number of order
criteria as arguments. Each order criteria contains a property “by” with an expression that defines the
desired order. Optionally each criterion can contain a flag $desc to require a descending order and a
$nullsLast flag. The following example uses two criteria to display the result set first in descending order
by the net amount in the header and then ascending order by the item net amount.

qSelectedOrders = qSelectedOrders.$order({$by: soHeader.NETAMOUNT,

$desc:true},
{$by: soHeader.items.NETAMOUNT});

12. Remove duplicates entries from the result set.

The $distinct operator removes duplicates from the result set. The following example shows how to
display the set of all the currencies used in the sales orders.

var qAllCurrencies = soHeader.$query().$project({CURRENCY: true}).$distinct();

7.4.4 Tutorial: Update a CDS Entity Using XS Data Services

You can use the XS Data Services (XSDS) library to update CDS entities as if they were JavaScript objects.

Prerequisites

This tutorial refers to CDS models that are included in the demonstration content provided with the SAP HANA
Interactive Education (SHINE) delivery unit (DU). The SHINE DU is available for download in the SAP Software
Download Center.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 399
 Note
Access to the SAP Software Download Center is only available to SAP customers and requires logon
credentials.

Context

For read-write scenarios, SAP HANA XS Data Services (XSDS) offer a managed mode with automatic entity
management and additional consistency guarantees. Managed mode shares CDS imports and transaction
handling with unmanaged mode but uses a different set of methods provided by the entity constructors.

Procedure

1. Import the XSDS library and the CDS entities into your application.
In your entity import, specify a SAP HANA sequence that is used to generate the required keys.

// import XSDS client library

var XSDS = $.import("sap.hana.xs.libs.dbutils", "xsds");
// import CDS entity as XSDS entity
var SOItem = XSDS.$importEntity("sap.hana.democontent.epm.data",
"EPM.SO.Item");
var SOHeader = XSDS.$importEntity("sap.hana.democontent.epm.data",
"EPM.SO.Header", {
SALESORDERID: { $key: "\"SAP_HANA_DEMO\".
\"sap.hana.democontent.epm.data::salesOrderId\"" },
items: {
$association: {
$entity: SOItem,
$viaBacklink: "SALESORDERID"
}
}
});

2. Retrieve an existing entity instance in managed mode.

The $importEntity() function returns a constructor for the entity imported. To retrieve an existing
entity instance in managed mode, run a query using the entity's key (for example, using $get), or retrieve
multiple instances that satisfy a given condition.

var order = SOHeader.$get({ SALESORDERID:

"0500000236" }); // by key
var orders = SOHeader.$findAll({ LIFECYCLESTATUS: "N", TAXAMOUNT: { $gt:
17000 } }); // by filter

3. Use or modify entity instances as required.

Iinstances of CDS entities are regular JavaScript objects which you can use and modify as required.

order.CURRENCY = "USD";
order.HISTORY.CHANGEDAT = new Date();

4. Ensure all changes are made persistent in the database.

SAP HANA Developer Guide

400 PUBLIC Writing Server-Side JavaScript Code
 Calling $save() flushes in-memory changes of the instance and all its reachable associated instances to
the database. Only entity instances that have been changed will be updated in the database.

order.$save();

5. Use the entity constructor to create a new CDS instance.

The key is generated automatically by the SAP HANA sequence supplied during the import of the XSDS
library and the CDS entities into your application.

var newOrder = new SoHeader ({

TAXAMOUNT": 69.04,
NETAMOUNT": 190.9,
GROSSAMOUNT": 325.94,
CURRENCY": "EUR",
PARTNERID": "0100000044",
DELIVERYSTATUS: "I",
BILLINGSTATUS: "I",
LIFECYCLESTATUS: "N",
HISTORY": {
CHANGEDAT": Date.now(),
CHANGEDBY": "0000000033",
CREATEDAT": Date.now(),
CREATEDBY": "0000000033"
},
items: []
});
newOrder.$save();

6. Discard any unwanted instances of a CDS entity.

Retrieved CDS entities are stored in the entity manager cache and subject to general JavaScript garbage-
collection rules. Use the $discard() function to permanently delete an entity instance from the database.

order.$discard();

7. Control how associations in a CDS document are followed.

By default, all associations are resolved, that is; association properties store a reference to their associated
entity instance. For heavily connected data, this may lead to very large data structures in memory. A “lazy”
association will delay the retrieval of the associated instances until the property is actually accessed. The
first time the lazy association is accessed, the associated entity is queried from the entity cache or the
database. After a lazy association has been resolved, it becomes a normal property of its parent entity
instance.

To control how associations are being followed, declare “lazy” associations during the import operation, as
shown in the following example:

var SOHeader = XSDS.$importEntity("sap.hana.democontent.epm.data",

"EPM.SO.Header", {
SALESORDERID: { $key: "\"SAP_HANA_DEMO\".
\"sap.hana.democontent.epm.data::salesOrderId\"" },
items: {
$association: {
$entity: SOItem,
$viaBacklink: "SALESORDERID",
$lazy: true
}
}
});

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 401
 The retrieval of “Lazy” associations is handled transparently by XSDS.

var order = SOHeader.$get({ SALESORDERID: "0500000236" }); // retrieve

single SO header
if (order.DELIVERYSTATUS != "D")
return; // return without loading SO items from database
for (var item in order.items) { … }; // now retrieve items for processing

8. Manually control transactions for your application where necessary.

Every SAP HANA XS application using XSDS is associated with one database connection and one
transaction. This is also true if the application uses multiple imports of the XSDS library; XS libraries are
single instances by default. Entities retrieved from the database are stored in the entity manager cache,
and any updates need to be saved explicitly to the database. By default, database saves will automatically
commit the changes to the database. However, you can manually control transactions for your application
by disabling auto-commit and calling $commit and $rollback explicitly, as illustrated in the following
example.

// disable auto-commit
XSDS.Transaction.$setAutoCommit(false);
var order = SOHeader.$get({ SALESORDERID: "0500000236" });
order.CURRENCY = "JPY";
order.$save(); // persist update
XSDS.Transaction.$commit(); // commit change
order.CURRENCY = "EUR";
order.$save(); // persist update
order.HISTORY.CHANGEDAT = new Date();
order.$save(); // persist update
XSDS.Transaction.$rollback(); // database rollback
// order #0500000236 now has currency JPY again

7.5 Creating Custom XS SQL Connections

In SAP HANA Extended Application Services (SAP HANA XS), you use the SQL-connection configuration file to
configure a connection to the database; the connection enables the execution of SQL statements from inside a
server-side JavaScript application with credentials that are different to the credentials of the requesting user.

In cases where it is necessary to execute SQL statements from inside your server-side JavaScript application
with credentials that are different to the credentials of the requesting user, SAP HANA XS enables you to define
and use a specific configuration for individual SQL connections. Each connection configuration has a unique
name, for example, Registration or AdminConn, which is generated from the name of the corresponding
connection-configuration file (Registration.xssqlcc or AdminConn.xssqlcc) on activation in the
repository. The administrator can assign specific, individual database users to this configuration, and you can
use the configuration name to reference the unique SQL connection configuration from inside your JavaScript
application code.

The following code example shows how to use the XS SQL connection AdminConn.xssqlcc.

function test() {
var body;
var conn;
$.response.status = $.net.http.OK;
try {
conn = $.db.getConnection("sap.hana.sqlcon::AdminConn");
var pStmt = conn.prepareStatement("select CURRENT_USER from dummy");

SAP HANA Developer Guide

402 PUBLIC Writing Server-Side JavaScript Code
 var rs = pStmt.executeQuery();
if (rs.next()) {
body = rs.getNString(1);
}
rs.close();
pStmt.close();
} catch (e) {
body = "Error: exception caught";
$.response.status = $.net.http.BAD_REQUEST;
}
if (conn) {
conn.close();
}
$.response.setBody( body );
}
test();

To use the SQL connection from your application during runtime, you must bind the SQL connection
configuration to a registered database user and assign the user the appropriate permissions, for example, by
assigning a pre-defined role to the user. To maintain this user mapping, SAP HANA XS provides the Web-based
SAP HANA XS Administration Tool. When the run-time status of the XSSQLCC artifact is set to active, SAP
HANA generates a new auto user (with the name XSSQLCC_AUTO_USER_[...]. The new user is granted the
permissions specified in a role, which can be assigned using the parameter role_for_auto_user - either in
the design-time artifact or the run-time configuration.

Note
Access to the tools provided by the XS Administration Tool requires the privileges granted by one or more
specific user roles.

To use the SAP HANA XS Administration Tool to view or maintain an XS SQL connection configuration, you need
the privileges granted by the following SAP HANA XS roles:

● sap.hana.xs.admin.roles::SQLCCViewer
Required to display the available SQL Connections and the current user mapping
● sap.hana.xs.admin.roles::SQLCCAdministrator
Required to modify details of the user mapping; the SQLCCAdministrator role includes the role
SQLCCViewer.

Troubleshooting Tips

If you are having problems implementing the XS SQL connection feature using an .xssqlcc configuration,
check the following points:

● User permissions
Make sure that you grant the necessary user the activated role (for example,
sap.hana.xs.admin.roles::SQLCCAdministrator). You can use the developer tools to grant roles (or
privileges), as follows:

Note
The granting user must have the object privilege EXECUTE on the procedure
GRANT_ACTIVATED_ROLE.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 403
 ○ SAP HANA studio
In the Systems view of the Administration Console perspective, choose Security Users
○ SAP HANA Web-based Development Workbench
In the Security tool, expand the Users node, choose the target (or add a new) user, and use the Granted
roles tab.
○ XS Administration Tools
In the SQL Connection Details tab of the XSSQLCC artifact's run time configuration. To edit user/role
details here, you will need the role SQLCCAdministrator and, in addition, the appropriate administrator
permissions required to set up (and assign roles to) a database user.
● File location
Make sure that the SQL-role configuration file (.xssqlcc) you create is located in the same package as
the application that references it.
● Logon dependencies
If your application is using form-based logon (configured in the application's .xsaccess file), make sure
the libxsauthenticator library is present and specified in the list of trusted libraries displayed in the
SAP HANA studio's Administration Console perspective ( Administration Configuration Tab
xsengine.ini application_container application_list . If the libxsauthenticator library is not in the
list of authorized libraries, an SAP HANA system administrator must add it.

Note
If you have to authorize libxsauthenticator, you might also need to refresh the Web page in your
browser the next time you want to access .xssqlcc to display the logon dialog again.

7.5.1 Create an XS SQL Connection Configuration

The .xssqlcc file enables you to establish a database connection that you can use to execute SQL statements
from inside your server-side JavaScript application with credentials that are different to the credentials of the
requesting user.

Prerequisites

You have been assigned the following SAP HANA user roles:

● sap.hana.xs.admin.roles::SQLCCViewer
● sap.hana.xs.admin.roles::SQLCCAdministrator

Note
This tutorial combines tasks that are typically performed by two different roles: the application developer
and the database administrator. The developer would not normally require the privileges of the SAP HANA
administrator or those granted by the SQLCCAdministrator user role.

SAP HANA Developer Guide

404 PUBLIC Writing Server-Side JavaScript Code
Context

In this tutorial, you learn how to configure an SQL connection that enables you to execute SQL statements from
inside your server-side JavaScript application with credentials that are different to the credentials of the user
requesting the XSJS service.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the application package structure that will contain the artifacts required for this tutorial:
a. From the context menu of the Content folder (or a folder of your choice), choose Create Application.
b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter a package name, for example, testApp, and choose Create.
The system creates the index.html, .xsaccess, and .xsapp files.
d. Check the contents of the .xsaccess file.

{
"exposed" : true,
"authentication" : { "method" : "Form"},
"prevent_xsrf" : true
}

The entries in the .xsaccess file ensure the following:

○ Application data can be exposed to client requests
○ User name and password credentials are required for logon authentication
○ Protection against cross-site, request-forgery attacks is enabled
3. Create the XS SQL connection configuration file.

a. From the context menu of the testApp folder, choose New File .
b. Enter a file name, for example, AdminConn.xssqlcc, and choose Create.

Note
The SQL connection configuration file (.xssqlcc) you create must be located in the same package
as the application that references it.

4. Configure the details of the SQL connection that the XS JavaScript service will use.
a. Define the required connection details.

{
"description" : "Admin SQL connection"
"role_for_auto_user" : "com.acme.roles::JobAdministrator"
}

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 405
 Tip
Replace the package path (com.acme.roles) and role name (JobAdministrator) with the
suitable ones for your case.

b. Save the SQL connection configuration file.

The SQL connection configuration file AdminConn.xssqlcc is activated and a catalog object created
with the name testApp::AdminConn, which can be referenced in an XS JavaScript application.
5. Write an XS JavaScript application that calls the XS SQL connection configuration.
To create a preconfigured SQL connection using the configuration object AdminConn, for example, from
inside your JavaScript application code, you must reference the object using the object name with the full
package path, as shown in the following code example:

function test() {
var body;
var conn;
$.response.status = $.net.http.OK;
try {
conn = $.db.getConnection("testApp::AdminConn");
var pStmt = conn.prepareStatement("select CURRENT_USER from dummy");
var rs = pStmt.executeQuery();
if (rs.next()) {
body = rs.getNString(1);
}
rs.close();
pStmt.close();
} catch (e) {
body = "Error: exception caught";
$.response.status = $.net.http.BAD_REQUEST;
}
if (conn) {
conn.close();
}
$.response.setBody( body );
}
test();

6. Save the changes to the artifacts you have created.

7. Bind the SQL connection configuration to a user.
You use the Web-based SAP HANA XS Administration Tool to configure the runtime elements of the XS SQL
connection.

To start the SAP HANA XS Administration Tool, select the AdminConn.xssqlcc file and choose
(Maintain Details) in the toolbar.
The details of the XS SQL configuration connection are displayed.
8. Set the runtime status of the XS SQL connection configuration.

You must change the runtime status of the XS SQL connection configuration to Active. This runtime status
can only be changed by an administrator. When the runtime status of the XSSQL connection configuration
is set to active, SAP HANA automatically generates a new user (XSSQLCC_AUTO_USER_[...]) for the
XSSQL connection configuration object and assigns the role defined in role_for_auto_user to the new
auto-generated user.

SAP HANA Developer Guide

406 PUBLIC Writing Server-Side JavaScript Code
Related Information

The SQL Connection Configuration File [page 407]

SQL Connection Configuration Syntax [page 408]

7.5.2 The SQL Connection Configuration File

The SQL-connection configuration file specifies the details of a connection to the database that enables the
execution of SQL statements from inside a server-side (XS) JavaScript application with credentials that are
different to the credentials of the requesting user.

If you want to create an SQL connection configuration, you must create the configuration as a flat file and save
the file with the suffix .xssqlcc, for example, MYSQLconnection.xssqlcc. The new configuration file must
be located in the same package as the application that references it.

Note
An SQL connection configuration can only be accessed from an SAP HANA XS JavaScript application
(.xsjs) file that is in the same package as the SQL connection configuration itself. Neither subpackages nor
sibling packages are allowed to access an SQL connection configuration.

The following example shows the composition and structure of a configuration file AdminConn.xssqlcc for an
SAP HANA XS SQL connection called AdminConn. On activation of the SQL connection configuration file
AdminConn.xssqlcc (for example, in the package sap.hana.sqlcon), an SQL connection configuration
with the name sap.hana.sqlcon::AdminConn is created, which can be referenced in your JavaScript
application. In the xssqlcc artifact, you can set the following values:

● description
A short description of the scope of the xs sql connection configuration
● role_for_auto_user
The name of the role to be assigned to the auto user (if required) that the XSSQL connection uses, and the
absolute path to the package where the role definition is located in the SAP HANA repository.

sap.hana.sqlcon::AdminConn.xssqlcc

{
"description" : "Admin SQL connection"
"role_for_auto_user" : "com.acme.roles::JobAdministrator"
}

The run-time status of an XSSQL connection configuration is inactive by default; the run-time status can only
be activated by an SAP HANA user with administrator privileges, for example, using the SAP HANA XS
Administration Tools. When the run-time status of the XSSQLCC artifact is set to active, SAP HANA generates a
new auto user (with the name XSSQLCC_AUTO_USER_[...]) and assigns the role defined in
role_for_auto_user to the new auto-generated user.

Tip
In the SAP HANA XS Administration Tools, it is possible to view and edit both the the user's parameters and
the role's definition.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 407
To create a preconfigured SQL connection using the configuration object AdminConn, for example, from inside
your JavaScript application code, you reference the object using the object name and full package path, as
illustrated in the following code example.

{
conn = $.db.getConnection("sap.hana.sqlcon::AdminConn");
}

Related Information

SQL Connection Configuration Syntax [page 408]

7.5.3 SQL Connection Configuration Syntax

The XS SQL connection-configuration file .xssqlcc uses pairs of keywords and values to define the SQL
connection.

Example
The XS SQL Connection Configuration (.xssqlcc) File

Code Syntax

{
"description" : "Admin SQL connection"
"role_for_auto_user" : "com.acme.roles::JobAdministrator"
}

description

A short description of the selected SQL connection configuration.

Sample Code

"description" : "Admin SQL connection"

role_for_auto_user

The name of (and package path to) the role assigned to be assigned to the new user that is automatically
generated on activation of the XSSQL connection-configuration artifact.

SAP HANA Developer Guide

408 PUBLIC Writing Server-Side JavaScript Code
 Sample Code

"role_for_auto_user" : "com.acme.roles::JobAdministrator"

Activating the design-time XSSQL connection configuration generates a run-time object whose status is
“inactive” by default; the run-time status must be set to active by an SAP HANA user with administrator
privileges, for example, using the SAP HANA XS Administration Tools. When the run-time status of the
XSSQLCC artifact is set to active, SAP HANA generates a new auto user (with the name
XSSQLCC_AUTO_USER_[...]) and assigns the role defined in role_for_auto_user to the new auto-
generated user.

Related Information

The SQL Connection Configuration File [page 407]

7.6 Setting the Connection Language in SAP HANA XS

HTTP requests can define the language used for communication in the HTTP header Accept-Language. This
header contains a prioritized list of languages (defined in the Browser) that a user is willing to accept. SAP
HANA XS uses the language with the highest priority to set the language for the requested connection. The
language setting is passed to the database as the language to be used for the database connection, too.

In server-side JavaScript, the session object's language property enables you to define the language an
application should use for a requested connection. For example, your client JavaScript code could include the
following string:

var application_language = $.session.language = 'de';

Note
Use the language-code format specified in BCP 47 to set the session language, for example: “en-US” (US
English), “de-AT” (Austrian German), “fr-CA” (Canadian French).

As a client-side framework running in the JavaScript sandbox, the SAP UI5 library is not aware of the Accept-
Language header in the HTTP request. Since the current language setting for SAPUI5 is almost never the
same as the language specified in the SAP HANA XS server-side framework, SAPUI5 clients could have
problems relating to text displayed in the wrong language or numbers and dates formatted incorrectly.

The application developer can inform the SAP UI5 client about the current server-side language setting, for
example, by adding an entry to the <script> tag in the SAPUI5 HTML page, as illustrated in the following
examples:

● Script tag parameter:

<script id="sap-ui-bootstrap"

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 409
 type="text/javascript"
src="/sap/ui5/1/resources/sap-ui-core.js"
data-sap-ui-theme="sap_goldreflection"
data-sap-ui-libs="sap.ui.commons"
data-sap-ui-language="de">
</script>

● Global sap-ui-config object:

<script>
window["sap-ui-config"] = {
"language" : "de"
}
</script>
[…]
<script id="sap-ui-bootstrap"
[…]
</script>

The sap-ui-config object must be created and filled before the sap-ui-bootstrap script.

It is important to understand that the session starts when a user logs on, and the specified language is
associated with the session. Although the user can start any number of applications in the session, for
example, in multiple Browser tabs, it is not possible to set a different language for individual applications called
in the session,

Setting the Session Language on the Server side

The script tag for the SAPUI5 startup can be generated on the server side, for example, using the
$.session.language property to set the data-sap-ui-language parameter. Applications that have the
SAPUI5 <script> tag in a static HTML page can use this approach, as illustrated in the following example:

<script id="sap-ui-bootstrap"
type="text/javascript"
src="/sap/ui5/1/resources/sap-ui-core.js"
data-sap-ui-theme="sap_goldreflection"
data-sap-ui-libs="sap.ui.commons"
data-sap-ui-language="$UI5_LANGUAGE$">
</script>

The called XSJS page can be instructed to replace the $UI5_LANGUAGE$ parameter, for example, with the
value stored in $.session.language when loading the static HTML page.

Setting the Session Language with an AJAX Call

You can include an HTTP call in the static HTML page to fetch the correct language from the server using some
server-side JavaScript code, as illustrated in the following example:

<script>
var xmlHttp = new XMLHttpRequest();
xmlHttp.open( "GET", "getAcceptLanguage.xsjs", false );
xmlHttp.send( null );
window["sap-ui-config"] = {
"language" : xmlHttp.getResponseHeader("Content-Language")

SAP HANA Developer Guide

410 PUBLIC Writing Server-Side JavaScript Code
 }
</script>
<script id="sap-ui-bootstrap"
…
</script>

This approach requires an XSJS artifact (for example, getAcceptLanguage.xsjs) that responds to the AJAX
call with the requested language setting, as illustrated in the following example:

$.response.contentType = "text/plain";
$.response.headers.set("Content-Language", $.session.language);
$.response.setBody("");

7.7 Scheduling XS Jobs

Scheduled jobs define recurring tasks that run in the background. The JavaScript API $.jobs allows
developers to add and remove schedules from such jobs.

If you want to define a recurring task, one that runs at a scheduled interval, you can specify details of the job in
a .xsjob file. The time schedule is configured using cron-like syntax. You can use the job defined in
an .xsjob file to run an XS Javascript or SQLScript at regular intervals. To create and enable a recurring task
using the xsjob feature, you perform the following high-level tasks:

Note
The tasks required to set up a scheduled job in SAP HANA XS are performed by two distinct user roles: the
application developer and the SAP HANA administrator. In addition, to maintain details of an XS job in the
SAP HANA XS Administration Tool, the administrator user requires the privileges granted by the role
template sap.hana.xs.admin.roles::JobAdministrator.

Setting up Scheduled Jobs in SAP HANA XS.

Step Task User Role Tool

1 Create the function or script you want to run at Application developer Text editor
regular intervals

2 Create the job file .xsjob that defines details of Application developer Text editor
the recurring task

3 Maintain the corresponding runtime configuration SAP HANA administrator XS Job Dashboard
for the xsjob

4 Enable the job-scheduling feature in SAP HANA SAP HANA administrator XS Job Dashboard
XS

5 Check the job logs to ensure the job is running ac­ SAP HANA administrator XS Job Dashboard
cording to schedule.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 411
Related Information

The XSJob File [page 415]

XS Job File Keyword Options [page 417]

7.7.1 Tutorial: Schedule an XS Job

The xsjob file enables you to run a service (for example, an XS JavaScript or an SQLScript) at a scheduled
interval.

Prerequisites

● You have the privileges granted by the SAP HANA user role sap.hana.xs.admin.roles::JobAdministrator.
● You have the privileges granted by the SAP HANA user role
sap.hana.xs.admin.roles::HTTPDestAdministrator.

Note
This tutorial combines tasks that are typically performed by two different roles: the application developer
and the database administrator. The developer would not normally require the privileges granted to the
JobAdministrator user role, the sap.hana.xs.admin.roles::HTTPDestAdministrator user role, or the SAP HANA
administrator.

Context

In this tutorial, you learn how to schedule a job that triggers an XS JavaScript application that reads the latest
value of a share price from a public financial service available on the Internet. You also see how to check that
the XS job is working and running on schedule.

To do this, you create a root application package called yahoo, which contains the following artifacts:

/yahoo/
.xsapp // application descriptor
.xsaccess // application access file
yahoo.xsjob // job schedule definition
yahoo.xshttpdest // HTTP destination details
yahoo.xsjs // Script to run on schedule

SAP HANA Developer Guide

412 PUBLIC Writing Server-Side JavaScript Code
Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the application package structure that will contain the artifacts required to complete this tutorial:
a. From the context menu of the Content folder, choose Create Application.
b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter the package name yahoo and choose Create.
The system creates the index.html, .xsaccess, and .xsapp files.
d. Delete the index.html file.
3. Write the XS JavaScript code that you want to run at the interval defined in an XS job schedule:

a. From the context menu of the yahoo folder, choose New File , enter the file name yahoo.xsjs
(remember to use the .xsjs extension), and choose Create.
b. Add the application code.
The XS JavaScript code shown in the following example connects to a public financial service on the
Internet to check and download the latest prices for stocks and shares:

function readStock(input) {
var stock = input.stock;

var dest = $.net.http.readDestination("yahoo", "yahoo");

var client = new $.net.http.Client();
var req = new $.web.WebRequest($.net.http.GET, "/d/quotes.csv?f=a&s="
+ stock);
client.request(req, dest);
var response = client.getResponse();
var stockValue;
if(response.body)
stockValue = parseInt(response.body.asString(), 10);
var sql = "INSERT INTO stock_values VALUES (NOW(), ?)";
var conn = $.db.getConnection();
var pstmt = conn.prepareStatement(sql);
pstmt.setDouble(1, stockValue);
pstmt.execute();
conn.commit();
conn.close();
}

c. Save the file.

4. Create an HTTP destination file to provide access to the external service (via an outbound connection).
Since the financial service used in this tutorial is hosted on an external server, you need to create an HTTP
destination file, which provides details of the server, for example, the server name and the port to use for
HTTP access.
a. Create a file as described in step 3a but enter the file name yahoo.xshttpdest (remember to use
the .xshttpdest extension).
b. Add the following content:

host = "download.finance.yahoo.com";
port = 80;

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 413
 Note
If you use a proxy, set proxyType to http and enter your proxy host and port:

proxyType = http;
proxyHost = "<your_proxy_host>";
proxyPort = <your_proxy_port>;

c. Save the file.

5. Create the XS job file to define the details of the schedule at which the job runs.
The XS job file uses a cron-like syntax to define the schedule at which the XS JavaScript must run. This job
file triggers the script yahoo.xsjs on the 59th second of every minute and provides the name “SAP.DE”
as the parameter for the stock value to check.
a. Create a file as described in step 3a but enter the file name yahoo.xsjob (remember to use
the .xsjob extension).
b. Add the following code:

{
"description": "Read stock value",
"action": "yahoo:yahoo.xsjs::readStock",
"schedules": [
{
"description": "Read current stock value",
"xscron": "* * * * * * 59",
"parameter": {
"stock": "SAP.DE"
}
}
]
}

c. Save the file.

6. Maintain the XS job's runtime configuration.
You maintain the details of an XS job's runtime configuration in the XS Job Dashboard in the SAP HANA XS
Administration Tool.

a. Select the yahoo.xsjob file and choose (Maintain Details) in the toolbar.
The XS Job Dashboard opens.
b. Switch to the Configuration tab to maintain the details of the XS job:
○ User
The user account in which the job runs, for example, SYSTEM.
○ Password
The password required for user, whose account is used to run the job.
○ Locale
The language encoding required for the locale in which the job runs, for example, en_US.
○ Start/Stop time
An optional value to set the period of time during which the job runs. Enter the values using the
syntax used for the SAP HANA data type LocalDate and LocalTime, for example, 2014-11-05
00:30:00 (thirty minutes past midnight on the 5th of November 2014).
○ Active
Enable or disable the job schedule
c. Save the job.

SAP HANA Developer Guide

414 PUBLIC Writing Server-Side JavaScript Code
 The changes to the job schedule are activated.
7. Enable the job-scheduling feature in SAP HANA XS.
This step requires the permissions granted to the SAP HANA administrator.

Note
It is not possible to enable the scheduler for more than one host in a distributed SAP HANA XS
landscape.

In the XS Job Dashboard set the Scheduler Enabled toggle button to YES.
Toggling the setting for the Scheduler Enabled button changes the value set for the SAP HANA
configuration variable xsengine.ini scheduler enabled , which is set in the Configuration tab of the
SAP HANA studio's Administration perspective. If the scheduler section is not already there, create it and
add the new parameter enabled, and assign the value true.
8. Check the job logs to ensure the XS job is active and running according to the defined schedule.
You can view the xsjob logs in the XS Job Dashboard tab of the SAP HANA XS Administration Tool. If there
is a problem and the XS job fails or does not run at the expected time, the information about why it failed
and when is displayed in the xsjob logs.

7.7.1.1 The XS Job File

The .xsjob file defines the details of a task that you want to run (for example, an XS JavaScript or an
SQLScript) at a scheduled interval.

The XS job file uses a cron-like syntax to define the schedule at which the service defined in an XS JavaScript
or SQLScript must run, as you can see in the following example, which runs the specified job (the stock-price
checking service yahoo.xsjs) on the 59th second minute of every minute.

{
"description": "Read stock value",
"action": "yahoo:yahoo.xsjs::readStock",
"schedules": [
{
"description": "Read current stock value",
"xscron": "* * * * * * 59",
"parameter": {
"stock": "SAP.DE"
}
}
]
}

When defining the job schedule in the xsjob file, pay particular attention to the entries for the following
keywords:

● action
Text string used to specify the path to the function to be called as part of the job.

"action": "<package_path>:<XSJS_Service>.xsjs::<FunctionName>",

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 415
 Note
You can also call SQLScripts using the action keyword.

● description
Text string used to provide context when the XSjob file is displayed in the SAP HANA XS Administration
tool.
● xscron
The schedule for the specified task (defined in the “action” keyword); the schedule is defined using
cron-like syntax.
● parameter
A value to be used during the action operation. In this example, the parameter is the name of the stock
SAP.DE provided as an input for the parameter (stock) defined in the readStock function triggered by
the xsjob action. You can add as many parameters as you like as long as they are mapped to a parameter
in the function itself.

The following examples illustrate how to define an xscron entry including how to use expressions in the
various xscron entries (day, month, hour, minutes,...):

● 2013 * * fri 12 0 0
Every Friday of 2013 at 12:00 hours
● * * 3:-2 * 12:14 0 0
Every hour between 12:00 and 14:00 hours on every day of the month between the third day of the month
and the second-last day.

Tip
In the day field, third from the left, you can use a negative value to count days backwards from the end of
the month. For example, * * -3 * 9 0 0 means: three days from the end of every month at 09:00.

● * * * * * */5 *
Every five minutes (*/5) and at any point (*) within the specified minute.

Note
Using the asterisk (*) as a wild card in the seconds field can lead to some unexpected consequences, if
the scheduled job takes less than 59 seconds to complete; namely, the scheduled job restarts on
completion. If the scheduled job is very short (for example, 10 seconds long), it restarts repeatedly until
the specified minute ends.

To prevent short-running jobs from restarting on completion, schedule the job to start at a specific second
in the minute. For example, * * * * * */5 20 indicates that the scheduled job should run every five
minutes and, in addition, at the 20th second in the specified minute.
● * * * -1.sun 9 0 0
Every last Sunday of a month at 09:00 hours

Related Information

XS Job File Keywords [page 417]

SAP HANA Developer Guide

416 PUBLIC Writing Server-Side JavaScript Code
7.7.1.2 XS Job File Keyword Options

The XS job file .xsjob uses a number of keywords to define the job that must be run at a scheduled interval.

Example
The XS Job (.xsjob) File

{
"description": "Read stock value",
"action": "yahoo:yahoo.xsjs::readStock",
"schedules": [
{
"description": "Read current stock value",
"signature_version": 1,
"xscron": "* * * * * * 59",
"parameter": {
"stock": "SAP.DE"
}
}
]
}

description

{
"description": "Read stock value",
}

The description keyword enables you define a text string used to provide context when the XS job is displayed
for maintenance in the SAP HANA XS Administration Tool. The text string is used to populate the Description
field in the SCHEDULED JOB tab.

action

{
"action": "myapps.finance.yahoo:yahoo.xsjs::readStock",
}

The action keyword enables you to define the function to run as part of the XS job, for example, an XS
JavaScript or an SQLScript. The following syntax is required: “action” :
“<package.path>:<XSJS_Service>.xsjs::<functionName>”.

Note
If you want to use the action to call an SQLScript, replace the name of the XSJS service in the example, with
the corresponding SQLScript name.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 417
schedules

{
"schedules": [
{
"description": "Read current stock value",
"xscron": "* * * * * * 59",
"parameter": {
"stock": "SAP.DE"
}
}
]
}

The schedules keyword enables you define the details of the XS job you want to run. Use the following
additional keywords to provide the required information:

● description (optional)
Short text string to provide context
● xscron
Uses cron-like syntax to define the schedule at which the job runs
● parameter (optional)
Defines any values to be used as input parameters by the (XSJS or SQLScript) function called as part of
the job

signature_version

{
"signature_version": 1,
}

The signature_version keyword enables you manage the version “signature” of an XS job. You change the XS job
version if, for example, the parameter signature of the job action changes; that is, an XS job accepts more (or
less) parameters, or the types of parameters differ compared with a previous version of an XS job. On
activation in the SAP HANA Repository, the signature of an XS job is compared to the previous one and, if the
job’s signature has changed, any job schedules created at runtime will be deactivated.

Note
The default value for signature_version is 0 (zero).

Deactivation of any associated runtime job schedules prevents the schedules from silently failing (no
information provided) and enables you to adjust the parameters and reactivate the job schedules as required,
for example, using the enhanced XS JS API for schedules. Schedules defined in a design-time XS Job artifact
are replaced with the schedules defined in the new version of the XS job artifact.

Tip
Minor numbers (for example, 1.2) are not allowed; the job scheduler interprets “1.2” as “12”.

SAP HANA Developer Guide

418 PUBLIC Writing Server-Side JavaScript Code
xscron

{
"schedules": [
{
"description": "Read current stock value",
"xscron": "* * * * * * 59",
"parameter": {
"stock": "SAP.DE"
}
}
]
}

The xscron keyword is used in combination with the schedules keyword. The xscron keyword enables you to
define the schedule at which the job runs. As the name suggests, the xscron keyword requires a cron-like
syntax.

The following table explains the order of the fields (*) used in the “xscron” entry of the .xsjob file and lists
the permitted value in each field.

xscron Syntax in the XS Job File

xscron Field (* from left to right) Meaning and Permitted Value

Year 4-digit, for example, 2013

Month 1 to 12

Day -31 to 31

DayofWeek mon,tue,wed,thu,fri,sat,sun

Hour 0 to 23

Minute 0 to 59

Second 0 to 59

Note
Using the asterisk (*) as a wild card in the seconds field can lead to some unexpected consequences, if the
scheduled job takes less than 59 seconds to complete; namely, the scheduled job restarts on completion. If
the scheduled job is very short (for example,10 seconds long), it restarts repeatedly until the specified
minute ends.

To prevent short-running jobs from restarting on completion, schedule the job to start at a specific second in
the minute. For example, * * * * * */5 20 indicates that the scheduled job should run every five minutes
and, in addition, at the 20th second in the specified minute. The job starts at precisely 20 seconds into the
specified minute and runs only once.

The following table illustrates the syntax allowed to define expressions in the “xscron” entry of the .xsjob
file.

Expression Where used... Value

* Anywhere Any value

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 419
Expression Where used... Value

*/a Anywhere Any a-th value

a:b Anywhere Values in range a to b

a:b/c Anywhere Every c-th value between a and b

a.y DayOfWeek On the a-th occurrence of the weekday

y (a = -5 to 5)

a,b,c Anywhere a or b or c

parameter

{
"schedules": [
{
"description": "Read current stock value",
"xscron": "* * * * * * 59",
"parameter": {
"stock": "SAP.DE",
"share": "BMW.DE"
}
}
]
}

The optional parameter keyword is used in combination with the schedules keyword. The parameter keyword
defines values to be used as input parameters by the XSJS function called as part of the job. You can list as
many parameters as you like, separated by a comma (,) and using the JSON-compliant syntax quotations (“”).

7.7.2 Add or Delete a Job Schedule during Runtime

The $.jobs application programming interface (API) enables you to manipulate the schedules for an XS job at
runtime.

Context

You can use the $.jobs.JobSchedules API to add a schedule to (or delete a schedule from) a job defined in
an .xsjob file at runtime.

Note
Schedules added at runtime are deleted when the .xsjob file is redeployed.

SAP HANA Developer Guide

420 PUBLIC Writing Server-Side JavaScript Code
Procedure

1. Create an XS job file using the .xsjob syntax.

Note
If you have already created this XS job file, for example, in another tutorial, you can skip this step.

Create a file called yahoo.xsjob and add the following code:

{
"description": "Read stock value",
"action": "yahoo:yahoo.xsjs::readStock",
"schedules": [
{
"description": "Read current stock value",
"xscron": "* * * * * * 59",
"parameter": {
"stock": "SAP.DE"
}
}
]
}

Save and activate the changes in the SAP HANA Repository.

Note
Saving a file in a shared project automatically commits the saved version of the file to the repository, To
explicitly commit a file to the repository, right-click the file (or the project containing the file) and choose
Team Commit from the context-sensitive popup menu.

2. Create the XS JavaScript (.xsjs) file you want to use to define the automatic scheduling of a job at
runtime.
Name the file schedule.xsjs.
3. Use the $.jobs JavaScript API to add or delete a schedule to a job at runtime.
The following example schedule.xsjs adds a new schedule at runtime for the XS job defined in
yahoo.xsjob, but uses the parameter keyword to change the name of the stock price to be checked.

var myjob = new $.jobs.Job({uri:"yahoo.xsjob"});

var id = myjob.schedules.add({
description: "Query another stock",
xscron: "* * * * * * * */10",
parameter: {
stock: "APC.DE"
}
});
// delete a job schedule
// myjob.schedules.delete( {id: id } );

4. Save and activate the changes in the SAP HANA Repository.

5. Call the XS JavaScript service schedule.xsjs to add the new job schedule at runtime.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 421
Related Information

SAP HANA XS JavaScript Reference

XS Job File Keyword Options [page 417]

7.8 Tracing Server-Side JavaScript

The SAP HANA XS server-side JavaScript API provides tracing functions that enable your application to write
predefined messages in the form of application-specific trace output in the xsengine trace files
(xsengine*.trc) according to the trace level you specify, for example, “info”(information) or “error”.

If you use the server-side JavaScript API to enable your application to write trace output, you can choose from
the following trace levels:

● debug
● info
● warning
● error
● fatal

For example, to enable debug-level tracing for your JavaScript application, include the following code:

$.trace.debug("request path: " + $.request.path);

7.8.1 Tutorial: Trace a Server-Side JavaScript Application

In this tutorial, you use the tracing functions provided by the server-side JavaScript API for SAP HANA XS to
enable tracing in a JavaScript application. The application-specific trace messages are written into a trace file,
according to the trace level you specify, for example, "debug", "info", "warning", "error", or "fatal".

Prerequisites

● You have the TRACE ADMIN system privilege (required to set trace levels in the trace tool).
● You have the privileges granted by the roles sap.hana.ide.roles::EditorDeveloper and
sap.hana.ide.roles::TraceViewer; both roles are included in the parent role sap.hana.ide.roles::Developer.

SAP HANA Developer Guide

422 PUBLIC Writing Server-Side JavaScript Code
Context

You can view trace files and assign trace levels to applications using the Trace component of the SAP HANA
Web-based Development Workbench. The Web-based trace tool is available on the SAP HANA XS Web server
at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/trace

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create a new application:
a. From the context menu of the Content folder, choose Create Application.
b. Choose the HANA XS Hello World template.
c. Enter a package name, for example, demo.helloxs, and choose Create.
3. Add logic code to the new application:
a. In the demo.helloxs folder, open the file logic.xsjs.
b. At line 5 in the logic.xsjs file, insert a new line with the following syntax:

function getUsername(){
var username = $.session.getUsername();
return username;
}
$.trace.debug("Let's say hello to my demo");
var result = "Hello World from User " + getUsername();
$.response.setBody(result);

c. Save the logic.xsjs file.

4. Navigate to the trace tool by choosing (Navigation Links) Trace .

5. Set the trace level:

a. Choose (Configuration) in the toolbar.

b. In the Application Trace panel, choose (Edit Configuration).

c. In theTrace Level for Applications dialog box, filter by the name of the application you want to trace.
The application name is the location (package) of the .xsapp file associated with the application you
are tracing, in this case demo.helloxs.
d. Set the system trace level to Debug and choose OK to activate the trace level changes.
6. Run the application from a Web browser:

a. In the Editor tool, select the indexUI5.html file in the demo.helloxs package and choose (Run)
in the toolbar.
b. In the Web browser, choose Call Backend.
7. View the application trace file.
In the trace tool, open the newest XS engine trace file, which you can find in the XS Engine folder.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 423
7.9 Debugging Server-Side JavaScript

SAP HANA XS provides an integrated debugger to enable you to debug the XS JavaScript code that you write.

Prerequisites

To use the debugging tools and features, set up your debugging environment as follows:

● Enable debugging on the system level

1. Start the SAP HANA studio and open the Administration perspective.
2. On the Configuration tab, add a section called xsengine.ini debugger (if it does not exist) and add
(or set) the following parameter: enabled=true

Tip
To enable the display of more helpful and verbose information for HTTP 500 exceptions on the SAP
HANA XS Web server, add the parameter developer_mode to the xsengine.ini httpserver
section and set it to true.

● Assign the debugger role to your user

SAP HANA XS provides the dedicated debugger role sap.hana.xs.debugger::Debugger. This role must be
assigned to any user who wants to start a debugging session for server-side JavaScript in SAP HANA XS.

Note
By default, other users do not have the permissions required to access your XS JavaScript debugging
sessions. However, you can grant a user global access to any of your debug sessions or grant access to a
debug session that is flagged with a specified token. You can also restrict access to a debug session to a
specified period of time.

Related Information

Tutorial: Create and Debug a Server-side JavaScript Application [page 425]

XSJS Debugger [page 427]
XSJS Debugger Role [page 428]
Debug Session Access [page 429]

SAP HANA Developer Guide

424 PUBLIC Writing Server-Side JavaScript Code
7.9.1 Tutorial: Create and Debug a Server-side JavaScript
Application

In this tutorial, you use the SAP HANA Web-based Development Workbench Editor to create and debug a
server-side JavaScript application. The application displays a browser window where you can enter two values
in URL parameters and display the results immediately in the browser window.

Prerequisites

● You have the privileges granted by the role sap.hana.ide.roles::EditorDeveloper; this role is included in the
parent role sap.hana.ide.roles::Developer.
● You have been assigned the user role sap.hana.xs.debugger::Debugger.
● Your SAP HANA administrator has enabled debugging in the SAP HANA system.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. From the context menu of the Content folder, choose Create Application.
Create the application in a package that does not already contain any application descriptors (for
example, .xsaccess and .xsapp files).
3. Choose the Empty application (with XSAccess and XSApp) template.
4. Enter a package name, for example, demo.first, and choose Create.
The system creates the index.html, .xsaccess, and .xsapp files, and automatically opens a dummy
index.html file.
5. To create a server-side JavaScript demo, do the following:
a. Delete the automatically created index.html file.
b. From the context menu of the demo.first folder, choose New File .
c. Enter a file name with the .xsjs extension, for example, debug.xsjs, and choose Create.
d. Enter the following server-side JavaScript code into the file and save it:

function doMultiply(var1, var2) {

return var1 + " X " + var2 + " = " + var1 * var2;
}
function doAdd(var1, var2) {
return var1 + " + " + var2 + " = " + (parseInt(var1, 10) +
parseInt(var2, 10));
}
$.response.contentType = "application/json";
$.response.status = 200;
$.response.contentType = "text/plain";
try {
var variable1 = parseInt($.request.parameters.get("var1"),10);
var variable2 = parseInt($.request.parameters.get("var2"), 10);

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 425
 switch ($.request.parameters.get("mode")) {
case "multiply":
$.response.setBody((doMultiply(variable1, variable2)));
break;
case "add":
$.response.setBody((doAdd(variable1, variable2)));
break;
default:
$.response.setBody(("Service not supported: " +
$.request.parameters.get("mode")));
break;
}
} catch (err) {
$.response.setBody("Failed to execute action: " + err.toString());
}

6. Choose (Run) in the toolbar.

A browser window opens.
7. Edit the URL parameters as follows and press Enter :
a. For multiply, enter <your_file_name>.xsjs?mode=multiply&var1=10&var2=200.
b. For addition, enter <your_file_name>.xsjs?mode=add&var1=10&var2=200.
The system computes the result and displays it in the browser window.
8. Set a breakpoint in front of the code line in the doAdd function by simply clicking the line number and then
repeat step 7b using, for example: <your_file_name>.xsjs?mode=add&var1=10&var2=200
During program execution, the Debugger panel opens in the editor as soon as a breakpoint is encountered.
You can see that the XSJS debugger has stopped at the breakpoint you defined and that the values of
<var1> and <var2> are shown in the Watch Area pane.
9. Evaluate an expression.

a. Choose (Evaluate expression) on the Debugger toolbar.

b. In the Evaluate expression dialog box, enter the expression parseInt(var1)+parseInt(var2) and
choose Evaluate.
c. Check that the result is displayed correctly on the right.
10. Change the value assigned to a variable.
a. In the same Evaluate expression dialog box, change the value assigned to the variable <var1>, for
example, to var1=100, and choose Evaluate.

b. Close the dialog box and choose (Resume (F10)) to finish the debugger session.
c. Switch to the application window to confirm that the change you made is reflected in the displayed
result.

Related Information

XSJS Debugger [page 427]

SAP HANA Developer Guide

426 PUBLIC Writing Server-Side JavaScript Code
7.9.2 XSJS Debugger

The SAP HANA Web-based Development Workbench provides an integrated debugger, which makes available
the tools you need to debug server-side JavaScript code.

The debug tools allow you to perform standard debugging tasks, such as adding breakpoints to the code and
starting, stepping through, and resuming code execution. You can also inspect variables and check the validity
of expressions.

Breakpoints

You set breakpoints in the source code by clicking the line number of the statement you want to stop at. You
can set as many breakpoints as you want. A red arrow in the line number column shows each breakpoint that
has been set:

Debug mode started:

Simply click the red arrow again to remove the breakpoint.

In the Debugger panel, the Breakpoints pane displays a list of the breakpoints set in the source file you are
currently debugging. You can remove breakpoints by deleting them from the list.

Code Execution

To run an application in debug mode, set a breakpoint on the line you want to start debugging from and then
choose (Run). The debugger stops at the defined breakpoint and the Debugger panel opens to the right of
the source code.

A blue arrow inside the red arrow tag shows that a breakpoint has been reached:

Note
In the source code, a blue arrow in the line number column shows the next code line that will be executed.

You can execute the script using the buttons located in the toolbar at the top of the Debugger panel:

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 427
 Continues execution to the next breakpoint
(Resume)

Steps through the code line-by-line and, whenever a function is called, steps into the body of
(Step in)
that function

Steps through the code line-by-line but if a function is called it does not step into the body of
(Step over)
that function

Leaves the current function

(Step out)

Callstack

In the Debugger panel, the Callstack pane shows the line number of the current code line where execution has
been suspended. When stepping through the code, the call stack allows you to see the path that is taken when
the XS JavaScript file is executed. If a function is called, an entry is added to the top of the call stack and
removed when the function has finished. The debugger then continues from the position given at the top of the
stack.

Variables and Expressions

The Watch Area pane allows you to inspect the current runtime values of existing variables when execution of
the code is suspended at breakpoints or is being stepped through. You can drill down within the tree to view the
values of sub-elements.

In the expression evaluation dialog box (open the dialog box by choosing (Evaluate expression) on the
Debugger toolbar), you can write your own statements to check the validity of expressions and manipulate
variable values.

7.9.3 XSJS Debugger Role

The JavaScript debugger included with SAP HANA Extended Application Services (SAP HANA XS) requires
user authentication to start a debug session. SAP HANA XS includes a dedicated debugger role, which defines
the permissions needed by a developer who wants to debug server-side JavaScript code.

Debugging application code is an essential part of the application-development process. SAP HANA Extended
Application Services (SAP HANA XS) provides integrated debugger functionality and a dedicated debugger role
that must be assigned to any developer who wants to debug XS JavaScript. The debugging role is named
sap.hana.xs.debugger::Debugger and can be assigned to a user with the standard role-assignment feature
included in the SAP HANA Web-based Development Workbench security tool.

Since developers primarily need to debug their own HTTP calls, the following limitations apply to a debug
session:

SAP HANA Developer Guide

428 PUBLIC Writing Server-Side JavaScript Code
● Only authenticated users can start a debug session, for example, by providing a user name and password
when logging in to a debug session.
● Users can debug their own sessions.
● A user can debug any session to which access has been explicitly granted, for example, by the owner of the
session.

Note
It is also possible to use SSL for debugging. If SSL is configured, the server redirects the Web-socket
connect call to the corresponding SSL (secure HTTP) URL, for example, if sent by plain HTTP.

Related Information

Debug Session Access [page 429]

7.9.4 Debug Session Access

You can grant other developers access to the debug sessions you use for debugging server-side JavaScript on
SAP HANA XS.

By default, other users are not allowed to access your XSJS debugging sessions. However, SAP HANA XS
provides a tool that enables you to grant access to your debugging sessions to other users, too.

Note
You can grant a user global access to any of your sessions or grant access to a session that is flagged with a
specified token. You can also restrict access to a debug session to a specified period of time.

The XS Debugging tool is available on the SAP HANA XS Web server at the following URL:
<SAPHANAWebServer>80<SAPHANAinstance>/sap/hana/xs/debugger/.

When you are grant access to your debugging session, the following options are available:

● User Name
The name of the database user who requires access to your debug session
● Privilege Expires
The point in time that marks the end of the period for which access to one or more debug sessions is
allowed.
● grant debug permission for all sessions
You can grant a user global access to any of your debug sessions.

Restriction
The user you grant access to must already be registered and authenticated in the SAP HANA database.

● grant debug permission for this session only

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 429
 You can grant access to a debug session that is flagged with a specific token:

Restriction
Unauthenticated users must use the token-based option.

The following rules apply to access to debug sessions flagged with a token:
○ The session used for granting access to the debug sessions is flagged automatically.
○ The session token is distributed by means of a session cookie; the cookie is inherited by any session
created with the current browser session.
● Session Name
A freely definable name that can be used to distinguish your debug session in the context of multiple
sessions.

7.10 Testing XS JavaScript Applications

SAP HANA provides a test framework called XSUnit that enables you to set up automated tests for SAP HANA
XS applications.

The test framework SAP HANA XSUnit (XSUnit) is a custom version of the open-source JavaScript test
framework, Jasmine, adapted for use with SAP HANA XS. You can use the XSUnit test framework to automate
the tests that you want to run for SAP HANA XS applications, for example, to test the following elements:

● Server side JavaScript code

● SQLScript code (stored procedures and views)
● Modeled calculation views

Prerequisites

To use the tools and features provided with the XSUnit test framework, set up your test environment as follows:

1. Install the HANA_TEST_TOOLS delivery unit

The XSUnit test framework is included in the HANA_TEST_TOOLS delivery unit, which you need to install
manually, for example, using the SAP HANA studio or the SAP HANA Application Lifecycle Management
tool. Once installed, the tools are available in the sap.hana.testtools package.

Note
To import a delivery unit into an SAP HANA system, you requires the REPO.IMPORT privilege, which is
normally granted only to the system administrator.

2. Assign tester roles

To access and use the tools provided with the SAP HANA XS test framework (XSUnit), you require
dedicated roles.
As the SAP HANA system administrator, you need to assign test users the roles required to work with the
SAP HANA XS test framework and SAP HANA Web-based Development Workbench.

SAP HANA Developer Guide

430 PUBLIC Writing Server-Side JavaScript Code
 Role Name Description

sap.hana.testtools.common::TestEx­ Enables you to view the persisted test results produced by the XSUnit test
ecute framework and to execute the examples included in the demonstration pack­
age (sap.hana.testtools.demo).

sap.hana.xs.debugger::Debugger Enables you to debug your server side JavaScript (test) code

sap.hana.xs.ide.roles::Developer Enables you to view source files in the SAP HANA Web-based Development
Workbench

3. Maintain the test schema (optional)

If you write XSUnit tests that are designed to test database content, you require a test schema in which you
create test tables during your test execution and fill the tables with test data. To avoid conflicts when
different users run the same test at the same time, it is recommended that individual developers place test
tables in their corresponding user schema.

Note
You must ensure that _SYS_REPO has select permission on the schema where the tables are located
(for example, either your user schema or the test schema).

grant select on schema MY_TEST_SCHEMA to _SYS_REPO with grant option;

Related Information

Automated Tests with XSUnit in SAP HANA [page 431]

XSUnit Test Examples [page 439]
SAP HANA XSUnit JavaScript API Reference

7.10.1 Automated Tests with XSUnit in SAP HANA

XSUnit is an integrated test environment that enables you to set up automatic tests for SAP HANA XS
applications.

People developing applications in the context of the SAP HANA database need to understand how to
implement a test-automation strategy. Especially for new applications which are designed to work exclusively
with SAP HANA, it is a good idea to consider the adoption of best practices and tools.

If you want to develop content that is designed to run specifically in SAP HANA, it is strongly recommended to
use the XSUnit test framework that is integrated in SAP HANA XS; this is the only way to transport your test
code with your SAP HANA content. The XSUnit tools are based on a Java Script unit test framework that uses
Jasmine as the underlying test library.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 431
Test Isolation and Simulation

To write self-contained unit tests that are executable in any system, you have to test the various SAP HANA
objects in isolation. For example, an SAP HANA view typically has dependencies to other views or to database
tables; these dependencies pass data to the view that is being tested and must not be controlled or overwritten
by the test. For this reason, you need to be able to simulate dependencies on the tested view. XSUnit includes a
test-isolation tool that provides this functionality; it allows you to copy a table for testing purposes.

Note
Although you cannot copy a view for testing purposes, you can create a table that acts like a view.

All (or specific) dependencies on any tables or views are replaced by references to temporary tables, which can
be created, controlled, and populated with values provided by the automated test.

Test Data

Preparing and organizing test data is an important part of the process of testing SAP HANA content such as
views and procedures; specific data constellations are required that have to be stable in order to produce
reliable regression tests. In addition, test-isolation tools help reduce the scope of a test by enabling you to test
a view without worrying about dependent tables and views. Limiting the scope of a test also helps to reduces
the amount of data which needs to be prepared for the test.

Related Information

XSUnit Test Examples [page 439]

7.10.2 Application Development Testing Roles

Dedicated roles enable developers to access and use the tools provided with the SAP HANA XS test framework
(XSUnit).

To grant access to the SAP HANA XS test framework that enables developers to set up automatic testing for
SAP HANA applications, the SAP HANA system admininstrator must ensure that the appropriate roles are
assigned. The following table lists the roles that are available; one (or more) of the listed roles must be assigned
to the application developers who want to use the XSUnit testing tools.

Default Developer Testing Roles

Role Name Description

sap.hana.testtools.common::TestExe­ Enables you to view the persisted test results produced by the XSUnit test frame­
cute work and to execute the examples included in the demonstration package
(sap.hana.testtools.demo).

SAP HANA Developer Guide

432 PUBLIC Writing Server-Side JavaScript Code
 Role Name Description

sap.hana.xs.debugger::Debugger Enables you to debug your server side JavaScript (test-)code

sap.hana.xs.ide.roles::Developer Enables you to view source files in the SAP HANA Web-based Work Bench (Web
IDE)

7.10.3 Test an SAP HANA XS Application with XSUnit

Use the XSUnit tools to set up automated testing of your applications in SAP HANA XS.

Prerequisites

● You have installed the HANA_TEST_TOOLS delivery unit (DU).

● You have been assigned the role sap.hana.testtools.common::TestExecute.

Context

If you want to develop content that is designed to run specifically with SAP HANA, you can use the XSUnit tools
that are integrated in SAP HANA XS. The XSUnit tools are based on a JavaScript unit test framework that uses
Jasmine as the underlying test library.

Procedure

1. Create a package to contain the test code.

2. Create an application descriptor (.xsapp file).
The XS library file you'll test can only be loaded if there is an application descriptor (.xsapp file) defined
within the package hierarchy. If your tests are not part of your application package hierarchy, we
recommend that you create a .xsapp file in the package that contains the tests.

a. Select the test package and from the context menu choose New File .
b. Enter the file name .xsapp and choose Create.
c. Select the .xsapp file and from the context menu choose Activate.
3. Create an XSUnit test.
XSUnit test files are XS library files (files with the .xsjslib file extension). XS Unit test file names must
end with Test.xsjslib (for example, myExampleTest.xsjslib) or .xsunit.xsjslib (for example,
myExample.xsunit.xsjslib).

a. Select the test package and from the context menu choose New File .
b. Enter a file name, for example, MyFirstTest.xsjslib, and choose Create.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 433
 c. Add the following content to the new XS library test file MyFirstTest.xsjslib.

/*global jasmine, describe, beforeOnce, beforeEach, it, xit, expect*/

describe("My First Test Suite using Jasmine", function() {

it('should show an assertion that passes', function() {

expect(1).toBe(1);
});
it("should show an negative assertion", function() {
expect(true).not.toBe(false);
});
it("should throw an expected error", function() {
expect(function() {
throw new Error("expected error");
}).toThrowError("expected error");
});
//xit = this test case is excluded
xit("should show an assertion that fails", function() {
expect(1).toBe(2);
});
});

d. Save the test file.

4. Execute the XSUnit test.

Select the MyFirstTest.xsjslib file and choose Invoke Tests in the context menu or (Run XS Unit
Test Suite) in the toolbar.
The integrated XS Unit Test Runner opens in a panel on the right and shows the progress of the test run.
Note that depending on your tests this may take some time.
5. Inspect the test results.
The test results are displayed in the form of a tree with a node for each of the following:
○ Each "describe" test specification
○ Each "it" test case
○ Each failed test case: an error message together with the stack trace
In the XS Unit Test Runner panel, choose from the following options:

○ Navigate to a code line: For failed test cases, drill down to the @ node below the error message, and
from the context menu choose Open code.
○ Generate a test report: Click Create test report to show an HTML report of the XS Unit test run in a
separate browser tab.
○ Rerun tests on save: While the XS Unit test runner is open, the tests are rerun each time the file is
saved, irrespective of which file is open in the editor.
6. Inspect the code line coverage.
To rerun the tests and collect code line coverage information, select the Track Code Coverage option.
In addition to the test results, this gives you an overview of all files affected by the test run. For each file, the
number of lines covered is shown in relation to the overall number of lines. To see exactly which code lines
were covered in a specific file, choose Show covered lines in the context menu of that file. The lines covered
at least once are shown in yellow in the editor.

SAP HANA Developer Guide

434 PUBLIC Writing Server-Side JavaScript Code
7.10.3.1 XSUnit's Enhanced Jasmine Syntax

The XSUnit test framework is a custom version of the JavaScript test framework Jasmine adapted to suit SAP
HANA XS.

A test specifications begin with a call to the global Jasmine function describe. The describe functions
define suites that enable you to group together related test suites and specifications. Test-suite specifications
are defined by calling the global Jasmine function it. You can group several test suites in one test file. The
following code snippet shows one test suite (introduced by the function “describe”) and two test
specifications, indicated by the function “it”.

/*jslint undef:true */
describe('testSuiteDescription', function() {
beforeOnce(function() {
// beforeOnce function is called once for all specifications
});
beforeEach(function() {
// beforeEach function is called before each specification
});
it('testSpecDescription', function() {
expect(1).toEqual(1);
});
it('anotherTestSpecDescription', function() {
expect(1).not.toEqual(0);
});
});

To enable a test suite to remove any duplicate setup and teardown code, Jasmine provides the global functions
beforeEach and afterEach. As the name implies the beforeEach function is executed before each
specification in the enclosing suite and all sub-suites; the afterEach function is called after each
specification. Similarly, the special methods beforeOnce and afterOnce are called once per test suite.

● beforeOnce
Executed once before all specifications of the test suite
● afterOnce
Executed once after all specifications of the test suite

Database Connection Setup

The XSUnit framework provides a managed database connection called jasmine.dbConnection, which is
globally available. You can use it in the following scenarios:

● Directly (in the function “it”)

● In the functions “beforeEach” and “afterEach”
● In other functions defined in your test libraries
● In imported libraries (if you have moved test code to external libraries)

One obvious advantage of this is that you no longer have to pass the database connection as a parameter or
define it as a global variable. The jasmine.dbConnection is opened automatically and rolled back (and
closed). However, if you want to persist your data, you have to commit() jasmine.dbConnection manually.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 435
 XSUnit TestRunner Tool Flow Chart

7.10.3.2 XSUnit Test Tools Syntax

Example syntax for the functions, assertions, and parameters required by the SAP HANA XSUnit test tools.

The following code example lists the most commonly used functions and assertions used in the XSUnit
syntax.For more information about the assertions used, for example, toBe, toBeTruthy, or toBeFalsy, see
Assertions.

/*global jasmine, describe, beforeOnce, beforeEach, it, xit, expect*/

describe("My First Test Suite using Jasmine", function() {
beforeOnce(function() {
// beforeOnce is called only one time for all specs
});
beforeEach(function() {
// beforeEach is called before each specs
});
// it = test case specification it("should show an assertion that passes",
function() {
var array = [{foo: 'bar', baz: 'quux'}, {bar: 'foo', quux: 'baz'}];
expect(1).toBeTruthy();
expect(12).toBe(jasmine.any(Number));
expect(array).toContain(jasmine.objectContaining({foo: 'bar' }));
});
it("should show an negative assertion", function() {
expect(true).not.toBe(false);

SAP HANA Developer Guide

436 PUBLIC Writing Server-Side JavaScript Code
 });
it("should throw an expected error", function() {
expect(function() {
throw new Error("expected error");
}).toThrowError("expected error");
});
// xit = this test case is excluded
xit("should show an assertion that fails", function() {
expect(1).toBe(2);
});
});

XSUnit Assertions and Parameters

The following code example lists the most commonly used assertions, shows the required syntax, and the
expected parameters.

expect(actual).toBe(expected);
expect(actual).toBeFalsy();
expect(actual).toBeTruthy()
expect(actual).toEqual(expected);
expect(actualArray).toContain(expectedItem);
expect(actual).toBeNull();
expect(actualNumber).toBeCloseTo(expectedNumber, precision);
expect(actual).toBeDefined();
expect(actual).toBeUndefined();
expect(actualString).toMatch(regExpression);
expect(actualFunction).toThrowError(expectedErrorMessage);
expect(actualFunction).toThrowError(expectedErrorType, expectedErrorMessage);
expect(actualTableDataSet).toMatchData(expected, keyFields);
expect(actual).toBeLessThan(expected);
expect(actual).toBeGreaterThan(expected);

7.10.3.3 XSUnit Test Run Options

The XSUnit tool suite includes a generic tool that you can use to run tests.

You can start the XSUnit test-running tool (TestRunner.xsjs) by entering the following URL in a Web
Browser:

http://<hostname>:80<HANAinstancenumber>/sap/hana/testtools/unit/jasminexs/
TestRunner.xsjs?<parameters>

The following table lists the parameters that you can use to control the behavior of test-runner tool. If you
execute the test runner without specifying the pattern parameter, only the tests in *Test.xsjslib files are
discovered (and run) within the package hierarchy.

Note
You can specifiy mutliple parameters by separating each parameter=value pair with the ampersand
character (&), for example:coverage=true&exclude=sap.hana.tests

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 437
TestRunner.xsjs Parameters
Name Mandatory Description

package yes Package that acts as starting point for discovering the tests. If not otherwise
specified by parameter “pattern” all .xsjslib files in this package and its sub-pack­
ages conforming to the naming pattern “*Test” will be assumed to contain tests
and will be executed.

package=sap.hana.testtools.demo

pattern no Naming pattern that identifies the .xsjslib files that contain the tests. If not speci­
fied, the pattern “*Test” is applied. You can use question mark (?) and asterisk (*)
as wildcards to match a single or multiple arbitrary characters, respectively. To
match all “Suite.xsjslib” files, use the following code:

pattern=Suite

format no Specifies the output format the test runner uses to report test results. By default,
the results will be reported as HTML document. This parameter has no effect if a
custom reporter is provided via parameter “reporter”. To display outputs results
using the JSON format, use the following code:

format=json

reporter no Complete path to module that provides an implementation of the Jasmine re­
porter interface. With this parameter a custom reporter can be passed to publish
the test results in an application specific format . To specify the reporter inter­
face, use the following code:

reporter=sap.hana.testtools.unit.jasminexs.reporter.db
.dbReporter

Note
format=db produces the same result

tags no Comma-separated list of tags which is used to define the tests to be executed.

tags=integration,long_running

profile no Name of a "profile" defined in the test which filters the tests to be executed on the
basis of tags.

profile=end2end

coverage no Activate code coverage measurement for all server-side (XS) JavaScript code
that is executed by the tests or which is in the scope of a specified package.

coverage=true

coverage=sap.hana.testtools.mockstar

coverage=true&exclude=sap.hana.testtools.mockstar.test
s

SAP HANA Developer Guide

438 PUBLIC Writing Server-Side JavaScript Code
7.10.3.4 XSUnit Test Examples

XSUnit includes a selection of test packages that demonstrate the scope of tests you can perform on an SAP
HANA XS application.

The following table lists the test packages included in the XSUnit test framework. The table also indicates the
name of the test file and provides a quick overview of the scope of the test.

Note
If you want to have a look at the code in the tests, checkout the package sap.hana.testtools.demo as an
XS project to your local workspace.

ExampleTest Units
Package Name Test Name (.xsjslib) Description

tests.getting_started myFirstTest Shows the usage of some basic Jas­

mine matchers as well as the usage of
custom matchers toMatchData and
toEqualObject that are supported
by the extended Jasmine version.

tests.attribute_view_1 AT_PRODUCTS_Test Shows how to configure mockstar in or­

der to replace a CDS entity with a test
table. Be aware that this test does not
make sense, as this attribute test tests
nothing at all - no logic, no joins,...

tests.graphic_calcview_1 CA_ORDERS_Test Tests a copy of the graphical calculation

view where the direct dependent tables
are replaced by test tables.

tests.graphic_calcview_3 CA_OPEN_AMOUNT_Test Tests the integration with the analytic

view but replaces the dependencies to
the tables with test tables. This exam­
ple test shows how to upload data from
a comma-separated-values (CSV) file
into the test tables

tests.hdbprocedure_with_cds CreateProductTest Tests a non-read-only HDBProcedure

with table in/out parameters while re­
placing the underlying Core Data Serv­
ices (CDS) entities with test tables.

tests.hdbprocedure_with_hdbview GetInvoicesTest Tests an HDBProcedure with scalar in

and view out parameters while replac­
ing a dependent hdbview with a test
table.

tests.hdbprocedure_with_hierarchy­ HierarchyProcedureTest Tests an HDBProcedure that includes a

view hierarchy view while replacing all under­
lying CDS entities with test tables.

tests.hdbprocedure_with_hdbproce­ CreateProductTest Tests an HDBProcedure while replacing

dure a dependent hdbprocedure with an
hdbprocedure that was created for
testing.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 439
Package Name Test Name (.xsjslib) Description

tests.http_service whoAmIServiceTestE2E Tests an http service and checks if it re­

turns the expected value. This test is
not automatically executed since the
SAP HANA instance needs to be main­
tained by the system administrator.

tests.procedure_1 PR_OPEN_AMOUNT_Test Tests a copy of the stored procedure

where the directly dependent tables are
replaced with test tables.

tests.scripted_calcview_1 CA_ABC_PRODUCTS_Test Tests a copy of the scripted calculation

view where the directly dependent ana­
lytic view is replaced with a test table.

tests.scripted_calcview_2 CA_OPEN_AMOUNT_SCRIPTED_W_PR Tests the integration with the called

OCEDURE_Test stored procedures but replaces the de­
pendencies to the tables with test ta­
bles.

apps.rating.tests validatorTest Tests a simple server-side (XS) Java­

Script.

dataAccessorTest Tests the database layer of server-side

(XS) JavaScript using Jasmine
spyOn() for testing in isolation.

oDataTestE2E Checks the accessibility of an OData

service and tests an OData service
without dependencies using mockstar.

ratingServicesTestE2E Tests an XS JavaScript service (end-to-

end scenario test).

tests myMockstarEnvironment Shows how to enhance the

mockstarEnvironment library to
add further reuse functions or change
the behaviour slightly to suit the con­
text.

7.10.3.5 The Mockstar Test Environment

Mockstar is a tool that is designed to enable you to isolate SAP HANA content in tests run by an automated test
suite.

To write self-contained unit tests that are executable in any system, it is essential to be able to test the selected
SAP HANA objects in isolation. For a typical unit test using the XSUnit tools, you need to be able to change any
direct dependencies between the tested objects and other views or tables with references to simple tables. For
integration tests, rather than change the direct dependencies to a view or a table, you might need to change
dependencies between the dependent views (deeper in the dependency hierarchy).

Mockstar is a tool that is specifically designed to enable you to isolate test objects, for example, a view or
procedure. Mockstar allows you to create a copy of the tested view or procedure and substitute the
dependency to a another view or table with a table that is stored in a test schema. It is strongly recommended
to use a dedicated schema for the tests; in this test schema, you have write permissions and, as a result, full
control over the data in the tables and views.

SAP HANA Developer Guide

440 PUBLIC Writing Server-Side JavaScript Code
The Mockstart test-isolation tool provides the following features:

● Creates a copy of the SAP HANA object to test (for example, a view or database table); the copied object
retains the same business logic as the original one object, but replaces some or all dependencies.
● Replaces the (static) dependencies to tables or views with temporary tables
● Supports deep dependency substitution
Mockstar can determine dependencies deep within a hierarchy of dependencies and copy only the
necessary parts of the hierarchy.

Mockstar tools are included in the delivery unit HANA_TEST_TOOLS, which you must install manually, for
example, using the SAP HANA studio or the SAP HANA Application Lifecycle Management tool. After the
installation completes, the Mockstar tools are available in the package sap.hana.testtools.mockstar.

Note
Importing a delivery unit into an SAP HANA system requires the REPO.IMPORT privilege, which is normally
granted only to the system administrator.

7.10.3.6 Mockstar Environment Example Syntax

A basic example of the syntax required to set up the Mockstar test environment.

The following example shows a simple setup using standard locations.

Note
The names of schemas, tables, and views used in the following code example are intended to be for
illustration purposes only.

var mockstarEnvironment = $.import('sap.hana.testtools.mockstar',

'mockstarEnvironment');
describe('testSuiteDescription', function() {
var testEnvironment = null;
beforeOnce(function() {
var definition = {
schema : 'SCHEMA',
model : {
schema : '_SYS_BIC',
name : 'modelName' //e.g. package/MODEL
},
substituteTables : {
"table" : { name : 'package::TABLE' }
},
substituteViews : {
"view" : {
schema : '_SYS_BIC',
name : 'package/VIEW'
}
}
};
testEnvironment = mockstarEnvironment.defineAndCreate(definition);
});
});

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 441
7.10.3.7 XSUnit Troubleshooting Solutions
Use trace files and other tools to fix problems with test operations.

The Mockstar test-isolation tools write helpful information in the SAP HANA trace files. You can adapt the trace
level, for example, to debug to ensure the right amount and type of information is written during the test run.
Note that you need the corresponding administration role to be able to change the trace-level settings in SAP
HANA. The trace files are written in the trace component xsa:sap.hana.testtools (truncated to
“xsa:sap.hana.tes” in the trace files).

Tip
As an alternative to reading the trace files directly, you can also use the SQL console to select data from the
table M_MERGED_TRACES.

This section contains information about the problems that developers frequently encounter during test runs:

● SAP HANA Test Tools Version [page 442]

● The Library is Not Part of an Application [page 442]
● Error for Cloned OData Service [page 443]
● Duplicate Entries When Inserting Test Data [page 443]
● Test Table Already Exists [page 443]
● Test Model Activation Fails [page 444]
● No Entries Returned From Copied Test Model [page 444]
● No Test Data Inserted into Test Table [page 444]
● TestRunner Tool Times Out [page 445]
● Test Model Creation is Aborted [page 446]
● Database Connections in XSUnit Test [page 446]

SAP HANA Test Tools Version

Which version of the SAP HANA test tools suite is installed?

1. Start SAP HANA studio

2. Open the SAP HANA Modeler perspective.
3. In the Quick Launch window, choose Delivery Units...
4. Choose HANA_TEST_TOOLS.

Import Error: The Library is Not Part of an Application

If the test runner tool shows the following error:

import: the library is not part of an application

The JavaScript library you want to test can only be loaded when there is an application descriptor (.xsapp file)
defined within the package hierarchy. The application descriptor is the core file that you use to describe an

SAP HANA Developer Guide

442 PUBLIC Writing Server-Side JavaScript Code
application's framework within SAP HANA XS. If your tests are not part of your application package hierarchy, it
is recommended you to create an .xsapp file in the context of the XS Project that contains the tests.

Error for Cloned OData Service

The following error message is displayed when testing access to an OData service in SAP HANA XS:

404 - Not found: Error for cloned OData Service (.xsodata)

Try the following solutions:

1. Try to access the generated service directly in a separate Web browser.

2. Check whether the file (xsodata service definition) exists, has been activated in the SAP HANA repository,
and is in the expected target folder.
3. Ensure that the target folder or one of its parent folders contains the following activated artifacts:
○ .xsapp file
Application descriptor file required by an SAP HANA XS application
○ .xsaccess file
Application access file which enables access to an SAP HANA XS application

Duplicate Entries When Inserting Test Data

If you encounter problems concerning duplicate entries when running tests, try the following solutions:

1. When inserting records into a productive table, ensure that no jasmine.dbConnection.commit() call
occurs during test execution.
2. When inserting records into a test table, ensure that the table entries are deleted (dropped) before they are
(re)created.

var tableUtils = new TableUtils(jasmine.dbConnection);

tableUtils.clearTableInUserSchema(invoicesTestTable);

Test Table Already Exists

You encounter an error message that explains that a test table cannot be created during the test because the
table already exists. You must ensure that the specified table is deleted before the test tries to create it during
the test run.

var sqlExecutor = new SqlExecutor(jasmine.dbConnection);

var createTableString = 'CREATE COLUMN TABLE ' + <table name> + '...' );
sqlExecutor.execSingleIgnoreFailing('drop table ' + <table name> );
sqlExecutor.execSingle(createTableString );

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 443
You can also use the functions provided by the table utilitites library, which enables you to ensure that the table
is dropped at the right time:

var tableUtils = new TableUtils(jasmine.dbConnection);

testTable = tableUtils.copyIntoUserSchema(originSchema, originTable);

Test Model Activation Fails

Your test produces an error relating to a failed activation:

Error: Repository: Activation failed for at least one object [...]

identifier is too long:[...]
Maximum length is 127: ...

the name of the model is too long (inlcuding the package name). You can reduce the name by setting the
TruncOptions option as shown in the following code snippet:

var mockstar = $.sap.hana.testtools.mockstar;

testView = mockstar.apiFacade.createTestModel(originalModel,
targetPackage, dependencySubstitutions, mockstar.TruncOptions.FULL);

Tip
Its a good idea to analyze the created model before it is activated.

To generate a detailed and structured error log, in the SAP HANA Systems view in the SAP HANA studio and
locate the test package and activate it manually.

No Entries Returned From Copied Test Model

1. Open the generated test model.

The generated model is located in a package with the name
tmp.unittest.<userName>.<originalPackage>. If you have configured the createTestModel()
function with the parameter mockstar.TruncOptions.FULL, the package name is
tmp.unittest.<userName>.
2. Ensure that the dependencies have been replaced as expected.
To see if the tables are filled correctly by the test, see No Test Data Inserted into Test Table [page 444].
3. Check the test view itself.
If the tested view returns no data, but data are expected, check if the data are removed by a filter during
extraction from the underlying data source.

No Test Data Inserted into Test Table

To test whether a test inserts data as expected into the created test table, implement a
jasmine.dbConnection.commit( ) connection to ensure that the data created during the test is stored

SAP HANA Developer Guide

444 PUBLIC Writing Server-Side JavaScript Code
persistently. Without the jasmine.dbConnection.commit( ), the test data is not persistent; the test
deletes all test data when the database session is closed. Start the test again using the TestRunner tool. When
the test completes, the test table should contain test data.

TestRunner Tool Times Out

The detault timeout setting for the TestRunner tool is ten (10) minutes. If your test run for longer than ten
minutes and cause a timeout, try splitting the test into smaller and shorter elements. If this is no possible, try
running the test in three phases:

1. Prepare the test run.

/sap/hana/testtools/unit/jasminexs/PrepareTestRun.xsjs
This generates a new test-run ID; no test runs are executed.
○ Response:
Returns the new test-run ID. If you request the answer in HTML format and provide all required
parameters for the TestRunner tool, you receive the appropriate links you can use in the following
steps (run the test and fetch the results).
○ Parameters:
format (optional; default = “html”)
Set this parameter to receive the test-run ID in the desired format. You can use any of the formats
supported by the TestRunner format parameter.
2. Run the tests.
/sap/hana/testtools/unit/jasminexs/TestRunner.xsjs
This step is almost identical to the usual test execution with the addition of parameter runid.
○ Response:
If the tests finish within the configured time frame, you receive the test results as expected. If the test
are too long,a timeout occurs.
○ Parameters:
runid. Required for this kind of (manual) execution: This is the test-run ID generated in the previous
step.
3. Fetch the test results (optional: only required if the test run causes a timeout).
/sap/hana/testtools/unit/jasminexs/GetTestResults.xsjs
Fetches the test results for a given test-run ID. You an run this service multiple times for each test.
○ Response:
Returns the test results in the requested format. If the tests are not yet finished, you receive a status
message (either “PREPARED” or “STARTED”). If the run ID provided does not exist, an error message is
displayed.
○ Parameters:
runid. Required for this kind of (manual) execution.
format (optional; default = “html”)

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 445
Test Model Creation is Aborted

This error sometimes occurs if you try to create a copy of the original view and replace some dependencies
with test tables. The reason for the error is one of the following:

● You did not provide any dependency substitutions. For example, you passed an empty array as the third
parameter of mockstar.createTestModel()).
● The view that you want to test does not depend on any of the original views specified in the dependency
substitutions.
● For active schema mapping, you have written the dependencies with the physical schema whereas the
view refers to the authoring schema. Provide the schema in the same way as it is written in the view (or
stored procedure).

Database Connections in XSUnit Test

The XSUnit test framework provides a new “managed” database connection called jasmine.dbConnection,
which is automatically opened and rolled back (and closed) after each test completes. You can use it in
beforeEach or afterEach functions, in other functions defined in your test libraries, or even in imported
libraries, in the event that you have moved test code into external libraries.

Related Information

Managed Database Connection Setup [page 435]

7.10.4 Testing JavaScript with XSUnit

Test an XS JavaScript using XSUnit test tools.

As the XSUnit test tools are based on a custom version of the JavaScript test framework Jasmine, you can use
XSUnit to test JavaScript. XSUnit provides tools that enable you to create and install a test “double” for one or
more object methods. In the Jasmine framework, a test double is known as a “spy”. A spy can be used not only
to stub any function but also to track calls to it and all arguments, too.

Note
XSUnit includes special matchers that enable interaction with Jasmine spies.

The XSUnit test tools delivery unit (DU) includes a small XS JavaScript demo “Ratings” application which
comprises an SAPUI5 client frontend on top of OData and XS JavaScript services; the Ratings application
enables you to experiment with different test techniques. You can try out the application at the following URL:

http://<SAPHANA_host>:80<instancenumber>/sap/hana/testtools/demo/apps/rating/
WebContent/

SAP HANA Developer Guide

446 PUBLIC Writing Server-Side JavaScript Code
Related Information

XSUnit's Jasmine Spy Syntax [page 447]

Testing HTTP Services with XSUnit [page 448]

7.10.4.1 XSUnit's Jasmine Spy Syntax

A command “cheat sheet” for the Jasmine Spy syntax.

The following code example provides a quick overview of commonly used commands that enable the use of
Jasmine Spies. You can see how to perform the following actions:

● Install a method double [page 447]

● Install an object double [page 447]
● Check a function call (and values) [page 448]

Installing a Method Double

The following code example shows how install a method double (simple example).

spyOn(object, "method");
expect(object.method).toHaveBeenCalled();

The following code example shows how install a method double (variant).

var spyMethod = spyOn(object, "method");

expect(spyMethod).toHaveBeenCalled();

The following code example shows how install a method double (custom action for double).

spyOn(object, "method"); // delegates nowhere

spyOn(object, "method").and.returnValue(3); // returns constant value
spyOn(object, "method").and.callThrough(); // delegates to original function
spyOn(object, "method").and.callFake(fakeFunction); // delegates to other
function

Installing an Object Double

The following code example shows how install an object double.

var spyObject = jasmine.createSpyObj("spy name", [ "method1", "method2",

"method3" ]);
spyObject.method1.and.returnValue(3);
expect(spyObject.method1).toHaveBeenCalled();

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 447
Checking Function Calls (and Values)

The following code example shows how to check whether the function has been called as expected, and if so, if
the the right values were used.

expect(spyObject.method).toHaveBeenCalled();
expect(spyObject.method).toHaveBeenCalledWith(expArgValue1, expArgValue2);
expect(spyObject.method.calls.allArgs()).toContain([ expArgValue1,
expArgValue2 ]);
expect(spyObject.method.calls.mostRecent().args).toEqual([ expArgVal1,
expArgVal2 ]);
expect(spyObject.method.calls.count()).toBe(2);
spyObject.method.calls.reset(); // reset all calls

7.10.4.2 Testing HTTP Services with XSUnit

XS JavaScript files that can be accessed by performing an HTTP call against the service defined in the XS
JavaScript file.

You can use the TestRunner tool to call an XS JavaScript service. The TestRunner service is part of the test-
tools package sap.hana.testtools.unit.jasminexs and has one mandatory parameter, namely
package. Since TestRunner is an HTTP GET service, you can execute the service in the browser using the
following URL:

http://<hostname>:80<instancenumber>/sap/hana/testtools/unit/jasminexs/
TestRunner.xsjs?package=<mypackage>

Since it is not possible to import XS Javascript files (.xsjs) files into a JavaScript library (.xsjslib), the
functions you implement inside the XS JavaScript file cannot be tested within an XSUnit test. As a
consequence, it is recommended to include only minimal logic within the XSJS files and delegate tasks to the
functions implemented in corresponsding JavaScript libraries; these libraries can be tested in isolation using
XSUnit tools (for example, Mockstar).

Note
XSUnit enables you to perform an HTTP call to your XSJS services via HTTP. However, this is an end-to-end
system test with no possibility to use test doubles during the test. These tests are not suitable for testing a
JavaScript function.

Since you cannot insert test data into the test table during the test, the tests have no control over the data. This
restriction reduces the scope of the tests you can perform for HTTP calls, for example, you can test the
following scenarios:

● Service must return an error if mandatory parameters are missing

● Service must return an error if the chosen HTTP type is correct
● Service must return an error if the wrong input is provided
● End-to-end HTTP scenarios (CREATE, READ, UPDATE, and DELETE)

describe("example for http tests", function() {

it("should receive answer from service", function() {
var requestBody = '{"param1":42,"param2":"xyz"}';

SAP HANA Developer Guide

448 PUBLIC Writing Server-Side JavaScript Code
 var headers = {
"Content-Type" : "application/json"
};
var response = jasmine.callHTTPService("/path/to/your/app/Service.xsjs",
$.net.http.POST, requestBody, headers);
expect(response.status).toBe($.net.http.OK);
var body = response.body ? response.body.asString() : "";
expect(body).toMatch(/regular expression that checks correct response/);
});
});

SAP HANA Database Logon for XSUnit

To ensure access to SAP HANA, you need to adapt the default HTTP destination file
(:localhost.xshttpdest) provided with the XSUnit test tools. The default HTTP destinatinon configuration
file is located in sap.hana.testtools.unit.jasminexs.lib:localhost.xshttpdest to fit to your
HANA instance. To access an HTTP destination configuration, you need the permissions granted in the user
role sap.hana.xs.admin.roles::HTTPDestAdministrator.

Caution
To change the HTTP destination, create an HTTP extension" of your own; do not make any changes to the
file localhost.xshttpdest. Changes to localhost.xshttpdest are overwritten by updates to the
XSUnit test tools on your system.

Related Information

Maintaining HTTP Destinations [page 80]

7.10.4.3 Testing JavaScript Functions with XSUnit

Use XSUnit tools to test JavaScript code that depends on functions in your code, for example: dependencies on
functions, libraries, or to database tables.

In JavaScript it is possible to overwrite anything that is visible in a context, for example: public data, public
functions, or even the whole class. With XSUnit, you can make use of a simulation framework that is included
with Jasmine. The simulation framework provides a mechanism that enables you to create and install a test
double (so-called Jasmine “Spy”), which can help you to reduce some of the basic code and keep the code
more concise. Jasmine Spies should be created in the test setup, before you define any expectations. The
Spies can then be checked, using the standard Jasmine expectation syntax. You can check if a Spy is called (or
not) and find out what (if any) parameters were used in the call. Spies are removed at the end of every test
specification.

Note
Each dependency increases the complexity of testing involved for a function or a component.

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 449
The Average Component Dependency (ACD) is the number of dependencies to other components, averaged
over all components; it indicates whether your system is loosely coupled. If you prefer to implement JavaScript
in an object-oriented way, you can apply dependency management aspects by following object-oriented design
principles (OOD).

The information in this topic covers the following test scenarios:

● Dependencies on Function Libraries [page 450]

● Dependency on Database Table [page 451]

Dependencies on Function Libraries

The following code snippet defines a controller that you want to test; the controller depends on a Date object.
The accompanying code snippet shows how you can test this code.

var Controller = null;

(function() {
//constructor function
Controller = function(dataModel) {
this.model = dataModel;
};
function updateModelWithTimestamp(newData) {
this.model.updateData(newData, this.getCurrentDate());
}
Controller.prototype.updateModel = function(newData) {
//bind 'this' to the private function
updateModelWithTimestamp.call(this, newData);
};
Controller.prototype.getCurrentDate = function() {
return new Date(Date.now());
};
}());
function DataModel() {
var modifiedAt = null;
var modifiedBy = null;
var data = null;
this.updateData = function(newData, modifiedAtDate) {
data = newData;
modifiedAt = modifiedAtDate;
modifiedBy = $.session.getUsername();
};
this.getModificationDate = function() {
return modifiedAt;
};
}

The following code snippets shows an example of the test code you could run; the code uses a Jasmine Spy
ensures the dependencies on the Date object are replaced and tested as expected.

var Controller = $.import("sap.hana.testtools.demo.objects.xs_javascript",

"javascriptOO").Controller;
var DataModel= $.import("sap.hana.testtools.demo.objects.xs_javascript",
"javascriptOO").DataModel;
describe('Controller', function() {
var controller = null;
var model = null;
var anyDate = new Date(2013, 8, 27, 11, 0, 0, 0);

beforeEach(function() {
model = new DataModel();

SAP HANA Developer Guide

450 PUBLIC Writing Server-Side JavaScript Code
 controller = new Controller(model);
});
it('should set current date when data is modified (replace Date.now() using
jasmine spies)', function() {
spyOn(Date, 'now').and.returnValue(anyDate.getTime());
oController.updateModel({data : [1,2,3]});
expect(model.getModificationDate()).toEqual(anyDate);
});
});

Dependency on Database Table

It is important to try to avoid mixing business logic that is implemented in JavaScript with the data base
interaction. We recommend moving the database persistency logic into a dedicated persistency class, so that
just the business logic remains for testing. The goal of the test is to be able to test both normal and special
cases without interacting with the data base at all.

To unit test the persistency class, you can parameterize the schema and use a schema for testing, for example,
the user schema where you have all authorizations required to create, modify, and drop objects, and cannot
mess things up with the test. Last of all, you can offer a small set of integration tests, that just ensure that the
productive classes, the AnyService class, and the Persistency class, integrate well.

Note
For sake of conciseness, resource closing and error handling is missing from the following code example.

function Persistency(dbConnection, schema) {

var dbSchema = schema !== undefined ? schema : 'SAP_HANA_TEST_DEMO';
this.existsEntry = function(key) {
var pstmt = dbConnection.prepareStatement('SELECT key FROM "' +
dbSchema + '"."Table" WHERE KEY=?');
pstmt.setString(1, key);
if (pstmt.executeQuery().next()) {
return true;
);
return false;
};
this.insertEntry = function(newEntry) {
var pstmt = dbConnection.prepareStatement('INSERT INTO "' + dbSchema +
'"."Table" VALUES(?,?)');
pstmt.setString(1, newEntry.Id);
pstmt.setString(2, newEntry.Value);
pstmt.execute();
};
}
function AnyService(persistency) {
this.execute = function(input) {
//validate input
if (!persistency.existsEntry(input.Id)) {
//calculate newEntry
persistency.insertEntry(newEntry);
}
};
}

The following code snippets shows an example of the test code you could run to test the dependencies.

var Persistency = $.import("package.of.persistency", "persistency").Persistency;

SAP HANA Developer Guide

Writing Server-Side JavaScript Code PUBLIC 451
 describe('Persistency test', function() {
var SqlExecutor = $.import('sap.hana.testtools.unit.util',
'sqlExecutor').SqlExecutor;
var TableUtils = $.import('sap.hana.testtools.unit.util',
'tableUtils').TableUtils;
var originTable = 'TableName';
var testTable = null;
var originSchema = 'SAP_HANA_TEST_DEMO';
var userSchema = $.session.getUsername().toUpperCase();
beforeOnce(function(){
var tableUtils = new TableUtils(jasmine.dbConnection);
testTable = tableUtils.copyIntoUserSchema(originSchema, originTable);
});
it('should insert one entry into table', function() {
var persistency = new Persistency(jasmine.dbConnection, userSchema);
persistency.insertEntry({ Id : '0815', Value : 1});
expect(persistency.existsEntry('0815');
expect(selectAllFromTable().getRowCount()).toBe(1);
});
function selectAllFromTable() {
var sqlExecutor = new SqlExecutor(jasmine.dbConnection);
return sqlExecutor.execQuery('select * from ' + testTable);
}
});

Testing a Self-Contained JavaScript Function

The following code snippet show how to use XSUnit to test a self-contained JavaScript function (mathlib); a
self-contained function has no dependencies to other JavaScript functions, database tables or session
parameters.

var mathlib = $.import("package.of.your.library", "math");

describe('The math XS JavaScript library', function() {
it('should calculate "7" as maximum value of "3, 7"', function() {
var maxValue = mathlib.max(3, 7);
expect(maxValue).toBe(7);
});
it('should calculate "-10" as maximum value of "-10, -20"', function() {
var maxValue = mathlib.max(-10, -20);
expect(maxValue).toBe(-10);
});
});

SAP HANA Developer Guide

452 PUBLIC Writing Server-Side JavaScript Code
8 Building UIs

You can use the SAPUI5 user interface technology to build and adapt client applications based on SAP HANA.

Related Information

Building User Interfaces with SAPUI5 for SAP HANA [page 453]
Consuming Data and Services with SAPUI5 for SAP HANA [page 454]

8.1 Building User Interfaces with SAPUI5 for SAP HANA

UI development toolkit for HTML5 (SAPUI5) is a user interface technology that is used to build and adapt client
applications based on SAP HANA. You can install SAPUI5 in the SAP HANA studio to build user interfaces
delivered by SAP HANA's Web server.

The SAPUI5 runtime is a client-side HTML5 rendering library with a rich set of standard and extension controls.
It provides a lightweight programming model for desktop as well as mobile applications. Based on JavaScript, it
supports Rich Internet Applications (RIA) such as client-side features. SAPUI5 complies with OpenAjax and can
be used with standard JavaScript libraries.

SAPUI5 Demo Kit

The SAPUI5 Demo Kit contains:

● A Developer Guide with a summary of valuable information about the programming languages used, open
source technologies, development tools, and APIs
● Explored app, which provides a detailed view on almost every control including detailed information on the
properties, aggregations, events, and methods. Additionally it provides running samples including a code
view, from which you can easily copy the required code snippets
● A Controls section containing running demo examples with descriptions and source codes for the core
libraries
● API reference with JavaScript documentation of Framework and Control API
● Demo Apps with running samples

SAP HANA Developer Guide

Building UIs PUBLIC 453
Related Information

SAPUI5 Demo Kit (version 1.28)

8.2 Consuming Data and Services with SAPUI5 for SAP

HANA

SAP HANA Extended Application Services (SAP HANA XS) can be used to expose the database data model,
with its tables, views and database procedures, to UI clients.

You can expose an SAP HANA model using OData services or by writing native server-side JavaScript code that
runs in the SAP HANA context. You can also use SAP HANA XS to build dynamic HTML5 client applications, for
example, using SAPUI5 for SAP HANA.

The server-centric approach to native application development envisaged for SAP HANA assumes the following
high-level scenario:

● View
UI rendering occurs completely in the client (SAPUI5, browser, mobile applications)
● Controller
Procedural (control-flow) logic is defined in (XS) JavaScript, SQLScript or an OData service
● Model
All application artifacts are stored in SAP HANA

SAP HANA Application Development with SAP HANA XS

Each of the levels illustrated in the graphic (view, control, model) is manifested in a particular technology and
dedicated languages. After you have defined the data model with design-time artifacts and the equivalent run-
time objects, you develop the control-flow logic to expose the data, for example, using server-side JavaScript or
an OData service. With the data model and control-flow logic in place, you can build the presentation logic to
view the exposed data in a UI client application using SAPUI5 for SAP HANA. For example, you can use an
SAPUI5 client to request and display data exposed by an OData service; the UI could include buttons that
trigger operations performed by SAP HANA XS JavaScript service; and the data displayed is retrieved from
data end points defined in your data model, for example, SQLScript or CDS.

SAP HANA Developer Guide

454 PUBLIC Building UIs
Related Information

SAPUI5 Demo Kit (version 1.32.7)

8.3 SAPUI5 for SAP HANA Development Tutorials

Tutorials are designed to extend task-based information to show you how to use real code and examples to
build native SAP HANA applications. The tutorials provided here include examples of how to build simple
SAPUI5 applications.

The tutorials provided here show you how to create your own simple SAPUI5-based applications. Some of the
tutorials make use of sample data, design-time development objects, and functions provided by the SAP HANA
Interactive Education (SHINE) demo application, for example: database tables, data views, server-side
JavaScript (XSJS) and OData services, and user-interface elements.

Note
If the SHINE DU (HCODEMOCONTENT) is not already installed on your SAP HANA system, you can download
the DU from the SAP Software Download Center in the SAP Support Portal at http://service.sap.com/
swdc. On the SAP HANA PLATFORM EDIT. 1.0 Web page, locate the download package SAP HANA DEMO
MODELL 1.0 # OS independent SAP HANA database .

The tutorials provided here cover the following areas:

● SAPUI5 clients
○ Hello world
Build a simple “Hello World” application using SAPUI5 tools; the exercise shows how the development
process works and which components are required.
● Consuming Server-side JavaScript (XSJS) services with SAPUI5
Build an SAPUI5 application that calls an XSJS service in response to user interaction with the user
interface, for example, clicking a button to perform an action. In this case, the XSJS service called by the UI
request performs an action and returns a response, which is displayed in the SAPUI5 client.
● Consuming OData services with SAPUI5
Build an SAPUI5 application that calls an OData service in response to user interaction with the user
interface, for example, clicking a graph or report chart. In this case, the OData service called by the UI
request performs an action (collects data) and returns a response, which is displayed in the SAPUI5 client.
○ Bind a UI element in an SAPUI5 application to the data specified in an OData service. For example, you
can populate the contents of a table column displayed in an SAPUI5 application by using the data
stored in a database table defined in an OData service.
○ Build an SAPUI5 view that provides input fields, which you can use to create a new record or update an
existing record in a database table, for example, using the OData create, update, and delete (CRUD)
features.
● Localizing UI Strings in SAPUI5
Create a simple text-bundle file for translation purposes and re-import the translated text into SAP HANA
for use with a specific language locale. Textbundles containing text strings that define elements of the user-
interface (for example, buttons and menu options).

SAP HANA Developer Guide

Building UIs PUBLIC 455
Related Information

SAPUI5 Demo Kit (version 1.28)

8.3.1 Tutorial: Create a Hello-World SAPUI5 Application

SAPUI5 provides a client-side HTML5 rendering library with a comprehensive set of standard controls and
extensions that you can use to build a UI quickly and easily.

Prerequisites

You have installed the SAPUI5 tools included in the delivery unit (DU) SAPUI5_1.

Context

In this tutorial, you create a simple “Hello World” application in SAPUI5 using the model-view-controller
concept. You create a bootstrap HTML (index.html) page in a HelloWorld package and a HelloWorld
controller and HelloWorld view in a sub-package called helloworldx:

\
HelloWorld
\
helloworldx
\
HelloWorld.controller.js
HelloWorld.view.js
.xsaccess
.xsapp
index.html

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the basic structure for your application:
a. Navigate to the package in which you want to create the SAPUI5 application and from the context
menu choose Create Application.
b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter a package name, for example, HelloWorld, and choose Create.

SAP HANA Developer Guide

456 PUBLIC Building UIs
 You now have a basic package structure to hold your application files. The root package for your new
application also contains the required application descriptors, which control access to the services and
data exposed by the new application.
3. Create a subpackage to store the SAPUI5 view and controller files:
a. Select the HelloWorld package and from the context menu choose New Package.
b. Enter a name, for example, helloworldx, and choose Create.
4. Create the SAPUI5 HelloWorld view (view.js):
a. Select the helloworldx package and from the context menu choose New File.
b. Enter a name, for example, HelloWorld.view.js, and choose Create.
5. Create the SAPUI5 HelloWorld controller (controller.js):
a. Select the helloworldx package and from the context menu choose New File.
b. Enter a name, for example, HelloWorld.controller.js, and choose Create.
6. Call the view from the index.html file.
Replace the entire content of the index.html file with the following:

<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<script src="/sap/ui5/1/resources/sap-ui-core.js" id="sap-ui-bootstrap"
data-sap-ui-libs="sap.ui.commons" data-sap-ui-theme="sap_bluecrystal">
</script>
<!-- add sap.ui.table,sap.ui.ux3 and/or other libraries to 'data-sap-ui-
libs' if required -->
<script>
sap.ui.localResources("helloworldx");
var view = sap.ui.view({
id: "idHelloWorld1",
viewName: "helloworldx.HelloWorld",
type: sap.ui.core.mvc.ViewType.JS
});
view.placeAt("content");
</script>
</head>
<body class="sapUiBody" role="application">
<div id="content"></div>
</body>
</html>

You have added the following elements to the index.html file:

○ Bootstrap script: SAPUI5 is implemented in JavaScript, so to load the SAPUI5 runtime library sapui-
core.js from the SAP HANA repository folder /sap/ui5/1/resources/ on the client you include
its bootstrap with a <script> tag. The data-sap-ui-theme attribute specifies the visual design to
be applied and the data-sap-ui-libs attribute the UI control libraries to be used.
○ Application script: SAPUI5 is based on the model-view-controller paradigm. To create the view and
controller, the SAPUI5 runtime needs to know from where to load the related resources
(sap.ui.localResources); in this case from the relative sub-folder /helloworldx. In this
example, you place the newly created instance of the HelloWorld view from the helloworldx sub-
folder in an HTML element with the ID content. SAPUI5 supports different view types; here the JS
(JavaScript) view type is used.
○ HTML body: The HTML element with the ID content, in which you placed the view, needs to be
included in the HTML page. To do this, you add a <div> block with id="content" to the HTML body.
The <body> attribute class="sapUiBody" defines the SAPUI5 CSS class to be used, which ensures

SAP HANA Developer Guide

Building UIs PUBLIC 457
 that the page background and some other styles are properly set. The attribute
role="application" sets the WAI-ARIA landmark role.
7. Add UI elements to the SAPUI5 application interface.
You define UI elements in the createContent function section of the HelloWorld.view.js file. In
this example, you instantiate the Button UI element class as myButton and then return it at the end of the
createContent function. The SAPUI5 application renders any UI element (or element group) returned
from the createContent function.

sap.ui.jsview("helloworldx.HelloWorld", {
/** Specifies the Controller belonging to this View.
* In the case that it is not implemented, or that "null" is returned,
this View does not have a Controller.
* @memberOf helloworldx.HelloWorld
*/
getControllerName : function() {
return "helloworldx.HelloWorld";
},
/** Is initially called once after the Controller has been instantiated.
It is the place where the UI is constructed.
* Since the Controller is given to this method, its event handlers can be
attached right away.
* @memberOf helloworldx.HelloWorld
*/
createContent : function(oController) {
var myButton = new sap.ui.commons.Button({ id : "btn",
text:"Hello World"});
myButton.attachPress(function(){$("#btn").fadeOut();});
return myButton;
}
});

8. Define the controller.

The HelloWorld.controller.js file contains the view controller logic. In this basic hello world example,
the controller does not contain any methods:

sap.ui.controller("helloworldx.HelloWorld", {
});

9. Save all files.

10. Test your “Hello World” SAPUI5 application in a Web browser.

Select the index.html file and choose (Run) in the toolbar.

You should see the Hello World button. Click the button to check that it disappears.

SAP HANA Developer Guide

458 PUBLIC Building UIs
8.3.2 Tutorial: Consume an XSJS Service from SAPUI5

An XS server-side JavaScript (XSJS) application can be used to perform an action linked to an element such as
a button or a text box in an SAPUI5 application.

Prerequisites

● You have installed the SAPUI5 tools included in the delivery unit (DU) SAPUI5_1.
● You have installed the SHINE (democontent) delivery unit; this DU contains the XSJS service you want to
consume with the SAPUI5 application you build in this tutorial.

Note
You might have to adjust the paths in the code examples provided to suit the folder/package hierarchy in
your SAP HANA repository, for example, to point to the underlying content (demonstration tables and
services) referenced in the tutorial.

Context

You can configure an SAPUI5 application to call an XSJS service in response to user interaction with the UI; the
XSJS service performs an action and returns a response. This tutorial demonstrates how to trigger an XSJS
service which performs a mathematical multiplication when numbers are typed in text boxes displayed in an
SAPUI5 application.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the basic structure for your application:
a. Navigate to the package in which you want to create the SAPUI5 application and from the context
menu choose Create Application.
b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter a package name, for example, xsjsMultiply, and choose Create.
You now have a basic package structure to hold your application files. The root package for your new
application also contains the required application descriptors, which control access to the services and
data exposed by the new application.
3. Create a subpackage to store the SAPUI5 view and controller files:
a. Select the xsjsMultiply package and from the context menu choose New Package.

SAP HANA Developer Guide

Building UIs PUBLIC 459
 b. Enter a name, for example, xsjsmultiply, and choose Create.
4. Create the SAPUI5 xsjsMultiply view (view.js):
a. Select the xsjsmultiply package and from the context menu choose New File.
b. Enter a name, for example, xsjsMultiply.view.js, and choose Create.
5. Create the SAPUI5 xsjsMultiply controller (controller.js):
a. Select the xsjsmultiply package and from the context menu choose New File.
b. Enter a name, for example, xsjsMultiply.controller.js, and choose Create.
6. Call the view from the index.html file.
Replace the entire content of the index.html file with the following:

<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<script src="/sap/ui5/1/resources/sap-ui-core.js" id="sap-ui-bootstrap"
data-sap-ui-libs="sap.ui.commons,sap.ui.table" data-sap-ui-
theme="sap_bluecrystal">
</script>
<script>
sap.ui.localResources("xsjsmultiply");
var view = sap.ui.view({
id: "idxsjsMultiply",
viewName: "xsjsmultiply.xsjsMultiply",
type: sap.ui.core.mvc.ViewType.JS
});
view.placeAt("content");
</script>
</head>
<body class="sapUiBody" role="application">
<div id="content"></div>
</body>
</html>

You have added the following elements to the index.html file:

○ Bootstrap script: SAPUI5 is implemented in JavaScript, so to load the SAPUI5 runtime library sapui-
core.js from the SAP HANA repository folder /sap/ui5/1/resources/ on the client you include
its bootstrap with a <script> tag. The data-sap-ui-theme attribute specifies the visual design to
be applied and the data-sap-ui-libs attribute the UI control libraries to be used.
○ Application script: SAPUI5 is based on the model-view-controller paradigm. To create the view and
controller, the SAPUI5 runtime needs to know from where to load the related resources
(sap.ui.localResources); in this case from the relative sub-folder /xsjsmultiply. In this
example, you place the newly created instance of the xsjsMultiply view from the xsjsmultiply
sub-folder in an HTML element with the ID content. SAPUI5 supports different view types; here the
JS (JavaScript) view type is used.
○ HTML body: The HTML element with the ID content, in which you placed the view, needs to be
included in the HTML page. To do this, you add a <div> block with id="content" to the HTML body.
The <body> attribute class="sapUiBody" defines the SAPUI5 CSS class to be used, which ensures
that the page background and some other styles are properly set. The attribute
role="application" sets the WAI-ARIA landmark role.
7. Set up the SAPUI5 view displayed in the application user interface.

SAP HANA Developer Guide

460 PUBLIC Building UIs
 The SAPUI5 view for this tutorial is specified in the file xsjsMultiply.view.js; it displays a simple UI
with two text boxes that you can use to specify the numbers to use for the multiplication action.

sap.ui.jsview("xsjsmultiply.xsjsMultiply", {
getControllerName : function() {
return "xsjsmultiply.xsjsMultiply";
},
createContent : function(oController) {
var multiplyPanel = new sap.ui.commons.Panel().setText("XS Service
Test - Multiplication");

var layoutNew = new

sap.ui.commons.layout.MatrixLayout({width:"auto"});
multiplyPanel.addContent(layoutNew);
var oVal1 = new sap.ui.commons.TextField("val1",{tooltip: "Value
#1", editable:true});
var oVal2 = new sap.ui.commons.TextField("val2",{tooltip: "Value
#2", editable:true});
var oResult = new sap.ui.commons.TextView("result",{tooltip:
"Results"});
var oEqual = new sap.ui.commons.TextView("equal",{tooltip:
"Equals", text: " = "});
var oMult = new sap.ui.commons.TextView("mult",{tooltip: "Multiply
by", text: " * "});

//Attach a controller event handler to Value 1 Input Field

oVal1.attachEvent("liveChange", function(oEvent){
oController.onLiveChange(oEvent,oVal2); });
//Attach a controller event handler to Value 2 Input Field
oVal2.attachEvent("liveChange", function(oEvent){
oController.onLiveChange(oEvent,oVal1); });

layoutNew.createRow(oVal1, oMult, oVal2, oEqual, oResult );

return multiplyPanel;
}
});

8. Set up the SAPUI5 controller functions to handle the UI events.

The code described in this step must be added to the SAPUI5 view controller file
xsjsMultiply.controller.js.
a. Define the controller:

sap.ui.controller("xsjsmultiply.xsjsMultiply", {
});

b. Add the code that creates an event handler named onLiveChange.

The onLiveChange function has two parameters: Event and oVal, which are used in the jQuery.Ajax
call to the XSJS service at the specified URL. This is the event which is triggered every time the value is
changed in either of the text boxes displayed in the application UI.

onLiveChange: function(oEvent,oVal){
var aUrl = '/sap/hana/democontent/epm/services/multiply.xsjs?
cmd=multiply'+'&num1='
+escape(oEvent.getParameters().liveValue)
+'&num2='+escape(oVal.getValue());
jQuery.ajax({
url: aUrl,
method: 'GET',
dataType: 'json',
success: this.onCompleteMultiply,
error: this.onErrorCall });

SAP HANA Developer Guide

Building UIs PUBLIC 461
 },

If the AJAX call is successful, call a controller event named onCompleteMultiply; if the AJAX call is
not successful, call a controller event named onErrorCall.
c. Add the code that creates an event handler named onCompleteMultiply.
The onCompleteMultiply function accepts the response object as an input parameter called myTxt.
This text box will contain the result of the multiplication in clear text. Use the
sap.ui.core.format.NumberFormat to format the output as an integer and set the value back into
the oResult textView.

onCompleteMultiply: function(myTxt){
var oResult = sap.ui.getCore().byId("result");
if(myTxt==undefined){ oResult.setText(0); }
else{
jQuery.sap.require("sap.ui.core.format.NumberFormat");
var oNumberFormat =
sap.ui.core.format.NumberFormat.getIntegerInstance({
maxFractionDigits: 12,
minFractionDigits: 0,
groupingEnabled: true });
oResult.setText(oNumberFormat.format(myTxt)); }
},

d. Add the code that produces an error dialog if the event produces an error.
The onErrorCall function displays a message dialog (sap.ui.commons.MessageBox.show) in the
event of an error during the multiplication action provided by the XSJS service. The information
displayed in the error message is contained in jqXHR.responseText.

onErrorCall: function(jqXHR, textStatus, errorThrown){

sap.ui.commons.MessageBox.show(jqXHR.responseText,
"ERROR",
"Service Call Error" );
return;
}

The complete xsjsMultiply.controller.js file should look like the following example:

sap.ui.controller("xsjsmultiply.xsjsMultiply", {
onLiveChange: function(oEvent,oVal){
var aUrl = '/sap/hana/democontent/epm/services/multiply.xsjs?
cmd=multiply'+'&num1='
+escape(oEvent.getParameters().liveValue)
+'&num2='+escape(oVal.getValue());
jQuery.ajax({
url: aUrl,
method: 'GET',
dataType: 'json',
success: this.onCompleteMultiply,
error: this.onErrorCall });
},

onCompleteMultiply: function(myTxt){
var oResult = sap.ui.getCore().byId("result");
if(myTxt==undefined){ oResult.setText(0); }
else{
jQuery.sap.require("sap.ui.core.format.NumberFormat");
var oNumberFormat =
sap.ui.core.format.NumberFormat.getIntegerInstance({
maxFractionDigits: 12,
minFractionDigits: 0,
groupingEnabled: true });
oResult.setText(oNumberFormat.format(myTxt)); }

SAP HANA Developer Guide

462 PUBLIC Building UIs
 },

onErrorCall: function(jqXHR, textStatus, errorThrown){

sap.ui.commons.MessageBox.show(jqXHR.responseText,
"ERROR",
"Service Call Error" );
return;
}
});

9. Save all files.

10. Test your “xsjsMultiply” SAPUI5 application in a Web browser.

Select the index.html file and choose (Run) in the toolbar.

8.3.3 Tutorial: Consume an OData Service from SAPUI5

An OData service can be used to provide the data required for display in an SAPUI5 application.

Prerequisites

● You have installed the SAPUI5 tools included in the delivery unit (DU) SAPUI5_1.
● You have installed the SHINE delivery unit (DU); this DU contains the views
(sap.hana.democontent.epm.models:: AN_SALES_OVERVIEW_WO_CURR_CONV and
sap.hana.democontent.epm.models::AT_BUYER) specified in the OData service
(salesOrders.xsodata) that you want to consume with the SAPUI5 application you build in this tutorial.
● You have generated data to populate the tables and views provided by the SHINE DU and used in this
tutorial. You can generate the data with tools included in the SHINE DU.

Note
You might have to adjust the paths in the code examples provided to suit the folder/package hierarchy in
your SAP HANA repository, for example, to point to the underlying content (demonstration tables and
services) referenced in the tutorial.

SAP HANA Developer Guide

Building UIs PUBLIC 463
Context

You can bind a UI element in an SAPUI5 application to the data specified in an OData service. For example, you
can populate the contents of a table column displayed in an SAPUI5 application with the data stored in a
database table defined in an OData service.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/ide/editor
2. Create the basic structure for your application:
a. Navigate to the package in which you want to create the SAPUI5 application and from the context
menu choose Create Application.
b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter a package name, for example, odataBasic, and choose Create.
You now have a basic package structure to hold your application files. The root package for your new
application also contains the required application descriptors, which control access to the services and
data exposed by the new application.
3. Create a subpackage to store the SAPUI5 view and controller files:
a. Select the odataBasic package and from the context menu, choose New Package.
b. Enter a name, for example, odatabasic, and choose Create.
4. Create the SAPUI5 odataBasic view (view.js):
a. Select the odatabasic package and from the context menu choose New File.
b. Enter a name, for example, odataBasic.view.js, and choose Create.
5. Create the SAPUI5 odataBasic controller (controller.js):
a. Select the odatabasic package and from the context menu choose New File.
b. Enter a name, for example, odataBasic.controller.js, and choose Create.
6. Call the view from the index.html file.
Replace the entire content of the index.html file with the following:

<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<script src="/sap/ui5/1/resources/sap-ui-core.js" id="sap-ui-bootstrap"
data-sap-ui-libs="sap.ui.commons,sap.ui.table" data-sap-ui-
theme="sap_bluecrystal">
</script>
<script>
sap.ui.localResources("odatabasic");
var view = sap.ui.view({
id: "idodataBasic",
viewName: "odatabasic.odataBasic",
type: sap.ui.core.mvc.ViewType.JS
});
view.placeAt("content");
</script>

SAP HANA Developer Guide

464 PUBLIC Building UIs
 </head>
<body class="sapUiBody" role="application">
<div id="content"></div>
</body>
</html>

You have added the following elements to the index.html file:

○ Bootstrap script: SAPUI5 is implemented in JavaScript, so to load the SAPUI5 runtime library sapui-
core.js from the SAP HANA repository folder /sap/ui5/1/resources/ on the client you include
its bootstrap with a <script> tag. The data-sap-ui-theme attribute specifies the visual design to
be applied and the data-sap-ui-libs attribute the UI control libraries to be used.

Note
You need to declare any libraries you want the SAPUI5 application to use to render the data it
consumes. For this tutorial, you add sap.ui.table to the list of SAPUI5 libraries.

○ Application script: SAPUI5 is based on the model-view-controller paradigm. To create the view and
controller, the SAPUI5 runtime needs to know from where to load the related resources
(sap.ui.localResources); in this case from the relative sub-folder /odatabasic. In this example,
you place the newly created instance of the odataBasic view from the odatabasic sub-folder in an
HTML element with the ID content. SAPUI5 supports different view types; here the JS (JavaScript)
view type is used.
○ HTML body: The HTML element with the ID content, in which you placed the view, needs to be
included in the HTML page. To do this, you add a <div> block with id="content" to the HTML body.
The <body> attribute class="sapUiBody" defines the SAPUI5 CSS class to be used, which ensures
that the page background and some other styles are properly set. The attribute
role="application" sets the WAI-ARIA landmark role.
7. Connect the SAPUI5 table element to the OData service salesOrders.xsodata.
Add the following code to the SAPUI5 view controller file odataBasic.view.js.

sap.ui.jsview("odatabasic.odataBasic", {
/** Specifies the Controller belonging to this View.
* In the case that it is not implemented, or that "null" is returned,
this View does not have a Controller.
* @memberOf databasic.odataBasic
*/
getControllerName : function() {
return "odatabasic.odataBasic";
},
/** Is initially called once after the Controller has been instantiated.
It is the place where the UI is constructed.
* Since the Controller is given to this method, its event handlers can be
attached right away.
* @memberOf databasic.odataBasic
*/
createContent : function(oController) {

var oLayout = new

sap.ui.commons.layout.MatrixLayout({width:"100%"});

var oModel = new sap.ui.model.odata.ODataModel("/sap/hana/

democontent/epm/services/salesOrders.xsodata/", true);

var oControl;
this.oSHTable = new sap.ui.table.Table("soTable",{
visibleRowCount: 10,
});

SAP HANA Developer Guide

Building UIs PUBLIC 465
 this.oSHTable.setTitle("SALES_ORDER_HEADERS");

//Table Column Definitions

oControl = new
sap.ui.commons.TextView().bindProperty("text","SALESORDERID");
this.oSHTable.addColumn(new sap.ui.table.Column({label:new
sap.ui.commons.Label({text: "SALES_ORDER_ID"}),
template: oControl, sortProperty: "SALESORDERID",
filterProperty: "SALESORDERID", filterOperator:
sap.ui.model.FilterOperator.EQ, flexible: true }));

oControl = new
sap.ui.commons.TextView().bindProperty("text","PARTNERID.PARTNERID");
this.oSHTable.addColumn(new sap.ui.table.Column({label:new
sap.ui.commons.Label({text: "PARTNER_ID"}),
template: oControl, sortProperty: "PARTNERID", filterProperty:
"PARTNERID" }));

oControl = new sap.ui.commons.TextView().bindProperty("text","Buyer/

COMPANYNAME");
this.oSHTable.addColumn(new sap.ui.table.Column({label:new
sap.ui.commons.Label({text: "COMPANY"}),
template: oControl, sortProperty: "Buyer/CompanyName",
filterProperty: "Buyer/CompanyName", filterOperator:
sap.ui.model.FilterOperator.Contains }));

oControl = new
sap.ui.commons.TextView().bindText("GROSSAMOUNT",oController.numericFormatter)
;
oControl.setTextAlign("End");
this.oSHTable.addColumn(new sap.ui.table.Column({label:new
sap.ui.commons.Label({text: "GROSS_AMOUNT"}),
template: oControl, sortProperty: "GROSSAMOUNT",
filterProperty: "GROSSAMOUNT", hAlign: sap.ui.commons.layout.HAlign.End}));
oControl = new
sap.ui.commons.TextView().bindProperty("text","CURRENCY");
this.oSHTable.addColumn(new sap.ui.table.Column({label:new
sap.ui.commons.Label({text: "CURRENCY"}),
template: oControl, sortProperty: "CURRENCY", filterProperty:
"CURRENCY" }));
this.oSHTable.setModel(oModel);
var sort1 = new sap.ui.model.Sorter("SALESORDERID", true);

this.oSHTable.bindRows({
path: "/SalesOrderHeader",
parameters: {expand: "Buyer",
select:
"SALESORDERID,CURRENCY,GROSSAMOUNT,PARTNERID.PARTNERID,Buyer/COMPANYNAME"},
sorter: sort1
});

this.oSHTable.setTitle("Sales Orders");
oLayout.createRow(this.oSHTable);

return oLayout;
}
});

The code you insert performs the following actions:

○ Creates an object named oModel of type sap.ui.model.odata.ODataModel:

var oModel = new sap.ui.model.odata.ODataModel("/sap/hana/democontent/epm/

services/salesOrders.xsodata/", true);

SAP HANA Developer Guide

466 PUBLIC Building UIs
 ○ Sets the model named oModel to the UI table control named oSHTable:

this.oSHTable.setModel(oModel);

○ Creates a sorting mechanism (of type sap.ui.model.Sorter) which uses the column
SALESORDERID:

var sort1 = new sap.ui.model.Sorter("SALESORDERID", true);

○ Binds the table to the entity SalesOrderHeader in the OData service definition and adds the sorter
object to the binding:

this.oSHTable.bindRows({
path: "/SalesOrderHeader",
parameters: {expand: "Buyer",
select:
"SALESORDERID,CURRENCY,GROSSAMOUNT,PARTNERID.PARTNERID,Buyer/COMPANYNAME"},
sorter: sort1
});

8. Define the controller.

The odataBasic.controller.js file contains the view controller logic. In this example, the controller
does not contain any methods:

sap.ui.controller("odatabasic.odataBasic", {
});

9. Save all files.

10. Test your “odataBasic” SAPUI5 application in a Web browser.

Select the index.html file and choose (Run) in the toolbar.

11. Optional: Use the metadata that OData exposes to build the table columns dynamically.
You do not have to hard code the column definitions in the *.view.js file. To use Odata metdata to build
the columns dynamically, replace the list of hard-coded table-column definitions in the
odataBasic.view.js with the code that builds the table columns dynamically, as shown in the following
example.

sap.ui.jsview("odatabasic.odataBasic", {
/** Specifies the Controller belonging to this View.
* In the case that it is not implemented, or that "null" is returned,
this View does not have a Controller.

SAP HANA Developer Guide

Building UIs PUBLIC 467
 * @memberOf databasic.odataBasic
*/
getControllerName: function() {
return "odatabasic.odataBasic";
},
/** Is initially called once after the Controller has been instantiated.
It is the place where the UI is constructed.
* Since the Controller is given to this method, its event handlers can
be attached right away.
* @memberOf databasic.odataBasic
*/
createContent: function(oController) {
var oLayout = new sap.ui.commons.layout.MatrixLayout({
width: "100%"
});
var oModel = new sap.ui.model.odata.ODataModel("/sap/hana/
democontent/epm/services/salesOrders.xsodata/", true);
var oControl;
this.oSHTable = new sap.ui.table.Table("soTable", {
visibleRowCount: 10,
});
this.oSHTable.setTitle("SALES_ORDER_HEADERS");
//Table Column Definitions
var oMeta = oModel.getServiceMetadata();
var oControl;
for (var i = 0; i <
oMeta.dataServices.schema[0].entityType[0].property.length; i++) {
var property =
oMeta.dataServices.schema[0].entityType[0].property[i];
oControl = new sap.ui.commons.TextField().bindProperty("value",
property.name);
this.oSHTable.addColumn(new sap.ui.table.Column({
label: new sap.ui.commons.Label({
text: property.name
}),
template: oControl,
sortProperty: property.name,
filterProperty: property.name,
filterOperator: sap.ui.model.FilterOperator.EQ,
flexible: true,
width: "125px"
}));
}
this.oSHTable.setModel(oModel);
var sort1 = new sap.ui.model.Sorter("SALESORDERID", true);
this.oSHTable.bindRows("/SalesOrderHeader", sort1);
this.oSHTable.setTitle("Sales Orders");
oLayout.createRow(this.oSHTable);
return oLayout;
}
});

The code you insert performs the following actions:

○ Uses the function getServiceMetadata() to connect to the OData metadata object
○ Inspects the OData metadata and extracts the columns of the service defined in the property
dataServices.schema[0].entityType[0].property
○ Loops over this collection of OData metadata and creates a column for each property.name in the
service dynamically

SAP HANA Developer Guide

468 PUBLIC Building UIs
8.3.4 Tutorial: Consume an OData Service with the CREATE
Option

An OData service can be used to provide the data required for display in an SAPUI5 application.

Prerequisites

● You have installed the SAPUI5 tools included in the delivery unit (DU) SAPUI5_1.
● You have installed the SHINE delivery unit (DU); this DU contains the tables and OData services that you
want to consume with the SAPUI5 application you build in this tutorial.
● You have generated data to populate the tables and views provided by the SHINE delivery unit and used in
this tutorial. You can generate the data with tools included in the SHINE delivery unit.

Note
You might have to adjust the paths in the code examples provided to suit the folder/package hierarchy in
your SAP HANA repository, for example, to point to the underlying content (demonstration tables and
services) referenced in the tutorial.

Context

You can bind a UI element in an SAPUI5 application to the data specified in an OData service. For example, you
can populate the contents of table columns displayed in an SAPUI5 application with the data stored in a
database table defined in an OData service. In this tutorial, you learn how to build an SAPUI5 view that provides
input fields, which you can use to create a new record or update an existing record in a database table, for
example, using the OData create, update, and delete (CRUD) features.

SAP HANA Developer Guide

Building UIs PUBLIC 469
Procedure

1. Open the SAP HANA Web-based Development Workbench Editor tool.

The Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor
2. Create the basic structure for your application:
a. Navigate to the package in which you want to create the SAPUI5 application and from the context
menu choose Create Application.
b. Choose the Empty application (with XSAccess and XSApp) template.
c. Enter a package name, for example, userCRUD, and choose Create.
You now have a basic package structure to hold your application files. The root package for your new
application also contains the required application descriptors, which control access to the services and
data exposed by the new application.
3. Create a subpackage to store the SAPUI5 view and controller files:
a. Select the userCRUD package and from the context menu choose New Package.
b. Enter a name, for example, usercrud, and choose Create.
4. Create the SAPUI5 userCRUD view (view.js):
a. Select the usercrud package and from the context menu choose New File.
b. Enter a name, for example, userCRUD.view.js, and choose Create.
5. Create the SAPUI5 userCRUD controller (controller.js):
a. Select the usercrud package and from the context menu choose New File.
b. Enter a name, for example, userCRUD.controller.js, and choose Create.
6. Call the view from the index.html file.
Replace the entire content of the index.html file with the following:

<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<script src="/sap/ui5/1/resources/sap-ui-core.js" id="sap-ui-bootstrap"
data-sap-ui-libs="sap.ui.commons,sap.ui.table" data-sap-ui-
theme="sap_bluecrystal">
</script>
<script>
sap.ui.localResources("usercrud");
var view = sap.ui.view({
id: "iduserCRUD",
viewName: "usercrud.userCRUD",
type: sap.ui.core.mvc.ViewType.JS
});
view.placeAt("content");
</script>
</head>
<body class="sapUiBody" role="application">
<div id="content"></div>
</body>
</html>

You have added the following elements to the index.html file:

○ Bootstrap script: SAPUI5 is implemented in JavaScript, so to load the SAPUI5 runtime library sapui-
core.js from the SAP HANA repository folder /sap/ui5/1/resources/ on the client you include

SAP HANA Developer Guide

470 PUBLIC Building UIs
 its bootstrap with a <script> tag. The data-sap-ui-theme attribute specifies the visual design to
be applied and the data-sap-ui-libs attribute the UI control libraries to be used.

Note
You need to declare any libraries you want the SAPUI5 application to use to render the data it
consumes. For this tutorial, you add sap.ui.table to the list of SAPUI5 libraries.

○ Application script: SAPUI5 is based on the model-view-controller paradigm. To create the view and
controller, the SAPUI5 runtime needs to know from where to load the related resources
(sap.ui.localResources); in this case from the relative sub-folder /usercrud. In this example,
you place the newly created instance of the userCRUD view from the helloworldx sub-folder in an
HTML element with the ID content. SAPUI5 supports different view types; here the JS (JavaScript)
view type is used.
○ HTML body: The HTML element with the ID content, in which you placed the view, needs to be
included in the HTML page. To do this, you add a <div> block with id="content" to the HTML body.
The <body> attribute class="sapUiBody" defines the SAPUI5 CSS class to be used, which ensures
that the page background and some other styles are properly set. The attribute
role="application" sets the WAI-ARIA landmark role.
7. Set up the SAPUI5 user interface and bind it to an OData service.
The code you need to add to the userCRUD.view.js performs the following actions:
○ Adds three text-entry boxes (sap.ui.commons.TextField) to the SAPUI5 application interface
(First Name, Last Name, and Email)
○ Adds a Create Record button (sap.ui.commons.Button) to the SAPUI5 application interface
○ Binds the SAPUI5 view to the OData service user.xsodata

sap.ui.jsview("usercrud.userCRUD", {

getControllerName : function() {
return "usercrud.userCRUD";
},

createContent : function(oController) {

var oLayout = new sap.ui.commons.layout.MatrixLayout();

this.oModel = new sap.ui.model.odata.ODataModel("/sap/hana/
democontent/epm/services/user.xsodata/", true);

var updatePanel = new sap.ui.commons.Panel("updPanel").setText('New

User Record Details');
var layoutNew = new
sap.ui.commons.layout.MatrixLayout({width:"auto"});

var oVal1 = new sap.ui.commons.TextField("fName",{tooltip: "First

Name", width: "200px", editable:true});
var oVal2 = new sap.ui.commons.TextField("lName",{tooltip: "Last
Name", width: "200px", editable:true});
var oVal3 = new sap.ui.commons.TextField("email",{tooltip: "Email",
width: "200px", editable:true});
var oExcButton = new sap.ui.commons.Button({
text : "Create Record",
press : oController.callUserService });
layoutNew.createRow(new sap.ui.commons.Label({text: "First Name:
"}), oVal1 ); //oExcButton );
layoutNew.createRow(new sap.ui.commons.Label({text: "Last Name:
"}), oVal2 ); //oExcButton );
layoutNew.createRow(new sap.ui.commons.Label({text: "Email:
"}), oVal3, oExcButton );

SAP HANA Developer Guide

Building UIs PUBLIC 471
 updatePanel.addContent(layoutNew);
oLayout.createRow(updatePanel);

oTable = new sap.ui.table.Table("userTbl",{tableId: "tableID",

visibleRowCount: 10});
oTable.setTitle("Users");

//Table Column Definitions

var oMeta = this.oModel.getServiceMetadata();
var oControl;

for ( var i = 0; i <

oMeta.dataServices.schema[0].entityType[0].property.length; i++) {
var property =
oMeta.dataServices.schema[0].entityType[0].property[i];

oControl = new sap.ui.commons.TextField({change:

oController.updateService } ).bindProperty("value",property.name);
if(property.name === 'PERS_NO'){
oControl.setEditable(false);
}
oTable.addColumn(new sap.ui.table.Column({label:new
sap.ui.commons.Label({text: property.name}), template: oControl,
sortProperty: property.name, filterProperty: property.name, filterOperator:
sap.ui.model.FilterOperator.EQ, flexible: true, width: "125px" }));
}

oTable.setModel(this.oModel);
oTable.bindRows("/Users");
oTable.setTitle("Users" );
oTable.setEditable(true);

oLayout.createRow(oTable);
return oLayout;

}
});

The userCRUD.view.js file should display the UI view shown in the following example:

8. Set up the UI elements that the SAPUI5 application uses to handle create and update events.
The functions that handle the create and update events are defined in the SAPUI5 controller.js file.
a. Add a declaration for the oModel and set it to null.

SAP HANA Developer Guide

472 PUBLIC Building UIs
 This code ensures that the model instance is passed from the SAPUI5 view to the SAPUI5 controller.

sap.ui.controller("usercrud.userCRUD", {
oModel : null,

b. Set up the callUserService function to handle create events (create new records in a table).
The code required for this implementation of the callUserService function is shown in the following
example:

callUserService : function() {
var oModel = sap.ui.getCore().byId("userTbl").getModel();
var oEntry = {};
oEntry.PERS_NO = "0000000000";
oEntry.FIRSTNAME = sap.ui.getCore().byId("fName").getValue();
oEntry.LASTNAME = sap.ui.getCore().byId("lName").getValue();
oEntry.E_MAIL = sap.ui.getCore().byId("email").getValue();
oModel.setHeaders({"content-type" : "application/
json;charset=utf-8"});
oModel.create('/Users', oEntry, null, function() {
alert("Create successful");
}, function() {
alert("Create failed");
});
},

In this example, the callUserService function performs the following actions:

○ Provides access to the model object by means of the controller with a call to var oModel =
sap.ui.getCore().byId("userTbl").getModel();.
○ Creates a JSON object with the service fields: PERS_NO, FIRSTNAME, LASTNAME, and E_MAIL.
PERS_NO can have a fixed value 0000000000. The other fields should be read from the screen with
sap.ui.getCore().byId("<insert field id>").getValue();
○ Sets a custom header of “content-type” with the value “application/
json;charset=utf-8” in the model. This enables a call to the oModel.create function for the
entity /Users.
c. Set up the updateService function to handle update events (update records in a table).
The code required for this implementation of the updateService function is shown in the following
example:

updateService: function(Event) {
var oModel = sap.ui.getCore().byId("userTbl").getModel();
var index = Event.getSource().oParent.getIndex();
var oEntry = {};
oEntry.PERS_NO = sap.ui.getCore().byId("__field0-col0-
row"+index).getValue();
switch (Event.mParameters.id){
case "__field1-col1-row"+index:
oEntry.FIRSTNAME = Event.mParameters.newValue; break;
case "__field2-col2-row"+index:
oEntry.LASTNAME = Event.mParameters.newValue; break;
case "__field3-col3-row"+index:
oEntry.E_MAIL = Event.mParameters.newValue;
break;
}

var oParams = {};

oParams.fnSuccess = function(){ alert("Update successful");};
oParams.fnError = function(){alert("Update failed");};
oParams.bMerge = true;
oModel.setHeaders({"content-type" : "application/
json;charset=utf-8"});

SAP HANA Developer Guide

Building UIs PUBLIC 473
 oModel.update("/Users('"+oEntry.PERS_NO+"')", oEntry, oParams);

}
});

The updateService performs the following actions:

○ Accesses the model to read the index of the table for the changed record using
Event.getSource().oParent.getIndex().
○ Creates a JSON object with the service fields PERS_NO and whichever field was modified or
updated. You can access the fields in the table using the event parameter ID “__field<index>-
col<index>-row”+index, where index is the table index you read earlier, for example,
__field1-col1-row"+index.
○ Sets a custom header of “content-type” with the value “application/
json;charset=utf-8” in the model. Then you can call the oModel.update function for the
entity /Users.
9. Save all files.
10. Test your “userCRUD” SAPUI5 application in a Web browser.

a. Select the index.html file and choose (Run) in the toolbar.

b. Create a new record in the table referenced in the OData service.

c. Update an existing record in the table referenced in the OData service.

SAP HANA Developer Guide

474 PUBLIC Building UIs
9 Setting Up Roles and Privileges

Every user who wants to work directly with the SAP HANA database must have a database user with the
necessary privileges. Although privileges can be granted to users directly, roles are the standard way to
authorize users. A role is a collection of privileges.

Overview of Roles and Privileges

After users have successfully logged on to SAP HANA, they can do only those things they are authorized to do.
This is determined by the privileges that they have been granted. Several privilege types exist in the SAP HANA
database, for example system privileges, object privileges, and application privileges.

Privileges can be granted to users directly or indirectly through roles. Roles are the standard mechanism of
granting privileges as they allow you to implement complex, reusable authorization concepts that can be
modeled on business roles. It is possible to create roles as pure runtime objects that follow classic SQL
principles (catalog roles) or as design-time objects in the repository of the SAP HANA database (repository
roles). In general, repository roles are recommended as they offer more flexibility. For example, they can be
transported between systems. For more information, see Catalog Roles and Repository Roles Compared in the
SAP HANA Security Guide.

Note
Part of the logon process is user authentication. SAP HANA supports several authentication mechanisms,
including user name/password authentication and external authentication services such as SAML and
Kerberos. For more information, see SAP HANA Authentication and Single Sign-On in the SAP HANA Security
Guide.

Application Authorization

Application developers define application descriptors to specify how users accessing their applications are
authenticated and what authorization is required. For more information, see Creating the Application
Descriptors.

User Management

User administrators are responsible for creating database users and granting them the required roles and
privileges. For more information about creating and authorizing users, as well as other user provisioning tasks,
see User Provisioning in the SAP HANA Administration Guide.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 475
Related Information

Creating the Application Descriptors [page 47]

9.1 Create a Design-Time Role

You create a role in the SAP HANA repository using the form-based role editor of the SAP HANA Web-based
Development Workbench.

Prerequisites

● A shared project exists with a suitable package for storing roles.

● You have the role sap.hana.xs.ide.roles::EditorDeveloper.
● You have package privileges on the package in which you plan to create the role:
○ REPO.READ
○ REPO.EDIT_NATIVE_OBJECTS
○ REPO.ACTIVATE_NATIVE_OBJECTS
○ REPO.MAINTAIN_NATIVE_PACKAGES

Caution
Theoretically, a user with authorization to create and activate repository objects can change a role that
he has been granted. Once the role is activated, the user has the new privileges that he or she just
added. Therefore, it is important that roles in production systems are imported from a test or
development system and that changes to imported objects are not allowed. This danger is however not
specific to roles but also applies to other repository objects, for example, modeled views.

● You can select all the roles and privileges that you plan to grant to the new role. For this, you need either the
system privilege CATALOG READ or the actual role or privilege to be granted.
● You have granted to the technical user _SYS_REPO those privileges on catalog-only objects that you plan to
grant the new role. For more information, see Roles as Repository Objects.
● If you're using the SAP HANA Web-based Development Workbench for either the system database or a
tenant database in a multiple-container system, you have configured the internal SAP Web Dispatcher so
that it can dispatch HTTP requests coming into the system to the correct database on the basis of alias
DNS names. Every tenant database needs an alias. For more information, see Configure HTTP Access to
Multitenant Database Containers in the SAP HANA Administration Guide.

SAP HANA Developer Guide

476 PUBLIC Setting Up Roles and Privileges
Context

The design-time definition of a role is specified in a text file with the extension .hdbrole. You can create and
define a role in a simple text editor using the role domain-specific language (DSL). However, the Editor tool of
the SAP HANA Web-based Development Workbench provides you with a form-based editor.

Procedure

1. Open the Editor tool of the SAP HANA Web-based Development Workbench.
The URL depends on whether you are connecting to a single-container system or to a database in a
multiple-container system.

Option Description

Single-container system http://<host>:<port>/sap/hana/xs/ide/editor

System database of a multiple-con­ http://<host>:<port>/sap/hana/xs/ide/editor
tainer system

Tenant database in a multiple-con­ http://<alias_DNS_name_of_tenant_DB>:<port>/sap/

tainer system hana/xs/ide/editor

2. Enter your user name and password.

3. Navigate to the package that you want to create the role in.

4. From the context menu, choose New Role .

The New Role window appears.
5. Enter the role name and choose Create.
The system creates the file <rolename>.hdb and opens it in the form-based editor.
6. Select the roles and privileges that you want to grant to the new role:

○ Roles
You can grant both catalog roles and other design-time roles.
○ System privileges
○ Object privileges
You can grant privileges on both catalog objects and design-time objects. First, select the object that
you want to grant privileges on, then the required privileges.

Caution
Do not grant object privileges on a catalog object if it was created in design time. If you do, the next
time the design-time object is activated (which results in the creation of a new version of the catalog
object), the privilege on the original catalog object will be removed from the role. Always grant
privileges on design-time objects.

○ Analytic privileges
○ Package privileges
First, select the package that you want to grant privileges on, then the required privileges.
○ Application privileges

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 477
 Note
Application privileges are implemented using the application-privileges file (.xsprivileges).

7. Save the role.

The role is saved and activated.

Note
By default, roles and other objects that you can create and edit in the Editor tool are activated on saving.
If you do not want objects to be activated on saving, then select the option Enable Inactive Save in the
Editor settings. Once this option is enabled, the (Save without activating CTRL+I) button becomes
available.

Results

A user administrator can now grant the role to users. This is possible using the Security tool of the SAP HANA
Web-based Development Workbench or using the SAP HANA studio.

Related Information

Roles as Repository Objects [page 482]

System Privileges [page 494]
Object Privileges [page 499]
Analytic Privileges [page 504]
Package Privileges [page 506]
Application Privileges [page 507]
The Application-Privileges File [page 67]

9.1.1 Change a Design-Time Role

You can change a design-time role in the SAP HANA Web-based Development Workbench using either the
form-based role editor or the text editor.

Prerequisites

● You have the role sap.hana.xs.ide.roles::EditorDeveloper.

● You have package privileges on the package in which the role is located:

SAP HANA Developer Guide

478 PUBLIC Setting Up Roles and Privileges
 ○ REPO.READ
○ REPO.EDIT_NATIVE_OBJECTS
○ REPO.ACTIVATE_NATIVE_OBJECTS
○ REPO.MAINTAIN_NATIVE_PACKAGES

Caution
Theoretically, a user with authorization to create and activate repository objects can change a role that
he has been granted. Once the role is activated, the user has the new privileges that he or she just
added. Therefore, it is important that roles in production systems are imported from a test or
development system and that changes to imported objects are not allowed. This danger is however not
specific to roles but also applies to other repository objects, for example, modeled views.

● You can select all the roles and privileges that you plan to grant to the new role. For this, you need either the
system privilege CATALOG READ or the actual role or privilege to be granted.
● You have granted to the technical user _SYS_REPO those additional privileges on catalog-only objects that
you plan to grant to the role. For more information, see Roles as Repository Objects.
● If you're using the SAP HANA Web-based Development Workbench for either the system database or a
tenant database in a multiple-container system, you have configured the internal SAP Web Dispatcher so
that it can dispatch HTTP requests coming into the system to the correct database on the basis of alias
DNS names. Every tenant database needs an alias. For more information, see Configure HTTP Access to
Multitenant Database Containers in the SAP HANA Administration Guide.

Context

You can change the roles and privileges granted to an existing repository role. It is important that you do this in
the design-time version of the role, not the runtime version. Otherwise, any changes that you make will be
reverted the next time the design-time version is activated.

Note
The Editor tool of the SAP HANA Web-based Development Workbench also provides features for copying
and renaming repository objects. It is recommended that you use these features with care since users who
have already been granted the role may be impacted. For example, if you rename a role, it will still be granted
to users by its old name. This means that you will have to revoke the role by its old name and then grant it
again by its new name.

Procedure

1. Open the Editor tool of the SAP HANA Web-based Development Workbench.
The URL depends on whether you are connecting to a single-container system or to a database in a
multiple-container system.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 479
 Option Description

Single-container system http://<host>:<port>/sap/hana/xs/ide/editor

System database of a multiple-con­ http://<host>:<port>/sap/hana/xs/ide/editor
tainer system

Tenant database in a multiple-con­ http://<alias_DNS_name_of_tenant_DB>:<port>/sap/

tainer system hana/xs/ide/editor

2. Navigate to the role that you want to change.

3. From the context menu, choose Open With and then the desired editor: role editor or text editor.

Note
If the role definition contains syntax errors, it is not possible to open the form-based role editor. You
must edit the role in the text editor instead.

4. Make the required changes.

5. Save the role.
The role is saved and activated.

Note
By default, roles and other objects that you can create and edit in the Editor tool are activated on saving.
If you do not want objects to be activated on saving, then select the option Enable Inactive Save in the
Editor settings. Once this option is enabled, the (Save without activating CTRL+I) button becomes
available.

Results

The authorization of users who have been granted the role changes accordingly.

Related Information

Roles as Repository Objects [page 482]

9.1.2 Roles

A role is a collection of privileges that can be granted to either a database user or another role in runtime.

A role typically contains the privileges required for a particular function or task, for example:

● Business end users reading reports using client tools such as Microsoft Excel
● Modelers creating models and reports

SAP HANA Developer Guide

480 PUBLIC Setting Up Roles and Privileges
 ● Database administrators operating and maintaining the database and its users

Privileges can be granted directly to users of the SAP HANA database. However, roles are the standard
mechanism of granting privileges as they allow you to implement complex, reusable authorization concepts
that can be modeled on business roles.

Creation of Roles

Roles in the SAP HANA database can exist as runtime objects only (catalog roles), or as design-time objects
that become catalog objects on deployment (database artifact with file suffix .hdbrole).

In an SAP HANA XS classic environment, database roles are created in the built-in repository of the SAP HANA
database using either the SAP HANA Web Workbench or the SAP HANA studio. These are also referred to as
repository roles. In an SAP HANA XS advanced environment, design-time roles are created using the SAP Web
IDE and deployed using SAP HANA deployment infrastructure (SAP HANA DI).

Note
Due to the container-based model of HDI, where each container corresponds to a database schema, roles
are schema specific.

In SAP HANA XS advanced applications, database roles control access to database objects only (for example,
tables, views, and procedures). Application roles and role collections are used to control and define access to
applications. For more information about the authorization concept of XS advanced, see the
sectionAuthorization in SAP HANA XS Advanced in the SAP HANA Security Guide.

Role Structure

A role can contain any number of the following privileges:

● System privileges for general system authorization, in particular administration activities

● Object privileges (for example, SELECT, INSERT, UPDATE) on database objects (for example, schemas,
tables, views, procedures, and sequences)
● Analytic privileges on SAP HANA information models
● Package privileges on repository packages (for example, REPO.READ, REPO.EDIT_NATIVE_OBJECTS,
REPO.ACTIVATE_NATIVE_OBJECTS)
● Application privileges for enabling access to SAP HANA-based applications developed in an SAP HANA
XS classic environment

A role can also contain other roles.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 481
Roles Best Practices

For best performance of role operations, in particular, granting and revoking, keep the following basic rules in
mind:

● Create roles with the smallest possible set of privileges for the smallest possible group of users who can
share a role (principle of least privilege)
● Avoid granting object privileges at the schema level to a role if only a few objects in the schema are relevant
for intended users.
● Avoid creating and maintaining all roles as a single user. Use several role administrator users instead.

Tip
For more information about security, see the SAP HANA Security Guide on the SAP Help Portal.

9.1.2.1 Roles as Repository Objects

Roles created in the repository differ from roles created directly as runtime objects using SQL in several ways.

● What authorization does a user need to grant privileges to a role? [page 482]
● What about the WITH ADMIN OPTION and WITH GRANT OPTION parameters? [page 483]
● How are repository roles granted and revoked? [page 483]
● How are repository roles dropped? [page 484]
● Can changes to repository roles be audited? [page 484]

What authorization does a user need to grant privileges to a role?

According to the authorization concept of the SAP HANA database, a user can only grant a privilege to a user
directly or indirectly in a role if the following prerequisites are met:

● The user has the privilege him- or herself

● The user is authorized to grant the privilege to others (WITH ADMIN OPTION or WITH GRANT OPTION)

A user is also authorized to grant object privileges on objects that he or she owns.

The technical user _SYS_REPO is the owner of all objects in the repository, as well as the runtime objects that
are created on activation. This means that when you create a role as a repository object, you can grant the
following privileges:

● Privileges that have been granted to the technical user _SYS_REPO and that _SYS_REPO can grant further
This is automatically the case for system privileges, package privileges, analytic privileges, and application
privileges. Therefore, all system privileges, package privileges, analytic privileges, and application privileges
can always be granted in design-time roles.
● Privileges on objects that _SYS_REPO owns
_SYS_REPO owns all activated objects. Object privileges on non-activated runtime objects must be
explicitly granted to _SYS_REPO. It is recommended that you use a technical user to do this to ensure that

SAP HANA Developer Guide

482 PUBLIC Setting Up Roles and Privileges
 privileges are not dropped when the granting user is dropped (for example, because the person leaves the
company.

The following table summarizes the situation described above:

Privilege Action Necessary to Grant in Repository Role

System privilege None

Package privilege None

Analytic privilege None

Application privilege None

SQL object on activated object (for example, attribute view, None

analytic view)

SQL object privilege on runtime object (for example, repli­ Grant privilege to user _SYS_REPO with WITH GRANT OP­
cated table) TION

Note
Technically speaking, only the user _SYS_REPO needs the privileges being granted in a role, not the
database user who creates the role. However, users creating roles in the SAP HANA Web-based
Development Workbench must at least be able to select the privileges they want to grant to the role. For this,
they need either the system privilege CATALOG READ or the actual privilege to be granted.

What about the WITH ADMIN OPTION and WITH GRANT OPTION
parameters?

When you create a role using SQL (that is, as a runtime object), you can grant privileges with the additional
parameters WITH ADMIN OPTION or WITH GRANT OPTION. This allows a user who is granted the role to grant
the privileges contained within the role to other users and roles. However, if you are implementing your
authorization concept with privileges encapsulated within roles created in design time, then you do not want
users to grant privileges using SQL statements. For this reason, it is not possible to pass the parameters WITH
ADMIN OPTION or WITH GRANT OPTION with privileges when you model roles as repository objects.

Similarly, when you grant an activated role to a user, it is not possible to allow the user to grant the role further
(WITH ADMIN OPTION is not available).

How are repository roles granted and revoked?

It is not possible to grant and revoke activated design-time roles using the GRANT and REVOKE SQL
statements. Instead, roles are granted and revoked through the execution of the procedures
GRANT_ACTIVATED_ROLE and REVOKE_ACTIVATED_ROLE. Therefore, to be able to grant or revoke a role, a
user must have the object privilege EXECUTE on these procedures.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 483
How are repository roles dropped?

It is not possible to drop the runtime version of a role created in the repository using the SQL statement DROP
ROLE. To drop a repository role, you must delete it in the repository and activate the change. The activation
process deletes the runtime version of the role.

Can changes to repository roles be audited?

The auditing feature of the SAP HANA database allows you to monitor and record selected actions performed
in your database system. One action that is typically audited is changes to user authorization. If you are using
roles created in the repository to grant privileges to users, then you audit the creation of runtime roles through
activation with the audit action ACTIVATE REPOSITORY CONTENT.

9.1.2.2 Role Domain-Specific Language Syntax

The design-time definition of a role is specified in a text file with the extension .hdbrole. Roles are defined
using a domain-specific language (DSL).

Example

role Roles::example_role

extends role sap.example::role1

extends catalog role "CATROLE1", "CATROLE2"
{
system privilege: BACKUP ADMIN, USER ADMIN;

catalog sql object"SYSTEM"."TABLE2": SELECT;

catalog sql object "SYSTEM"."TABLE2": INSERT, UPDATE, DELETE;
sql object sap.example:VIEW1.attributeview,
sap.example:PROC1.hdbprocedure, sap.example:SEQ1.sequence: SELECT, DROP;
sql object sap.example:MY_VIEW.attributeview: DROP;
catalog schema "SYSTEM": SELECT;
schema [page 487] sap.example:app1.hdbschema: INSERT, UPDATE, DELETE;

analytic privilege: sap.example:sp1.analyticprivilege,

sap.example:AP2.analyticprivilege;
catalog analytic privilege: "sp3";

package sap.example: REPO.EDIT_NATIVE_OBJECTS;

package sap.example, sap.co: REPO.READ;
application privilege: sap.example::Execute, sap.example::Save;
}

A role definition specifies the following information:

● The package in which the role is created

● The role name
● Other roles granted to the role
● The privileges granted to the role

SAP HANA Developer Guide

484 PUBLIC Setting Up Roles and Privileges
The package and role name are specified as follows:

role <package_name>::<role_name>

The keywords listed below are used to specify which roles and privileges are granted to the role.

Note
The following general conventions apply when modeling a role definition using the role DSL:

● Comments start with a double-slash (//) or double-dash (--) and run to the end of the line.
● When specifying a reference to a design-time object, you must always specify the package name as
follows:
○ <package>::<object> if you are referencing a design-time role
○ <package>:<object>.<extension> if you are referencing any other design-time object
● When specifying multiple privileges on the same object or the same privilege on multiple objects, you
can do so individually line by line, or you can group them on a single line. Separate multiple objects
and/or multiple privileges using a comma.

extends role

extends role <package>.<package>::<role>

The keyword extends role allows you to include another design-time role in the role. If role A extends role B,
role B is granted to role A. This means that effectively A has all privileges that B has.

extends catalog role

extends catalog role "<role>"

The keyword extends catalog role allows you to include a catalog role in the role. If role A extends role B,
role B is granted to role A. This means that effectively A has all privileges that B has.

system privilege

{
system privilege: BACKUP ADMIN, USER ADMIN;
system privilege: LICENSE ADMIN;
}

The system privilege keyword allows you to grant a system privilege to the role.

For more information about all available system privileges, see System Privileges (Reference).

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 485
sql object

{
sql object sap.example:MY_VIEW.attributeview: DROP;
sql object sap.example:MY_PROCEDURE.hdbprocedure: DROP;
sql object sap.example:MY_VIEW.attributeview,
sap.example:MY_OTHER_VIEW.analyticview, sap.example:MY_THIRD_VIEW.analyticview:
SELECT;
}

The sql object keyword allows you to grant an object privilege on a design-time object (table, view,
procedure,sequence) to the role.

Tip
Many object types can be created in the repository. To verify the correct extension, refer to the object file in
the relevant package in the Project Explorer view (SAP HANA studio) or the file explorer (SAP HANA Web-
based Developer Workbench).

For more information about all available object privileges and to which object types they apply, see Object
Privileges (Reference).

catalog sql object

{
catalog sql object "MY_SCHEMA"."MY_TABLE": SELECT;
}

The catalog sql object keyword allows you to grant an object privilege on a catalog object (table, view,
procedure, sequence) to the role.

Note
Catalog objects must always be qualified with the schema name. Catalog objects must also be referenced
within double quotes, unlike design-time objects.

Caution
Do not grant object privileges on a catalog object if it was created in design time. If you do, the next time the
design-time object is activated (which results in the creation of a new version of the catalog object), the
privilege on the original catalog object will be removed from the role. Therefore, grant privileges on design-
time objects.

For more information about all available object privileges and to which object types they apply, see Object
Privileges (Reference).

SAP HANA Developer Guide

486 PUBLIC Setting Up Roles and Privileges
catalog schema

{
catalog schema "MY_SCHEMA": SELECT;
}

The catalog schema keyword allows you to grant a catalog schema to the role.

For more information about the object privileges that apply to schemas, see Object Privileges (Reference).

schema

{
schema sap.example:MY_OTHER_SCHEMA.hdbschema: SELECT;
}

The schema keyword allows you to grant a design-time schema to the role.

Note
You must still use the deprecated extension .schema if you are referring to a repository schema that uses
this extension.

For more information about the object privileges that apply to schemas, see Object Privileges (Reference).

package

{
package sap.example: REPO.READ;
}

The package keyword allows you to grant a repository package to the role.

For more information about all available package privileges, see Package Privileges.

analytic privilege

{
analytic privilege: sap.example:sp1.analyticprivilege,
sap.example:AP2.analyticprivilege;
}

The analytic privilege keyword allows you to grant a design-time analytic privilege to the role.

For more information, see Analytic Privileges.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 487
catalog analytic privilege

{
catalog analytic privilege: "sp3";
}

The catalog analytic privilege keyword allows you to grant an activated analytic privilege to the role.

For more information, see Analytic Privileges.

application privilege

{
application privilege: sap.example::Execute;
}

The application privilege keyword allows you to grant an application privilege to the role.

Note
Application privileges are implemented using the application-privileges file (.xsprivileges).

For more information, see Application Privileges.

Related Information

System Privileges (Reference) [page 494]

Object Privileges (Reference) [page 500]
Package Privileges [page 506]
Analytic Privileges [page 504]
Application Privileges [page 507]
The Application-Privileges File [page 67]

9.1.2.3 Custom Role for Developers

Create a custom role for developers so that you can to grant developers all required privileges quickly and
efficiently.

A role enables you to assign various types of privileges to a user, for example: SQL privileges, analytic
privileges, system privileges, as well as application and package privileges. You can also restrict the type of
privilege, for example, to SELECT, INSERT or UPDATE statements (or any combination of desired statements).
You can use an existing role as the basis for a new, extended, custom role. The privileges granted by an
extended role include all the privileges specified in all the roles that are used as the basis of the extended role
plus any additional privileges defined in the new extended role itself.

SAP HANA Developer Guide

488 PUBLIC Setting Up Roles and Privileges
 Note
It is not possible to restrict the privileges granted by the existing role that you are extending. For example, if
role A extends role B, role A will always include all the privileges specified in role B.

The following example shows how to create a DEVELOPMENT role as a design-time object. Note that a role-
definition file must have the suffix .hdbrole, for example, MyRoleDefinition.hdbrole.

Tip
File extensions are important. If you are using SAP HANA studio to create artifacts in the SAP HANA
repository, the file-creation wizard adds the required file extension automatically and, if appropriate, enables
direct editing of the new file in the corresponding editor.

After activating the design-time role definition, you can grant the resulting runtime role object to application
developers, for example, by executing the _SYS_REPO procedure GRANT_ACTIVATED_ROLE. The call requires
the parameters: ROLENAME (the name of the runtime role object you want to assign) and USERNAME (the name
of the user to whom you want to assign the new runtime role).

call “_SYS_REPO”.“GRANT_ACTIVATED_ROLE”
('acme.com.data::MyUserRole','GranteeUserName');

The example role illustrated in this topic defines the following privileges for the SAP HANA application
developer:

● Schema privileges:
○ _SYS_BIC
SELECT and EXECUTE for all tables
● Object privileges:
○ Schema _SYS_BI
○ SELECT privilege for all BIMC_* tables
○ UPDATE, INSERT, and DELETE privilege for M_* tables
○ Catalog object REPOSITORY_REST (SYS)
EXECUTE privilege
● Analytic privileges:
○ _SYS_BI_CP_ALL
SELECT for the data preview on the views
● Design-time privileges:
○ Package privileges:
○ For the root package
REPO.MAINTAIN_NATIVE_PACKAGES
○ For packages containing application content
REPO.EDIT_NATIVE_OBJECTS
REPO.ACTIVATE_NATIVE_OBJECTS
○ Application privileges:

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 489
 Application privileges are used to authorize user (and client) access to an application, for example, to
start the application or perform administrative actions in the application. When creating a role for
developers, make sure that the developers have (at least) the following application privileges:
○ Execute and Save privileges for the applications the developers are assigned to work on. The
application privileges can be defined in a .xsprivileges file, which must reside in application
package to which the defined privileges apply.
○ The privileges granted with the debugger role that is included with SAP HANA XS.

Note
It is also possible to grant application privileges in SAP HANA studio, for example, using the list of
privileges displayed in the Application Privileges tab in the Security [Users | Roles] runtime area.
To grant (or revoke) application privileges, the granting (or revoking) user must also have the object
privilege Execute for the GRANT_APPLICATION_PRIVILEGE or REVOKE_APPLICATION_PRIVILEGE
procedure respectively.

● Additional privileges
User _SYS_REPO requires the SELECT privilege on <schema_where_tables_reside> to enable the
activation and data preview of information views.

Example
Application-Development Role-Definition Example

role <package_name>::DEVELOPMENT
// extends role com.acme::role1
// extends catalog role "CATROLE1", "CATROLE2"
{
// system privileges
// system privilege: BACKUP ADMIN, USER ADMIN;
// schema privileges
catalog schema "_SYS_BIC": SELECT, EXECUTE;
// sql object privileges
// privileges on the same object may be split up in several lines
catalog sql object "SYS"."REPOSITORY_REST": EXECUTE;
catalog sql object "_SYS_BI"."BIMC_ALL_CUBES": SELECT;
catalog sql object "_SYS_BI"."BIMC_CONFIGURATION": SELECT;
catalog sql object "_SYS_BI"."BIMC_DIMENSIONS": SELECT;
catalog sql object "_SYS_BI"."BIMC_PROPERTIES": SELECT;
catalog sql object "_SYS_BI"."BIMC_VARIABLE": SELECT;
catalog sql object "_SYS_BI"."BIMC_VARIABLE_ASSIGNMENT": SELECT;
catalog sql object "_SYS_BI"."BIMC_VARIABLE_VALUE": SELECT;
catalog sql object "_SYS_BI"."M_CONTENT_MAPPING": UPDATE, INSERT, DELETE;
catalog sql object "_SYS_BI"."M_FISCAL_CALENDAR": UPDATE, INSERT, DELETE;
catalog sql object "_SYS_BI"."M_IMPORT_SERVER_CONFIG": UPDATE, INSERT, DELETE;
catalog sql object "_SYS_BI"."M_REPLICATION_EXCEPTIONS": UPDATE, INSERT,
DELETE;
catalog sql object "_SYS_BI"."M_SCHEMA_MAPPING": UPDATE, INSERT, DELETE;
catalog sql object "_SYS_BI"."M_TIME_DIMENSION": UPDATE, INSERT, DELETE;
catalog sql object "_SYS_BI"."M_TIME_DIMENSION _MONTH": UPDATE, INSERT, DELETE;
catalog sql object "_SYS_BI"."M_TIME_DIMENSION _WEEK": UPDATE, INSERT, DELETE;
catalog sql object "_SYS_BI"."M_TIME_DIMENSION _YEAR": UPDATE, INSERT, DELETE;
catalog sql object "_SYS_BI"."M_USER_PERSONALIZATION": UPDATE, INSERT, DELETE;
// analytic privileges
catalog analytic privilege: "_SYS_BI_CP_ALL";
// design time privileges
package com.acme: REPO.MAINTAIN_NATIVE_PACKAGES;
package com.acme.myapps: REPO.EDIT_NATIVE_OBJECTS;
package com.acme.myapps: REPO.ACTIVATE_NATIVE_OBJECTS;
application privilege: com.acme.myapps.app1::Execute, com.acme.xs.app1::Save;
application privilege: com.acme.myapps.debugger::Execute;

SAP HANA Developer Guide

490 PUBLIC Setting Up Roles and Privileges
 }

Related Information

Roles as Repository Objects [page 482]

Create a Design-Time Role [page 476]
The Application-Privileges File [page 67]
Privileges [page 491]

9.1.3 Privileges

Several privilege types are used in SAP HANA (system, object, analytic, package, and application).

Privilege Type Applicable To Target User Description

System privilege System, database Administrators, devel­ System privileges control general system activi­
opers ties. They are mainly used for administrative
purposes, such as creating schemas, creating
and changing users and roles, performing data
backups, managing licenses, and so on.

System privileges are also used to authorize ba­

sic repository operations.

System privileges granted to users in a particu­

lar tenant database authorize operations in that
database only. The only exception is the system
privilege DATABASE ADMIN. This system privi­
lege can only be granted to users of the system
database. It authorizes the execution of opera­
tions on individual tenant databases. For exam­
ple, a user with DATABASE ADMIN can create
and drop tenant databases, change the data­
base-specific properties in configuration (*.ini)
files, and perform database-specific backups.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 491
Privilege Type Applicable To Target User Description

Object privilege Database objects End users, technical Object privileges are used to allow access to
(schemas, tables, users and modification of database objects, such as
views, procedures and tables and views. Depending on the object type,
so on) different actions can be authorized (for exam­
ple, SELECT, CREATE ANY, ALTER, DROP, and
so on).

Schema privileges are object privileges that are

used to allow access to and modification of
schemas and the objects that they contain.

Source privileges are object privileges that are

used to restrict access to and modification of
remote data sources, which are connected
through SAP HANA smart data access.

Object privileges granted to users in a particular

database authorize access to and modification
of database objects in that database only. That
is, unless cross-database access has been ena­
bled for the user. This is made possible through
the association of the requesting user with a re­
mote identity on the remote database. For more
information, see Cross-Database Authorization
in Tenant Databases in the SAP HANA Security
Guide.

Analytic privilege Analytic views End users Analytic privileges are used to allow read access
to data in SAP HANA information models (that
is, analytic views, attribute views, and calcula­
tion views) depending on certain values or com­
binations of values. Analytic privileges are eval­
uated during query processing.

Analytic privileges granted to users in a particu­

lar database authorize access to information
models in that database only.

SAP HANA Developer Guide

492 PUBLIC Setting Up Roles and Privileges
 Privilege Type Applicable To Target User Description

Package privilege Packages in the classic Application and con­ Package privileges are used to allow access to
repository of the SAP tent developers work­ and the ability to work in packages in the classic
HANA database ing in the classic SAP repository of the SAP HANA database.
HANA repository
Packages contain design time versions of vari­
ous objects, such as analytic views, attribute
views, calculation views, and analytic privileges.

Package privileges granted to users in a particu­

lar database authorize access to and the ability
to work in packages in the repository of that da­
tabase only.

Note
With SAP HANA XS advanced, source code
and web content are not versioned and
stored in the SAP HANA database, so pack­
age privileges are not used in this context.
For more information, see Authorization in
SAP HANA XS Advanced.

Application privilege SAP HANA XS classic Application end users, Developers of SAP HANA XS classic applica­
applications technical users (for tions can create application privileges to author­
SQL connection con­ ize user and client access to their application.
figurations) They apply in addition to other privileges, for ex­
ample, object privileges on tables.

Application privileges can be granted directly to

users or roles in runtime in the SAP HANA stu­
dio. However, it is recommended that you grant
application privileges to roles created in the re­
pository in design time.

Note
With SAP HANA XS advanced, application
privileges are not used. Application-level au­
thorization is implemented using OAuth and
authorization scopes and attributes. For
more information, see Authorization in SAP
HANA XS Advanced.

Note
In the SAP HANA studio, an additional privilege type can be granted. Privileges on users are SQL privileges
that users can grant on their user. ATTACH DEBUGGER is the only privilege that can be granted on a user.

For example, User A can grant User B the privilege ATTACH DEBUGGER to allow User B debug SQLScript
code in User A's session. User A is only user who can grant this privilege. Note that User B also needs the
object privilege DEBUG on the relevant SQLScript procedure.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 493
 For more information, see Debug an External Session in the SAP HANA Developer Guide .

9.1.3.1 System Privileges

System privileges control general system activities.

System privileges are mainly used to authorize users to perform administrative actions, including:

● Creating and deleting schemas

● Managing users and roles
● Performing data backups
● Monitoring and tracing
● Managing licenses

System privileges are also used to authorize basic repository operations, for example:

● Importing and exporting content

● Maintaining delivery units (DU)

In a system with multitenant database containers, system privileges granted to users in a particular database
container authorize operations in that database only. The only exception is the system privilege DATABASE
ADMIN. This system privilege can only be granted to users of the system database. It authorizes the execution
of operations on individual tenant databases. For example, a user with DATABASE ADMIN can create and drop
tenant databases, change the database-specific properties in configuration (*.ini) files, and perform database-
specific or full-system data backups.

For more information about the individual system privileges available, see System Privileges (Reference).

Related Information

System Privileges (Reference) [page 494]

9.1.3.1.1 System Privileges (Reference)

System privileges control general system activities.

General System Privileges

System privileges are used to restrict administrative tasks. The following table describes the supported system
privileges in an SAP HANA database.

SAP HANA Developer Guide

494 PUBLIC Setting Up Roles and Privileges
 System Privilege Description

ADAPTER ADMIN Controls the execution of the following adapter-related com­

mands: CREATE ADAPTER, DROP ADAPTER and ALTER
ADAPTER. It also allows access to ADAPTERS and
ADAPTER_LOCATIONS system views.

AGENT ADMIN Controls the execution of the following agent-related com­

mands: CREATE AGENT, DROP AGENT, and ALTER AGENT.
It also allows access to AGENTS and ADAPTER_LOCATIONS
system views.

AUDIT ADMIN Controls the execution of the following auditing-related com­

mands: CREATE AUDIT POLICY, DROP AUDIT POLICY and
ALTER AUDIT POLICY and the changes of the auditing con­
figuration. It also allows access to AUDIT_LOG system view.

AUDIT OPERATOR Authorizes the execution of the following command: ALTER

SYSTEM CLEAR AUDIT LOG. It also allows access to AU­
DIT_LOG system view.

BACKUP ADMIN Authorizes BACKUP and RECOVERY commands for defining

and initiating backup and recovery procedures. It also au­
thorizes changing of system configuration options with re­
spect to backup and recovery.

BACKUP OPERATOR Authorizes the BACKUP command to initiate a backup.

CATALOG READ Authorizes users to have unfiltered read-only access to all

system views.

Normally, the content of these views is filtered based on the

privileges of the accessing user.

CERTIFICATE ADMIN Authorizes the changing of certificates and certificate col­

lections that are stored in the database.

CREATE R SCRIPT Authorizes the creation of a procedure using the language R.

CREATE REMOTE SOURCE Authorizes the creation of remote data sources using the
CREATE REMOTE SOURCE command.

CREATE SCENARIO Controls the creation of calculation scenarios and cubes

(calculation database).

CREATE SCHEMA Authorizes the creation of database schemas using the CRE­
ATE SCHEMA command.

By default each user owns one schema, with this privilege

the user is allowed to create additional schemas.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 495
System Privilege Description

CREATE STRUCTURED PRIVILEGE Authorizes the creation of Structured Privileges (Analytical

Privileges).

Only the owner of an Analytical Privilege can further grant or

revoke that privilege to other users or roles.

CREDENTIAL ADMIN Authorizes the credential commands: CREATE/ALTER/

DROP CREDENTIAL.

DATA ADMIN Authorizes reading all data in the system views. It also ena­
bles execution of any Data Definition Language (DDL) com­
mands in the SAP HANA database.

A user with this privilege cannot select or change data

stored tables for which they do not have access privileges,
but they can drop tables or modify table definitions.

DATABASE ADMIN Authorizes all commands related to tenant databases, such

as CREATE, DROP, ALTER, RENAME, BACKUP, and RECOV­
ERY.

EXPORT Authorizes export activity in the database via the EXPORT

TABLE command.

Beside this privilege, the user requires the SELECT privilege

on the source tables to be exported.

EXTENDED STORAGE ADMIN Required to manage SAP HANA dynamic tiering and create
extended storage.

IMPORT Authorizes the import activity in the database using the IM­
PORT commands.

Beside this privilege, the user requires the INSERT privilege

on the target tables to be imported.

INIFILE ADMIN Authorizes changing of system settings.

LICENSE ADMIN Authorizes the SET SYSTEM LICENSE command to install a

new license.

LOG ADMIN Authorizes the ALTER SYSTEM LOGGING [ON|OFF] com­

mands to enable or disable the log flush mechanism.

MONITOR ADMIN Authorizes the ALTER SYSTEM commands for events.

OPTIMIZER ADMIN Authorizes the ALTER SYSTEM commands concerning SQL

PLAN CACHE and ALTER SYSTEM UPDATE STATISTICS
commands, which influence the behavior of the query opti­
mizer.

SAP HANA Developer Guide

496 PUBLIC Setting Up Roles and Privileges
 System Privilege Description

RESOURCE ADMIN This privilege authorizes commands concerning system re­

sources, for example ALTER SYSTEM RECLAIM DATAVO­
LUME and ALTER SYSTEM RESET MONITORING VIEW. It
also authorizes many of the commands available in the Man­
agement Console.

ROLE ADMIN This privilege authorizes the creation and deletion of roles
using the CREATE ROLE and DROP ROLE commands. It also
authorizes the granting and revocation of roles using the
GRANT and REVOKE commands.

Activated repository roles, meaning roles whose creator is

the predefined user _SYS_REPO, can neither be granted to
other roles or users nor dropped directly. Not even users
with the ROLE ADMIN privilege can do so. Check the docu­
mentation concerning activated objects.

SAVEPOINT ADMIN Authorizes the execution of a save point process using the
ALTER SYSTEM SAVEPOINT command.

SCENARIO ADMIN Authorizes all calculation scenario-related activities (includ­

ing creation).

SERVICE ADMIN Authorizes the ALTER SYSTEM [START|CANCEL|RECON­

FIGURE] commands.

This privilege is for administering system services of the da­

tabase

SESSION ADMIN Authorizes the ALTER SYSTEM commands concerning ses­

sions to stop or disconnect a user session or to change ses­
sion variables.

SSL ADMIN Controls the execution of the following commands: SET

pse_store_name PURPOSE SSL. It also allows access to the
PSES system view.

STRUCTUREDPRIVILEGE ADMIN Authorizes the creation, reactivation, and dropping of struc­

tured privileges.

TENANT ADMIN Authorizes the tenant operations performed by the ALTER

SYSTEM [RESUME|SUSPEND] TENANT commands.

TABLE ADMIN Authorizes the LOAD/UNLOAD/MERGE of tables and its ta­

ble placement.

TRACE ADMIN Authorizes the ALTER SYSTEM [CLEAR|REMOVE] TRACES

commands for operations on database trace files and au­
thorizes changing trace system settings.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 497
System Privilege Description

TRUST ADMIN Authorizes commands to update the trust store.

USER ADMIN Authorizes the creation and modification of users using the
CREATE USER, ALTER USER, and DROP USER commands.

VERSION ADMIN Authorizes the ALTER SYSTEM RECLAIM VERSION SPACE

command of the multi-version concurrency control (MVCC)
mechanism.

WORKLOAD ADMIN Authorizes execution of the workload class and mapping

commands: CREATE WORKLOAD CLASS, ALTER WORK­
LOAD CLASS, DROP WORKLOAD CLASS, CREATE WORK­
LOAD MAPPING, ALTER WORKLOAD MAPPING, and DROP
WORKLOAD MAPPING

WORKLOAD ANALYZE ADMIN Used by Analyze Workload, Capture Workload, and Replay
Workload apps when performing workload analysis.

WORKLOAD CAPTURE ADMIN Authorizes access to monitoring view M_WORKLOAD_CAP­

TURES to see the current status of capturing and captured
workloads, as well of execution of actions with built-in proce­
dure WORKLOAD_CAPTURE

WORKLOAD REPLAY ADMIN Authorizes access to monitoring views M_WORKLOAD_RE­

PLAY_PREPROCESSES and M_WORKLOAD_REPLAYS to
see current status of preprocessing, preprocessed, replay­
ing, and replayed workloads, as well as execution of actions
with the built-in procedure WORKLOAD_REPLAY

<identifier>.<identifier> Components of the SAP HANA database can create new

system privileges. These privileges use the component-
name as first identifier of the system privilege and the com­
ponent-privilege-name as the second identifier.

Note
Additional system privileges (shown as <identifier>.<identifier> above) may exist and be required in
conjunction with SAP HANA options and capabilities such as SAP HANA smart data integration. For more
information, see SAP HANA Options and Capabilities on SAP Help Portal.

Repository System Privileges

Note
The following privileges authorize actions on individual packages in the SAP HANA repository, used in the
SAP HANA Extended Services (SAP HANA XS) classic development model. With SAP HANA XS advanced,

SAP HANA Developer Guide

498 PUBLIC Setting Up Roles and Privileges
 source code and web content are no longer versioned and stored in the repository of the SAP HANA
database.

System Privilege Description

REPO.EXPORT Authorizes the export of delivery units for example

REPO.IMPORT Authorizes the import of transport archives

REPO.MAINTAIN_DELIVERY_UNITS Authorizes the maintenance of delivery units (DU, DU vendor and system vendor
must be the same

REPO.WORK_IN_FOREIGN_WORK­ Authorizes work in a foreign inactive workspace

SPACE

REPO.CONFIGURE Authorize work with SAP HANA Change Recording, which is part of SAP HANA
Application Lifecycle Management
REPO.MODIFY_CHANGE

REPO.MODIFY_OWN_CONTRIBUTION

REPO.MODIFY_FOREIGN_CONTRIBU­
TION

9.1.3.2 Object Privileges

Object privileges are SQL privileges that are used to allow access to and modification of database objects.

For each SQL statement type (for example, SELECT, UPDATE, or CALL), a corresponding object privilege exists.
If a user wants to execute a particular statement on a simple database object (for example, a table), he or she
must have the corresponding object privilege for either the actual object itself, or the schema in which the
object is located. This is because the schema is an object type that contains other objects. A user who has
object privileges for a schema automatically has the same privileges for all objects currently in the schema and
any objects created there in the future.

Object privileges are not only grantable for database catalog objects such as tables, views and procedures.
Object privileges can also be granted for non-catalog objects such as development objects in the repository of
the SAP HANA database.

Initially, the owner of an object and the owner of the schema in which the object is located are the only users
who can access the object and grant object privileges on it to other users.

An object can therefore be accessed only by the following users:

● The owner of the object

● The owner of the schema in which the object is located
● Users to whom the owner of the object has granted privileges
● Users to whom the owner of the parent schema has granted privileges

Caution
The database owner concept stipulates that when a database user is deleted, all objects created by that
user and privileges granted to others by that user are also deleted. If the owner of a schema is deleted, all
objects in the schema are also deleted even if they are owned by a different user. All privileges on these
objects are also deleted.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 499
Authorization Check on Objects with Dependencies

The authorization check for objects defined on other objects (that is, stored procedures and views) is more
complex. In order to be able to access an object with dependencies, both of the following conditions must be
met:

● The user trying to access the object must have the relevant object privilege on the object as described
above.
● The user who created the object must have the required privilege on all underlying objects and be
authorized to grant this privilege to others.

If this second condition is not met, only the owner of the object can access it. He cannot grant privileges on it to
any other user. This cannot be circumvented by granting privileges on the parent schema instead. Even if a user
has privileges on the schema, he will still not be able to access the object.

Note
This applies to procedures created in DEFINER mode only. This means that the authorization check is run
against the privileges of the user who created the object, not the user accessing the object. For procedures
created in INVOKER mode, the authorization check is run against the privileges of the accessing user. In this
case, the user must have privileges not only on the object itself but on all objects that it uses.

Tip
The SAP HANA studio provides a graphical feature, the authorization dependency viewer, to help
troubleshoot authorization errors for object types that typically have complex dependency structures:
stored procedures and calculation views.

For more information about resolving authorization errors with the authorization dependency viewer, see
Resolve Errors Using the Authorization Dependency Viewer in the SAP HANA Administration Guide .

For more information about the object privileges available in SAP HANA and for which objects they are relevant,
see Object Privileges (Reference).

Related Information

Object Privileges (Reference) [page 500]

9.1.3.2.1 Object Privileges (Reference)

Object privileges are used to allow access to and modification of database objects, such as tables and views.

The following table describes the supported object privileges in a HANA database.

SAP HANA Developer Guide

500 PUBLIC Setting Up Roles and Privileges
 Object Privilege Command Types Applies to Privilege Description

ALL PRIVILEGES DDL & DML ● Tables This privilege is a collection

● Views of all Data Definition Lan­
guage(DDL) and Data Manip­
ulation Language(DML) privi­
leges that the grantor cur­
rently possesses and is al­
lowed to grant further. The
privilege it grants is specific
to the particular object being
acted upon.

This privilege collection is dy­

namically evaluated for the
given grantor and object.

ALTER DDL ● Schemas Authorizes the ALTER com­

● Tables mand for the object.
● Views
● Functions/procedures

CREATE ANY DDL ● Schemas Authorizes all CREATE com­

mands for the object.

CREATE VIRTUAL FUNC­ DDL ● Remote sources Authorizes creation of virtual

TION functions (REFERENCES
privilege is also required)

CREATE VIRTUAL FUNC­ DDL ● Schemas Authorizes creation of virtual

TION PACKAGE function packages.

CREATE VIRTUAL TABLE DDL ● Remote sources Authorizes the creation of

proxy tables pointing to re­
mote tables from the source
entry

CREATE TEMPORARY TABLE DDL ● Schemas Authorizes the creation of a

temporary local table, which
can be used as input for pro­
cedures, even if the user
does not have the CREATE
ANY privilege for the
schema.

DEBUG DML ● Schemas Authorizes debug-functional­

● Calculation Views ity for the procedure or cal­
● Functions/procedures culation view or for the pro­
cedures and calculation
views of a schema.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 501
Object Privilege Command Types Applies to Privilege Description

DELETE DML ● Schemas Authorizes the DELETE and

● Tables TRUNCATE commands for
● Views the object.
● Functions/procedures
While DELETE applies to
views, it only applies to up­
datable views (that is, views
that do not use a join, do not
contain a UNION, and do not
use aggregation).

DROP DDL ● Schemas Authorizes the DROP com­

● Tables mands for the object.
● Views
● Sequences
● Functions/procedures
● Remote sources

EXECUTE DML ● Schemas Authorizes the execution of

● Functions/procedures an SQLScript function or a
database procedure using
the CALLS or CALL com­
mand respectively. It also al­
lows a user to execute a vir­
tual function.

INDEX DDL ● Schemas Authorizes the creation,

● Tables modification or dropping of
indexes for the object

INSERT DML ● Schemas Authorizes the INSERT com­

● Tables mand for the object.
● Views
The INSERT and UPDATE
privilege are both required on
the object to allow the RE­
PLACE and UPSERT com­
mands to be used.

While INSERT applies to

views, it only applies to up­
datable views (that is, views
that do not use a join, do not
contain a UNION, and do not
use aggregation).

SAP HANA Developer Guide

502 PUBLIC Setting Up Roles and Privileges
 Object Privilege Command Types Applies to Privilege Description

REFERENCES DDL ● Schemas Authorizes the usage of all

● Tables tables in this schema or this
table in a foreign key defini-
tion, or the usage of a per­
sonal security environment
(PSE) for a certain purpose.
It also allows a user to refer­
ence a virtual function pack­
age.

SELECT DML ● Schemas Authorizes the SELECT com­

● Tables mand for this object or the
● Views usage of a sequence.
● Sequences

SELECT CDS METADATA DML ● Schemas Authorizes access to CDS

● Tables metadata from the catalog

SELECT METADATA DML ● Schemas Authorizes access to the

● Tables complete metadata of all ob­
jects in a schema (including
procedure and view defini-
tions), thus showing the exis­
tence of objects that may be
located in other schemas.

TRIGGER DDL ● Schemas Authorizes the CREATE

● Tables TRIGGER/DROP TRIGGER
command for the specified
table or the tables in the
specified schema.

UPDATE DML ● Schemas Authorizes the UPDATE/

● Tables LOAD/UNLOAD/LOCK TA­
● Views BLE command for that ob­
ject.

While UPDATE applies to

views, it only applies to up­
datable views (that is, views
that do not use a join, do not
contain a UNION, and do not
use aggregation).

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 503
Object Privilege Command Types Applies to Privilege Description

<identifier>.<identifi DDL Components of the SAP

er> HANA database can create
new object privileges. These
privileges use the compo­
nent-name as first identifier
of the system privilege and
the component-privilege-
name as the second identi­
fier.

Note
Additional object privileges (shown as <identifier>.<identifier> above) may exist and be required in
conjunction with SAP HANA options and capabilities such as SAP HANA smart data integration. For more
information, see SAP HANA Options and Capabilities on SAP Help Portal.

9.1.3.3 Analytic Privileges

Analytic privileges grant different users access to different portions of data in the same view based on their
business role. Within the definition of an analytic privilege, the conditions that control which data users see is
either contained in an XML document or defined using SQL.

Standard object privileges (SELECT, ALTER, DROP, and so on) implement coarse-grained authorization at
object level only. Users either have access to an object, such as a table, view or procedure, or they don't. While
this is often sufficient, there are cases when access to data in an object depends on certain values or
combinations of values. Analytic privileges are used in the SAP HANA database to provide such fine-grained
control at row level of which data individual users can see within the same view.

Example
Sales data for all regions are contained within one analytic view. However, regional sales managers should
only see the data for their region. In this case, an analytic privilege could be modeled so that they can all
query the view, but only the data that each user is authorized to see is returned.

Creation of Analytic Privileges

Although analytic privileges can be created directly as catalog objects in runtime, we recommend creating
them as design-time objects that become catalog objects on deployment (database artifact with file
suffix .hdbanalyticprivilege). In an SAP HANA XS classic environment, analytic privileges are created in
the built-in repository of the SAP HANA database using either the SAP HANA Web Workbench or the SAP
HANA studio. In an SAP HANA XS advanced environment, they are created using the SAP Web IDE and
deployed using SAP HANA deployment infrastructure (SAP HANA DI).

SAP HANA Developer Guide

504 PUBLIC Setting Up Roles and Privileges
 Note
HDI supports only SQL-based analytic privileges (see below). Furthermore, due to the container-based
model of HDI, where each container corresponds to a database schema, analytic privileges created in HDI
are schema specific.

XML- Versus SQL-Based Analytic Privileges

Before you implement row-level authorization using analytic privileges, you need to decide which type of
analytic privilege is suitable for your scenario. In general, SQL-based analytic privileges allow you to more easily
formulate complex filter conditions using sub-queries that might be cumbersome to model using XML-based
analytic privileges.

Recommendation
SAP recommends the use of SQL-based analytic privileges. Using the SAP HANA Modeler perspective of the
SAP HANA studio, you can migrate XML-based analytic privileges to SQL-based analytic privileges. For more
information, see the SAP HANA Modeling Guide (For SAP HANA Studio).

The following are the main differences between XML-based and SQL-based analytic privileges:

Feature SQL-Based Analytic Privi­ XML-Based Analytic Privi­

leges leges

Control of read-only access to SAP HANA information mod­ Yes Yes

els:

● Attribute views
● Analytic views
● Calculation views

Control of read-only access to SQL views Yes No

Control of read-only access to database tables No No

Design-time modeling using the SAP HANA Web-based Yes Yes

Workbench or the SAP HANA Modeler perspective of the
SAP HANA studio

Note
This corresponds to development in an SAP HANA XS
classic environment using the SAP HANA repository.

Design-time modeling using the SAP Web IDE for SAP HANA Yes No

Note
This corresponds to development in an SAP HANA XS ad­
vanced environment using HDI.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 505
Feature SQL-Based Analytic Privi­ XML-Based Analytic Privi­
leges leges

Transportable Yes Yes

HDI support Yes No

Complex filtering Yes No

Enabling an Authorization Check Based on Analytic Privileges

All column views modeled and activated in the SAP HANA modeler and the SAP HANA Web-based
Development Workbench automatically enforce an authorization check based on analytic privileges. XML-
based analytic privileges are selected by default, but you can switch to SQL-based analytic privileges.

Column views created using SQL must be explicitly registered for such a check by passing the relevant
parameter:

● REGISTERVIEWFORAPCHECK for a check based on XML-based analytic privileges

● STRUCTURED PRIVILEGE CHECK for a check based on SQL-based analytic privileges

SQL views must always be explicitly registered for an authorization check based analytic privileges by passing
the STRUCTURED PRIVILEGE CHECK parameter.

Note
It is not possible to enforce an authorization check on the same view using both XML-based and SQL-based
analytic privileges. However, it is possible to build views with different authorization checks on each other.

Related Information

Create XML-Based Analytic Privileges (SAP HANA Web Workbench) [page 513]
Create SQL-Based Analytic Privileges (SAP HANA Web Workbench) [page 511]

9.1.3.4 Package Privileges

Package privileges authorize actions on individual packages in the SAP HANA repository.

Privileges granted on a repository package are implicitly assigned to the design-time objects in the package, as
well as to all sub-packages. Users are only allowed to maintain objects in a repository package if they have the
necessary privileges for the package in which they want to perform an operation, for example to read or write
to an object in that package. To be able perform operations in all packages, a user must have privileges on the
root package .REPO_PACKAGE_ROOT.

If the user authorization check establishes that a user does not have the necessary privileges to perform the
requested operation in a specific package, the authorization check is repeated on the parent package and

SAP HANA Developer Guide

506 PUBLIC Setting Up Roles and Privileges
recursively up the package hierarchy to the root level of the repository. If the user does not have the necessary
privileges for any of the packages in the hierarchy chain, the authorization check fails and the user is not
permitted to perform the requested operation.

In the context of repository package authorizations, there is a distinction between native packages and
imported packages.

● Native package
A package that is created in the current system and expected to be edited in the current system. Changes
to packages or to objects the packages contain must be performed in the original development system
where they were created and transported into subsequent systems. The content of native packages are
regularly edited by developers.
● Imported package
A package that is created in a remote system and imported into the current system. Imported packages
should not usually be modified, except when replaced by new imports during an update. Otherwise,
imported packages or their contents should only be modified in exceptional cases, for example, to carry
out emergency repairs.

Note
The SAP HANA administrator can grant the following package privileges to an SAP HANA user: edit,
activate, and maintain.

Related Information

Package Privilege Options [page 42]

9.1.3.5 Application Privileges

In SAP HANA Extended Application Services (SAP HANA XS), application privileges define the authorization
level required for access to an SAP HANA XS application, for example, to start the application or view particular
functions and screens.

Application privileges can be assigned to an individual user or to a group of users, for example, in a user role.
The user role can also be used to assign system, object, package, and analytic privileges, as illustrated in the
following graphic. You can use application privileges to provide different levels of access to the same
application, for example, to provide advanced maintenance functions for administrators and view-only
capabilities to normal users.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 507
 Application Privileges for Users and User Roles

If you want to define application-specific privileges, you need to understand and maintain the relevant sections
in the following design-time artifacts:

● Application-privileges file (.xsprivileges)

● Application-access file (.xsaccess)
● Role-definition file (<RoleName>.hdbrole)

Application privileges can be assigned to users individually or by means of a user role, for example, with the
“application privilege” keyword in a role-definition file (<RoleName>.hdbrole) as illustrated in the following
code. You store the roles as design-time artifacts within the application package structure they are intended
for, for example, acme.com.hana.xs.app1.roles.

role acme.com.hana.xs.app1.roles::Display
{
application privilege: acme.com.hana.xs.appl::Display;
application privilege: acme.com.hana.xs.appl::View;
catalog schema "ACME_XS_APP1": SELECT;
package acme.com.hana.xs.app1: REPO.READ;
package ".REPO_PACKAGE_ROOT" : REPO.READ;
catalog sql object "_SYS_REPO"."PRODUCTS": SELECT;
catalog sql object "_SYS_REPO"."PRODUCT_INSTANCES": SELECT;
catalog sql object "_SYS_REPO"."DELIVERY_UNITS": SELECT;
catalog sql object "_SYS_REPO"."PACKAGE_CATALOG": SELECT;
catalog sql object "ACME_XS_APPL"."acme.com.hana.xs.appl.db::SYSTEM_STATE":
SELECT, INSERT, UPDATE, DELETE;
}

The application privileges referenced in the role definition (for example, Display and View) are actually
defined in an application-specific .xsprivileges file, as illustrated in the following example, which also
contains entries for additional privileges that are not explained here.

Note
The .xsprivileges file must reside in the package of the application to which the privileges apply.

The package where the .xsprivileges resides defines the scope of the application privileges; the privileges
specified in the.xsprivileges file can only be used in the package where the .xsprivileges resides (or
any sub-packages). This is checked during activation of the .xsaccess file and at runtime in the by the XS
JavaScript API $.session.(has|assert)AppPrivilege().

{
"privileges" : [

SAP HANA Developer Guide

508 PUBLIC Setting Up Roles and Privileges
 { "name" : "View", "description" : "View Product Details" },
{ "name" : "Configure", "description" : "Configure Product Details" },
{ "name" : "Display", "description" : "View Transport Details" },
{ "name" : "Administrator", "description" : "Configure/Run Everything" },
{ "name" : "ExecuteTransport", "description" : "Run Transports"},
{ "name" : "Transport", "description" : "Transports"}
]
}

The privileges are authorized for use with an application by inserting the authorization keyword into the
corresponding .xsaccess file, as illustrated in the following example. Like the .xsprivileges file,
the .xsaccess file must reside either in the root package of the application to which the privilege
authorizations apply or the specific subpackage which requires the specified authorizations.

Note
If a privilege is inserted into the .xsaccess file as an authorization requirement, a user must have this
privilege to access the application package where the .xsaccess file resides. If there is more than one
privilege, the user must have at least one of these privileges to access the content of the package.

{
"prevent_xsrf": true,
"exposed": true,
"authentication": {
"method": "Form"
},
"authorization": [
"acme.com.hana.xs.appl::Display",
"acme.com.hana.xs.appl::Transport"
]
}

Related Information

Custom Role for Developers [page 488]

Creating the Application Descriptors [page 47]

9.2 Run the File Access Check for Roles

This report allows you to check which application files are accessible to users at runtime based on a specific
role.

Prerequisites

● You are assigned the role sap.hana.ide.roles::SecurityTester (needed to use the Check File Access report).

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 509
● You have the system privilege USER ADMIN (needed to create and delete users).
● You have the EXECUTION privilege on GRANT_ACTIVATED_ROLE (needed to assign roles to users).

Context

In an SAP HANA XS application, files are organized in a package hierarchy. In order to access these files,
application privileges are assigned to users and roles, and the application privileges needed to access each
package are specified in the corresponding .xsaccess files.

This report allows you to check that the correct files are accessible through the roles defined in an application.
In order to do this, a temporary user is created for each selected role and an HTTP request is then generated
and sent to access each file contained in the application.

Files for which an HTTP status code 4xx is returned are not accessible. The results pane lists all application files
according to their HTTP status code.

Note that this report is available in the SAP HANA Web-based Development Workbench only.

Procedure

1. In the application package hierarchy, select the hdbrole file and from the context menu choose Check File
Access.
You are prompted to confirm whether or not you want to execute the XSJS files contained in the
application when running the report.

Caution
Bear in mind that when XSJS files are executed they might change underlying data. This could
potentially be dangerous if there is a function, for example, that deletes data or even entire tables.

2. Choose Yes or No, depending on your preference.

A results pane opens on the right and displays the results.
3. Navigate through the tree structure to check that the correct files are accessible.
You can see which files are associated with each HTTP status code that was returned. The 4xx status
codes show files that are not accessible.

SAP HANA Developer Guide

510 PUBLIC Setting Up Roles and Privileges
9.3 Creating Analytic Privileges

You can create analytic privileges based on either an XML document (the "classic" variation) or an SQL
definition.

Related Information

Analytic Privileges [page 504]

Create Classical XML-Based Analytic Privileges [page 513]
Create SQL Analytic Privileges [page 511]

9.3.1 Create SQL Analytic Privileges

SQL based analytic privileges provides you the flexibility to create analytic privileges within the familiar SQL
environment. You can create and apply SQL analytic privileges for a selected group of models or apply them to
all models across packages.

Prerequisites

If you want to use a SQL analytic privilege to apply data access restrictions on calculation views, set the Apply
Privileges property for the calculation view to SQL Analytic Privileges.

1. Open the calculation view in the view editor.

2. Select the Semantics node.
3. Choose the View Properties tab.
4. In the Apply Privileges dropdown list, select SQL Analytic Privileges.

Procedure

1. Launch the SAP Web IDE for SAP HANA in a browser.

2. Display the application project to which you want to add the analytic privilege.

In XS advanced, SAP Web IDE for SAP HANA creates an application within a context of a project. If you do
not already have a project, there are a number of ways to create one, for example: by importing it, cloning
it, or creating a new one from scratch.

a. In the SAP Web IDE for SAP HANA, choose File New Project from Template .
b. Choose the project template type.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 511
 Currently, there is only one type of project template available, namely: Multi-Target Application Project.
Select Multi-Target Application Project and choose Next.
c. Type a name for the new MTA project (for example, myApp and choose Next to confirm.
d. Specify details of the new MTA project and choose Next to confirm.
e. Create the new MTA project; choose Finish.
3. Select the HDB module in which you want to create the analytic privilege.

Tip
If you do not already have a database module, right-click the root folder of your new MTA project and, in
the context menu, choose New HDB Module .

4. Browse to the src folder.

5. In the context menu, choose New Analytic Privilege .

6. Enter details for the new analytic privilege.
a. In the Name field, enter the name of the analytic privilege.
7. Choose Create.
The tool launches analytic privilege editor where you can define the analytic privilege.
8. Select information models.

If you want to create an analytic privilege and apply the data access restrictions for selected list of models,
in the Secured Models section,

a. Choose .
b. In the Find Data Sources dialog, search and select the models for which you want apply the analytic
privilege restrictions.
c. Choose OK.
9. Defining SQL analytic privileges.
a. In the SQL editor, provide the attribute restrictions and its validity.
For example,

(("REGION" = 'EAST') OR ("REGION" = 'NORTH')) AND (("CUSTOMER_ID" =

'SAP')) AND ((CURRENT_DATE BETWEEN 2015-05-15 00:00:00.000 AND 2015-05-15
23:59:59.999))

10. Build an HDB module

The build process uses the design-time database artifacts to generate the corresponding actual objects in
the database catalog.

a. From the module context menu, choose Build Build

11. Assign privileges to a user.

You use the SAP HANA Runtime Tools to assign privileges to an authorization role.

12. In the menu bar, choose Tools SAP HANA Runtime Tools .

You use the SQL console in the SAP HANA Runtime Tools to assign privileges to an authorization role
(using the SQL syntax).

SAP HANA Developer Guide

512 PUBLIC Setting Up Roles and Privileges
9.3.2 Create Classical XML-Based Analytic Privileges

Create analytic privileges for information views and assign them to different users to provide selective access
that are based on certain combinations of data.

Prerequisites

If you want to use a classical XML-based analytic privilege to apply data access restrictions on information
views, set the Apply Privileges property for the information view to Classical Analytic Privileges.

1. Open the calculation view in the view editor.

2. Select the Semantics node.
3. Choose the View Properties tab.
4. In the Apply Privileges dropdown list, select Classical Analytic Privileges.

Context

Analytic privileges help restrict data access to information views based on attributes or procedures. You can
create and apply analytic privileges for a selected group of models or apply them to all models across
packages.

After you create analytic privileges, assign it to users. This restricts users to access data only for certain
combinations of dimension attributes.

Procedure

1. Open the SAP HANA Web-based Development Workbench Editor.

The Web-based Editor tool is available on the SAP HANA XS Web server at the following URL: http://
<WebServerHost>:80<SAPHANAinstance>/sap/hana/ide/editor.
2. In the navigator pane, select a package where you want to create the new analytic privilege.

3. In the context menu of the package, select New Analytic Privilege .

4. Provide a name and description.
5. In the Type dropdown list, select Classical.
6. Choose Create.
7. Define validity for the analytic privilege.
In the Privilege Validity section, specify the time period for which the analytic privilege is valid.
a. Choose Add.
b. Select a required operator.
c. Provide the validity period based on the selected operator.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 513
8. Define scope of the analytic privilege.
In the Secured Models section, select the models for which the analytic privileges restrictions are
applicable.
a. Choose Add.
b. If you want to create an analytic privilege and apply the data access restrictions for selected list of
models, in the Find Data Sources dialog, select the models for which you want apply the analytic
privilege restrictions.
c. Choose OK.
d. If you want to create an analytic privilege and apply the data access restrictions for all models, select
the Apply to all information models checkbox.
9. Select attributes and define restrictions.

Use attributes from the secured models to define data access restrictions.

a. In the Associated Attributes Restrictions section, choose Add.

b. In the Attributes dialog, select the attributes.

Note
Select a model if you want to use all attributes from the model to define restrictions.

c. Choose OK.

d. Choose to define restrictions on the selected attributes.

Modeler uses the restrictions defined on the attributes to restrict data access. Each attribute
restriction is associated with only one attribute, but can contain multiple value filters. You can create
more than one attribute restrictions.
e. In the Restriction Type dropdown list, select a restriction type.
f. Select the required operator and provide a value using the value help.
g. For catalog procedure or repository procedure, you can also provide values using the syntax <schema
name>::<procedure name> or <package name>::<procedure name> respectively.
10. Activate analytic privileges.
a. If you want to activate the analytic privilege, in the menu bar, choose Save.
b. If you want to activate the analytic privilege along with all objects, in the menu bar, choose Save All.

Note
Activate the analytic privilege only if you have defined at least one restriction on attributes in the
Associated Attributes Restrictions section.

11. Assign privileges to a user.

If you want to assign privileges to an authorization role, execute the following steps:

a. In the menu bar, choose .

b. Select the Security menu option.

This opens a new tab in the browser where you can assign the analytic privileges to users.
c. Expand Users.
d. Select a user.

SAP HANA Developer Guide

514 PUBLIC Setting Up Roles and Privileges
 e. In the Analytic Privileges tab page, choose the add icon to add the privilege.
f. In the editor toolbar, choose Activate.

9.3.3 Analytic Privileges

Analytic privileges grant different users access to different portions of data in the same view based on their
business role. Within the definition of an analytic privilege, the conditions that control which data users see is
either contained in an XML document or defined using SQL.

Standard object privileges (SELECT, ALTER, DROP, and so on) implement coarse-grained authorization at
object level only. Users either have access to an object, such as a table, view or procedure, or they don't. While
this is often sufficient, there are cases when access to data in an object depends on certain values or
combinations of values. Analytic privileges are used in the SAP HANA database to provide such fine-grained
control at row level of which data individual users can see within the same view.

Example
Sales data for all regions are contained within one analytic view. However, regional sales managers should
only see the data for their region. In this case, an analytic privilege could be modeled so that they can all
query the view, but only the data that each user is authorized to see is returned.

XML- Versus SQL-Based Analytic Privileges

Before you implement row-level authorization using analytic privileges, you need to decide which type of
analytic privilege is suitable for your scenario. In general, SQL-based analytic privileges allow you to more easily
formulate complex filter conditions that might be cumbersome to model using XML-based analytic privileges.

The following are the main differences between XML-based and SQL-based analytic privileges:

Feature SQL-Based Analytic Privi­ XML-Based Analytic Privi­

leges leges

Control of read-only access to SAP HANA information mod­ Yes Yes

els:

● Attribute views
● Analytic views
● Calculation views

Control of read-only access to SQL views Yes No

Control of read-only access to database tables No No

Design-time modeling in the Editor tool of the SAP HANA Yes Yes
Web Workbench

Design-time modeling in the SAP HANA Modeler perspective Yes Yes

of the SAP HANA studio

Transportable Yes Yes

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 515
Feature SQL-Based Analytic Privi­ XML-Based Analytic Privi­
leges leges

Complex filtering Yes No

Enabling an Authorization Check Based on Analytic Privileges

All column views modeled and activated in the SAP HANA modeler and the SAP HANA Web-based
Development Workbench automatically enforce an authorization check based on analytic privileges. XML-
based analytic privileges are selected by default, but you can switch to SQL-based analytic privileges.

Column views created using SQL must be explicitly registered for such a check by passing the relevant
parameter:

● REGISTERVIEWFORAPCHECK for a check based on XML-based analytic privileges

● STRUCTURED PRIVILEGE CHECK for a check based on SQL-based analytic privileges

SQL views must always be explicitly registered for an authorization check based analytic privileges by passing
the STRUCTURED PRIVILEGE CHECK parameter.

Note
It is not possible to enforce an authorization check on the same view using both XML-based and SQL-based
analytic privileges. However, it is possible to build views with different authorization checks on each other.

9.3.3.1 Structure of XML-Based Analytic Privileges

An analytic privilege consists of a set of restrictions against which user access to a particular attribute view,
analytic view, or calculation view is verified. In an XML-based analytic privilege, these restrictions are specified
in an XML document that conforms to a defined XML schema definition (XSD).

Each restriction in an XML-based analytic privilege controls the authorization check on the restricted view
using a set of value filters. A value filter defines a check condition that verifies whether or not the values of the
view (or view columns) qualify for user access.

The following restriction types can be used to restrict data access:

● View
● Activity
● Validity
● Attribute

The following operators can be used to define value filters in the restrictions.

Note
The activity and validity restrictions support only a subset of these operators.

SAP HANA Developer Guide

516 PUBLIC Setting Up Roles and Privileges
 ● IN <list of scalar values>
● CP <pattern with *>
● EQ (=), LE (<=), LT (<), GT (>), GE (>=) <scalar value>
● BT <scalar value as lower limit><scalar value as upper limit>
● IS_NULL
● NOT_NULL

All of the above operators, except IS_NULL and NOT_NULL, accept empty strings (" ") as filter operands.
IS_NULL and NOT_NULL do not allow any input value.

The following are examples of how empty strings can be used with the filter operators:

● For the IN operator: IN ("", "A", "B") to filter on these exact values
● As a lower limit in comparison operators, such as:
○ BT ("", “XYZ”), which is equivalent to NOT_NULL AND LE "XYZ”"GT "", which is equivalent to
NOT_NULL
○ LE "", which is equivalent to EQ ""
○ LT "", which will always return false
○ CP "", which is equivalent to EQ ""
The filter conditions CP "*" will also return rows with empty-string as values in the corresponding attribute.

View Restriction

This restriction specifies to which column views the analytic privilege applies. It can be a single view, a list of
views, or all views. An analytic privilege must have exactly one cube restriction.

Example
IN ("Cube1", "Cube2")

Note
When an analytic view is created in the SAP HANA modeler, automatically generated views are included
automatically in the cube restriction.

Note
The SAP HANA modeler uses a special syntax to specify the cube names in the view restriction:
_SYS_BIC:<package_hierarchy>/<view_name>

For example:

<cubes>
<cube name="_SYS_BIC:test.sales/AN_SALES" />
<cube name="_SYS_BIC:test.sales/AN_SALES/olap" />
</cubes>

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 517
Activity Restriction

This restriction specifies the activities that the user is allowed to perform on the restricted views, for example,
read data. An analytic privilege must have exactly one activity restriction.

Example
EQ "read", or EQ "edit"

Note
Currently, all analytic privileges created in the SAP HANA modeler are automatically configured to restrict
access to READ activity only. This corresponds to SQL SELECT queries. This is due to the fact that the
attribute, analytic, and calculation views are read-only views. This restriction is therefore not configurable.

Validity Restriction

This restriction specifies the validity period of the analytic privilege. An analytic privilege must have exactly one
validity restriction.

Example
GT 2010/10/01 01:01:00.000

Attribute Restriction

This restriction specifies the value range that the user is permitted to access. Attribute restrictions are applied
to the actual attributes of a view. Each attribute restriction is relevant for one attribute, which can contain
multiple value filters. Each value filter represents a logical filter condition.

Note
The SAP HANA modeler uses different ways to specify attribute names in the attribute restriction depending
on the type of view providing the attribute. In particular, attributes from attribute views are specified using
the syntax "<package_hierarchy>/<view_name>$<attribute_name>", while local attributes of
analytic views and calculation views are specified using their attribute name only. For example:

<dimensionAttribute name="test.sales/AT_PRODUCT$PRODUCT_NAME">
<restrictions>
<valueFilter operator="IN">
<value value="Car" />
<value value="Bike" />
</valueFilter>
</restrictions>
</dimensionAttribute>

SAP HANA Developer Guide

518 PUBLIC Setting Up Roles and Privileges
Value filters for attribute restrictions can be static or dynamic.

● A static value filter consists of an operator and either a list of values as the filter operands or a single value
as the filter operand. All data types are supported except those for LOB data types (CLOB, BLOB, and
NCLOB).
For example, a value filter (EQ 2006) can be defined for an attribute YEAR in a dimension restriction to
filter accessible data using the condition YEAR=2006 for potential users.

Note
Only attributes, not aggregatable facts (for example, measures or key figures) can be used in dimension
restrictions for analytic views.

● A dynamic value filter consists of an operator and a stored procedure call that determines the operand
value at runtime.
For example, a value filter (IN (GET_MATERIAL_NUMBER_FOR_CURRENT_USER())) is defined for the
attribute MATERIAL_NUMBER. This filter indicates that a user with this analytic privilege is only allowed to
access material data with the numbers returned by the procedure
GET_MATERIAL_NUMBER_FOR_CURRENT_USER.

It is possible to combine static and dynamic value filters as shown in the following example.

Example

<dimensionAttribute name=" test.sales/AT_PRODUCT$PRODUCT_NAME ">

<restrictions>
<valueFilter operator="CP"> <value value="ELECTRO*"/> </valueFilter>
<valueFilter operator="IN"> <procedureCall schema="PROCEDURE_OWNER"
procedure="DETERMINE_AUTHORIZED_PRODUCT_FOR_USER" /> </valueFilter >
</restrictions>
</dimensionAttribute>
<dimensionAttribute name=" test.sales/AT_TIME$YEAR ">
<restrictions>
<valueFilter operator="EQ"> <value value="2012"/> </valueFilter>
<valueFilter operator="IN"> <procedureCall schema="PROCEDURE_OWNER"
procedure="DETERMINE_AUTHORIZED_YEAR_FOR_USER" /> </valueFilter >
</restrictions>

An analytic privilege can have multiple attribute restrictions, but it must have at least one attribute restriction.
An attribute restriction must have at least one value filter. Therefore, if you want to permit access to the whole
content of a restricted view, then the attribute restriction must specify all attributes.

Similarly, if you want to permit access to the whole content of the view with the corresponding attribute, then
the value filter must specify all values.

The SAP HANA modeler automatically implements these two cases if you do not select either an attribute
restriction or a value filter.

Example
Specification of all attributes:

<dimensionAttributes>
<allDimensionAttributes/ >
</dimensionAttributes>

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 519
 Example
Specification of all values of an attribute:

<dimensionAttributes>
<dimensionAttribute name="PRODUCT">
<all />
</dimensionAttribute>
</dimensionAttributes>

Logical Combination of Restrictions and Filter Conditions

The result of user queries on restricted views is filtered according to the conditions specified by the analytic
privileges granted to the user as follows:

● Multiple analytic privileges are combined with the logical operator OR.
● Within one analytic privilege, all attribute restrictions are combined with the logical operator AND.
● Within one attribute restriction, all value filters on the attribute are combined with the logical operator OR.

Example
You create two analytic privileges AP1 and AP2. AP1 has the following attribute restrictions:

● Restriction R11 restricting the attribute Year with the value filters (EQ 2006) and (BT 2008, 2010)
● Restriction R12 restricting the attribute Country with the value filter (IN ("USA", "Germany"))

Given that multiple value filters are combined with the logical operator OR and multiple attribute restrictions
are combined with the logical operator AND, AP1 generates the condition:

((Year = 2006) OR (Year BT 2008 and 2010)) AND (Country IN ("USA", "Germany"))

AP2 has the following restriction:

Restriction R21 restricting the attribute Country with the value filter (EQ "France")

AP2 generates the condition:

(Country = "France")

Any query of a user who has been granted both AP1 and AP2 will therefore be appended with the following
WHERE clause:

((Year = 2006) OR (Year BT 2008 and 2010)) AND (Country IN ("USA", "Germany")))
OR (Country = "France")

SAP HANA Developer Guide

520 PUBLIC Setting Up Roles and Privileges
9.3.3.1.1 Dynamic Value Filters in the Attribute Restriction
of XML-Based Analytic Privileges
The attribute restriction of an XML-based analytic privilege specifies the value range that the user is permitted
to access using value filters. In addition to static scalar values, stored procedures can be used to define filters.

By using storing procedures to define filters, you can have user-specific filter conditions be determined
dynamically in runtime, for example, by querying specified tables or views. As a result, the same analytic
privilege can be applied to many users, while the filter values for authorization can be updated and changed
independently in the relevant database tables. In addition, application developers have full control not only to
design and manage such filter conditions, but also to design the logic for obtaining the relevant filter values for
the individual user at runtime.

Procedures used to define filter conditions must have the following properties:

● They must have the security mode DEFINER.

● They must be read-only procedures.
● A procedure with a predefined signature must be used. The following conditions apply:
○ No input parameter
○ Only 1 output parameter as table type with one single column for the IN operator
○ Only 1 output parameter of a scalar type for all unary operators, such as EQUAL
○ Only 2 output parameters of a scalar type for the binary operator BETWEEN
● Only the following data types are supported as the scalar types and the data type of the column in the table
type:
○ Date/Time types DATE, TIME, SECONDDATE, and TIMESTAMP
○ Numeric types TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL, REAL, and DOUBLE
○ Character string types VARCHAR and NVARCHAR
○ Binary type VARBINARY

NULL as Operand for Filter Operators

In static value filters, it is not possible to specify NULL as the operand of the operator. The operators IS_NULL
or NOT_NULL must be used instead. In dynamic value filters where a procedure is used to determine a filter
condition, NULL or valid values may be returned. The following behavior applies in the evaluation of such cases
during the authorization check of a user query:

Filter conditions of operators with NULL as the operand are disregarded, in particular the following:

● EQ NULL, GT NULL, LT NULL, LE NULL, and CP NULL

● BT NULL and NULL

If no valid filter conditions remain (that is, they have all been disregarded because they contain the NULL
operand), the user query is rejected with a “Not authorized” error.

Example
Dynamic analytic privilege 1 generates the filter condition (Year >= NULL) and dynamic analytic privilege 2
generates the condition (Country EQ NULL). The query of a user assigned these analytic privileges
(combined with the logical operator OR) will return a “Not authorized” error.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 521
 Example
Dynamic analytic privilege 1 generates the filter condition (Year >= NULL) and dynamic analytic privilege 2
generates the condition (Country EQ NULL AND Currency = “USD”). The query of a user assigned these
analytic privileges (combined with the logical operator OR) will be filtered with the filter Currency = ‘USD’.

In addition, a user query is not authorized in the following cases even if further applicable analytic privileges
have been granted to the user.

● The BT operator has as input operands a valid scalar value and NULL, for example, BT 2002 and NULL or
BT NULL and 2002
● The IN operator has as input operand NULL among the value list, for example, IN (12, 13, NULL)

Permitting Access to All Values

If you want to allow the user to see all the values of a particular attribute, instead of filtering for certain values,
the procedure must return "*" and '' '' (empty string) as the operand for the CP and GT operators respectively.
These are the only operators that support the specification of all values.

Implementation Considerations

When the procedure is executed as part of the authorization check in runtime, note the following:

● The user who must be authorized is the database user who executes the query accessing a secured view.
This is the session user. The database table or view used in the procedure must therefore contain a column
to store the user name of the session user. The procedure can then filter by this column using the SQL
function SESSION_USER. This table or view should only be accessible to the procedure owner.

Caution
Do not map the executing user to the application user. The application user is unreliable because it is
controlled by the client application. For example, it may set the application user to a technical user or it
may not set it at all. In addition, the trustworthiness of the client application cannot be guaranteed.

● The user executing the procedure is the _SYS_REPO user. In the case of procedures activated in the SAP
HANA modeler, _SYS_REPO is the owner of the procedures. For procedures created in SQL, the EXECUTE
privilege on the procedure must be granted to the _SYS_REPO user.
● If the procedure fails to execute, the user’s query stops processing and a “Not authorized” error is
returned. The root cause can be investigated in the error trace file of the indexserver,
indexserver_alert_<host>.trc.

When designing and implementing procedures as filter for dynamic analytic privileges, bear the following in
mind:

● To avoid a recursive analytic privilege check, the procedures should only select from database tables or
views that are not subject to an authorization check based on analytic privileges. In particular, views
activated in the SAP HANA modeler are to be avoided completely as they are automatically registered for
the analytic privilege check.

SAP HANA Developer Guide

522 PUBLIC Setting Up Roles and Privileges
 ● The execution of procedures in analytic privileges slows down query processing compared to analytic
privileges containing only static filters. Therefore, procedures used in analytic privileges must be designed
carefully.

9.3.3.1.2 Example: Create an XML-Based Analytic Privilege

with Dynamic Value Filter

Use the CREATE STRUCTURED PRIVILEGE statement to create an XML-based analytic privilege that contains a
dynamic procedure-based value filter and a fixed value filter in the attribute restriction.

Context

Note
The analytic privilege in this example is created using the CREATE STRUCTURED PRIVILEGE statement.
Under normal circumstances, you create XML-based analytic privileges using the SAP HANA modeler or the
SAP HANA Web-based Development Workbench. Analytic privileges created using CREATE STRUCTURED
PRIVILEGE are not owned by the user _SYS_REPO. They can be granted and revoked only by the actual
database user who creates them.

Assume you want to restrict access to product data in secured views as follows:

● Users should only see products beginning with ELECTRO, or

● Users should only see products for which they are specifically authorized. This information is contained in
the database table PRODUCT_AUTHORIZATION_TABLE in the schema AUTHORIZATION.

To be able to implement the second filter condition, you need to create a procedure that will determine which
products a user is authorized to see by querying the table PRODUCT_AUTHORIZATION_TABLE.

Procedure

1. Create the table type for the output parameter of the procedure:

CREATE TYPE "AUTHORIZATION"."PRODUCT_OUTPUT" AS TABLE("PRODUCT" int);

2. Create the table that the procedure will use to check authorization:

CREATE TABLE "AUTHORIZATION"."PRODUCT_AUTHORIZATION_TABLE" ("USER_NAME"

NVARCHAR(128), "PRODUCT" int);

3. Create the procedure that will determine which products the database user executing the query is
authorized to see based on information contained in the product authorization table:

CREATE PROCEDURE "AUTHORIZATION"."DETERMINE_AUTHORIZED_PRODUCT_FOR_USER" (OUT

VAL "AUTHORIZATION"."PRODUCT_OUTPUT")
LANGUAGE SQLSCRIPT SQL SECURITY DEFINER READS SQL DATA AS

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 523
 BEGIN
VAL = SELECT PRODUCT FROM "AUTHORIZATION"."PRODUCT_AUTHORIZATION_TABLE”
WHERE USER_NAME = SESSION_USER;
END;

Note
The session user is the database user who is executing the query to access a secured view. This is
therefore the user whose privileges must be checked. For this reason, the table or view used in the
procedure should contain a column to store the user name so that the procedure can filter on this
column using the SQL function SESSION_USER.

Caution
Do not map the executing user to the application user. The application user is unreliable because it is
controlled by the client application. For example, it may set the application user to a technical user or it
may not set it at all. In addition, the trustworthiness of the client application cannot be guaranteed.

4. Create the analytic privilege:

CREATE STRUCTURED PRIVILEGE '<?xml version="1.0" encoding="utf-8"?>

<analyticPrivilegeSchema version="1">
<analyticPrivilege name="AP2">
<cubes>
<allCubes />
</cubes>
<validity>
<anyTime/>
</validity>
<activities>
<activity activity="read" />
</activities>
<dimensionAttributes>
<dimensionAttribute name="PRODUCT">
<restrictions>
<valueFilter operator="CP"> <value value="ELECTRO*"/> </
valueFilter>
<valueFilter operator="IN"> <procedureCall schema="AUTHORIZATION"
procedure="DETERMINE_AUTHORIZED_PRODUCT_FOR_USER"/> </valueFilter>
</restrictions>
</dimensionAttribute>
</dimensionAttributes>
</analyticPrivilege>
</analyticPrivilegeSchema>';

Results

Now when a database user requests access to a secured view containing product information, the data
returned will be filtered according to the following condition:

(product LIKE "ELECTRO*" OR product IN

(AUTHORIZATION.DETERMINE_AUTHORIZED_PRODUCT_FOR_USER())

SAP HANA Developer Guide

524 PUBLIC Setting Up Roles and Privileges
9.3.3.2 Structure of SQL-Based Analytic Privileges

An analytic privilege consists of a set of restrictions against which user access to a particular attribute view,
analytic view, calculation view, or SQL view is verified. In an SQL-based analytic privilege, these restrictions are
specified as filter conditions that are fully SQL based.

SQL-based analytic privileges are created in the Editor tool of the SAP HANA Web-based Development
Workbench ( New Analytic Privilege Type: SQL ) on the basis of the CREATE STRUCTURED PRIVILEGE
statement:

CREATE STRUCTURED PRVILEGE <privilege_name> FOR <action> ON <view_name>

<filter_condition>

The FOR clause is used restrict the type of access (only the SELECT action is supported). The ON clause is
used to restrict access to one or more views with the same filter attributes.

The <filter condition> parameter is used to restrict the data visible to individual users. The following
methods of specifying filter conditions are possible:

● Fixed filter (WHERE) clause

● Dynamically generated filter (CONDITION PROVIDER) clause

Fixed Filter Clauses

A fixed filter clause consists of a WHERE clause that is specified in the definition of the analytic privilege itself.

You can express fixed filter conditions freely using SQL, including subqueries.

By incorporating built-in SQL functions into the subqueries, in particular SESSION_USER, you can define an
even more flexible filter condition.

Example
country IN (SELECT a.country FROM authorization table a WHERE SESSION_USER= a.user_name)

Note
A calculation view cannot be secured using an SQL-based analytic privilege that contains a complex filter
condition if the view is defined on top of analytic and/or attributes views that themselves are secured with
an SQL-based analytic privilege with a complex filter condition.

Remember
If you use a subquery, you (the creating user) must have the required privileges on the database objects
(tables and views) involved in the subquery.

Comparative conditions can be nested and combined using AND and OR (with corresponding brackets).

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 525
 Tip
To create an analytic privilege that allows access to either all data or no data in a view, set a fixed filter
condition such as 1=1 or 1!=1.

For examples, see Examples: Securing Views Using SQL-Based Analytic Privileges.

Dynamically Generated Filter Clauses

With a dynamically generated filter clause, the WHERE clause that specifies the filter condition is generated
every time the analytic privilege is evaluated. This is useful in an environment in which the filter clause changes
very dynamically. The filter condition is determined by a procedure specified in the CONDITION PROVIDER
clause, for example:

Sample Code
CREATE STRUCTURED PRVILEGE dynamic_ap FOR SELECT ON schema1.v1 CONDITION PROVIDER
schema2.procedure1;

Procedures in the CONDITION PROVIDER clause must have the following properties:

● They must have the security mode DEFINER.

● They must be read-only procedures.
● They must have a predefined signature. Here, the following conditions apply:
○ No input parameter
○ Only one output parameter for the filter condition string
● The procedure may only return conditions expressed with the following operators:
○ =, <=, <, >, >=
○ LIKE
○ BETWEEN
○ IN
A complex filter condition, that is a subquery, may not be returned.

Tip
A procedure that returns the filter condition 1=1 or 1>1 can be used to create an analytic privilege that
allows access to all data or no data in a view.

● The procedure must be executable by _SYS_REPO, that is, either_SYS_REPO must be the owner of the
procedure or the owner of the procedure has all privileges on the underlying tables/views with GRANT
OPTION and has granted the EXECUTE privilege on the procedure to the _SYS_REPO user.

If errors occur in procedure execution, the user receives a Not authorized error, even if user has the analytic
privileges that would grant access.

For examples, see Examples: Securing Views Using SQL-Based Analytic Privileges.

SAP HANA Developer Guide

526 PUBLIC Setting Up Roles and Privileges
Related Information

Examples: Securing Views Using SQL-Based Analytic Privileges [page 527]

9.3.3.2.1 Examples: Securing Views Using SQL-Based

Analytic Privileges

Use the CREATE STRUCTURED PRIVILEGE statement to create SQL-based analytic privileges for different
scenarios.

Context

The examples provided here take you through the following scenarios:

● Example 1: Securing a column view using an SQL-based analytic privilege with a fixed filter clause [page
527]
● Example 2: Securing an SQL view using an SQL-based analytic privilege with a complex filter clause
(subquery) [page 529]
● Example 3: Securing a column view using an SQL-based analytic privilege with a dynamically generated
filter clause [page 531]

Note
The analytic privileges in these example are created using the CREATE STRUCTURED PRIVILEGE statement.
Under normal circumstances, you create SQL-based analytic privileges using the SAP HANA Web-based
Development Workbench. Analytic privileges created using CREATE STRUCTURED PRIVILEGE are not
owned by the user _SYS_REPO. They can be granted and revoked only by the actual database user who
creates them.

Example 1: Secure a Column View Using an SQL-Based

Analytic Privilege with a Fixed Filter Clause

Prerequisites

The database user TABLEOWNER has set up a calculation scenario based on the table SALES_TABLE, which
contains the data to be protected.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 527
Context

All sales data is contained in a single view. You want to restrict user access so that sales managers can see only
information about the product "car" in the sales region UK and Germany. You want to do this by creating an
analytic privilege with a fixed filter clause.

A fixed filter clause consists of an SQL WHERE clause that is specified in the definition of the analytic privilege
itself.

Procedure

1. Create the view containing the sales data:

CREATE COLUMN VIEW "TABLEOWNER"."VIEW_SALES" TYPE CALCULATION WITH PARAMETERS

('PARENTCALCINDEXSCHEMA'='TABLEOWNER',
'PARENTCALCINDEX'='CALCSCEN_SALES',
'PARENTCALCNODE'='SALES_TABLE',
'REGISTERVIEWFORAPCHECK'='0') STRUCTURED PRIVILEGE CHECK
;

Note
You can see above that the authorization check using XML-based analytic privileges is disabled with
'REGISTERVIEWFORAPCHECK'='0', while the authorization check using SQL-based analytic privileges
is enabled with STRUCTURED PRIVILEGE CHECK. Both checks cannot be enabled at the same time.

2. Create the analytic privilege:

CREATE STRUCTURED PRIVILEGE AP_SALES_1 FOR SELECT

ON TABLEOWNER.VIEW_SALES
WHERE REGION IN ('DE','UK')
OR PRODUCT = 'CAR'
;

Remember
When specifying filters, remember the following:
○ You can specify only the SELECT action in the FOR clause.
○ You can specify one or more views with the same filter attributes in the ON clause
○ You can specify comparative conditions between attributes and constant values using only the
following operators:
○ =, <=, <, >, >=
○ LIKE
○ BETWEEN
○ IN
○ You can create complex filter conditions by including SQL statements as subqueries inside the
WHERE clause. Example 2 illustrates how you do this. But remember: A calculation view cannot be
secured using an SQL-based analytic privilege that contains a complex filter condition if the view is
defined on top of analytic and/or attributes views that themselves are secured with an SQL-based
analytic privilege with a complex filter condition.

SAP HANA Developer Guide

528 PUBLIC Setting Up Roles and Privileges
 Also remember that if you use a subquery, you must have the required privileges on the database
objects (tables and views) involved in the subquery.

3. Grant the SELECT privilege on the view TABLEOWNER.VIEW_SALES to the relevant users/roles:

GRANT SELECT on TABLEOWNER.VIEW_SALES to <SALES_MANAGERS>;

Remember
Only the view owner or a user who has the SELECT privilege WITH GRANT OPTION on the view can
perform the grant.

4. Grant the analytic privilege to the relevant users/roles:

GRANT STRUCTURED PRIVILEGE AP_SALES_1 TO <SALES_MANAGERS>;

Remember
Only the owner of the analytic privilege can grant it.

Example 2: Secure an SQL View Using an SQL-Based Analytic

Privilege with a Complex Filter Clause
(Subquery)

Prerequisites

The database user TABLEOWNER has created a table TABLEOWNER.SALES, which contains the data to be
protected.

Context

All sales data is contained in a single view. You want to restrict access of user MILLER so that he can see only
product information from the year 2008. You want to do this by creating an analytic privilege with a complex
filter clause.

With a complex filter clause, the SQL WHERE clause that specifies the filter condition includes an SQL
statement, or a subquery. This allows you to create complex filter conditions to control which data individual
users see.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 529
Procedure

1. Create the view containing the sales data which needs to be secured:

CREATE VIEW "VIEWOWNER"."ROW_VIEW_SALES_ON_SALES" AS SELECT

* FROM "TABLEOWNER"."SALES" WITH STRUCTURED PRIVILEGE CHECK
;

Remember
The user creating the view must have the SELECT privilege WITH GRANT OPTION on the table
TABLEOWNER.SALES.

2. Create the table containing user-specific authorization data:

CREATE COLUMN TABLE "VIEWOWNER"."AUTHORIZATION_VALUES"("VALUE" VARCHAR(256),

"USER_NAME" VARCHAR(20));

3. Insert authorization information for user MILLER:

INSERT INTO "VIEWOWNER"."AUTHORIZATION_VALUES" VALUES('2008', 'MILLER);

4. Create the analytic privilege using a subquery as the condition provider:

CREATE STRUCTURED PRIVILEGE AP_ROW_VIEW_SALES_ON_SALES FOR SELECT

ON "VIEWOWNER"."ROW_VIEW_SALES_ON_SALES"
WHERE (CURRENT_DATE BETWEEN 2015-01-01 AND 2015-01-11) AND YEAR IN (SELECT
VALUE FROM VIEWOWNER.AUTHORIZATION_VALUES WHERE USER_NAME = SESSION_USER)
;

Remember
○ Subqueries allow you to create complex filter conditions, but remember: A calculation view cannot
be secured using an SQL-based analytic privilege that contains a complex filter condition if the view
is defined on top of analytic and/or attributes views that themselves are secured with an SQL-based
analytic privilege with a complex filter condition.
○ The user creating the analytic privilege must have the SELECT privilege on the objects involved in
the subquery, in this case table VIEWOWNER.AUTHORIZATION_VALUES.
○ The session user is the database user who is executing the query to access a secured view. This is
therefore the user whose privileges must be checked. For this reason, the table containing the
authorization information needs a column to store the user name so that the subquery can filter on
this column using the SQL function SESSION_USER.

Caution
Do not map the executing user to the application user. The application user is unreliable because it is
controlled by the client application. For example, it may set the application user to a technical user or it
may not set it at all. In addition, the trustworthiness of the client application cannot be guaranteed.

5. Grant the SELECT privilege on the view VIEWOWNER.ROW_VIEW_SALES_ON_SALES to user MILLER.

GRANT SELECT ON "VIEWOWNER"."ROW_VIEW_SALES_ON_SALES" TO MILLER;

SAP HANA Developer Guide

530 PUBLIC Setting Up Roles and Privileges
 Remember
Only the view owner or a user who has the SELECT privilege WITH GRANT OPTION on the view can
perform the grant.

6. Grant the analytic privilege to user MILLER.

GRANT STRUCTURED PRIVILEGE AP_ROW_SALES_ON_SALES TO MILLER;

Remember
Only the owner of the analytic privilege can grant it.

Example 3: Secure a Column View Using an SQL-Based

Analytic Privilege with a Dynamically Generated
Filter Clause

Prerequisites

The database user TABLEOWNER has set up a calculation scenario based on the table SALES_TABLE, which
contains the data to be protected.

Context

All sales data is contained in a single view. You want to restrict access of user ADAMS so that he can see only
information about cars bought by customer Company A or bikes sold in 2006. You want to do this by creating
an analytic privilege with a dynamically generated filter clause.

With a dynamically generated filter clause, the SQL WHERE clause that specifies the filter condition is
generated every time the analytic privilege is evaluated. This is useful in an environment in which the filter
clause changes very dynamically.

Procedure

1. Create the view containing the sales data:

CREATE COLUMN VIEW "TABLEOWNER"."VIEW_SALES" TYPE CALCULATION WITH PARAMETERS

('PARENTCALCINDEXSCHEMA'='TABLEOWNER',
'PARENTCALCINDEX'='CALCSCEN_SALES',
'PARENTCALCNODE'='SALES_TABLE',
'REGISTERVIEWFORAPCHECK'='0') STRUCTURED PRIVILEGE CHECK
;

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 531
2. Create a table containing user-specific filter strings:

CREATE COLUMN TABLE "AUTHORIZATION"."AUTHORIZATION_FILTERS"("FILTER"

VARCHAR(256),
"USER_NAME" VARCHAR(20))
;

3. Create an authorization filter for user ADAMS:

INSERT
INTO "AUTHORIZATION"."AUTHORIZATION_FILTERS" VALUES('(CUSTOMER=''Company A''
AND PRODUCT=''Car'') OR (YEAR=''2006'' AND PRODUCT=''Bike'')',
'ADAMS')
;

Remember
Filters containing comparative conditions must be defined as specified in example 1.

4. Create the database procedure that provides the filter clause for the analytic privilege and grant it to user
_SYS_REPO:

CREATE PROCEDURE "PROCOWNER"."GET_FILTER_FOR_USER"(OUT OUT_FILTER

VARCHAR(5000))
LANGUAGE SQLSCRIPT SQL SECURITY DEFINER READS SQL DATA AS
v_Filter VARCHAR(5000);
CURSOR v_Cursor FOR SELECT "FILTER" FROM
"PROCOWNER"."AUTHORIZATION_FILTERS" WHERE "USER_NAME" = SESSION_USER;
BEGIN
OPEN v_Cursor;
FETCH v_Cursor INTO v_Filter;
OUT_FILTER := v_Filter;
CLOSE v_Cursor;
END;
GRANT EXECUTE ON "PROCOWNER"."GET_FILTER_FOR_USER" TO _SYS_REPO;

Remember
When using procedures as the condition provider in an SQL-based analytic privilege, remember the
following:
○ Procedures must have the following properties:
○ They must have the security mode DEFINER.
○ They must be read-only procedures.
○ A procedure with a predefined signature must be used. The following conditions apply:
○ No input parameter
○ Only 1 output parameter of VARCHAR or NVARCHAR type for the filter condition string
The length of the string may be between 1 and 5000 characters. However, the output string
must not exceed this length.
○ The procedure may not return a complex filter condition, that is a subquery.
○ The procedure must be executable by _SYS_REPO, that is, either_SYS_REPO must be the owner of
the procedure or the owner of the procedure has all privileges on the underlying tables/views with
GRANT OPTION and has granted the EXECUTE privilege on the procedure to the _SYS_REPO user.
○ The session user is the database user who is executing the query to access a secured view. This is
therefore the user whose privileges must be checked. For this reason, the table or view used in the
procedure should contain a column to store the user name so that the procedure can filter on this
column using the SQL function SESSION_USER.

SAP HANA Developer Guide

532 PUBLIC Setting Up Roles and Privileges
 ○ If errors occur in procedure execution, the user receives a Not authorized error, even if he has
the analytic privileges that would grant access.

5. Create the analytic privilege using the procedure as condition provider:

CREATE STRUCTURED PRIVILEGE AP_SALES_2 FOR SELECT ON

"TABLEOWNER"."VIEW_SALES" CONDITION PROVIDER
"AUTHORIZATION"."GET_FILTER_FOR_USER";

On evaluation of the analytic privilege for user ADAMS, the WHERE clause (CUSTOMER='Company A' AND
PRODUCT='Car') OR (YEAR='2006' AND PRODUCT='Bike'), as provided by the procedure
GET_FILTER_FOR_USER, will be used.
6. Grant the SELECT privilege on the view TABLEOWNER.VIEW_SALES to user ADAMS:

GRANT SELECT on TABLEOWNER.VIEW_SALES to ADAMS;

Remember
Only the view owner or a user who has the SELECT privilege WITH GRANT OPTION on the view can
perform the grant.

7. Grant the analytic privilege to user ADAMS:

GRANT STRUCTURED PRIVILEGE AP_SALES_2 TO ADAMS;

Remember
Only the owner of the analytic privilege can grant it.

9.3.3.3 Runtime Authorization Check of Analytic Privileges

When a user requests access to data stored in an attribute, analytic, calculation, or SQL views, an authorization
check based on analytic privileges is performed and the data returned to the user is filtered accordingly. The
EFFECTIVE_STRUCTURED_PRIVILEGES system view can help you to troubleshoot authorization problems.

Access to a view and the way in which results are filtered depend on whether the view is independent or
associated with other views (dependent views).

Independent Views

The authorization check for a view that is not defined on another column view is as follows:

1. The user's authorization to access the view is checked.

A user can access the view if both of the following prerequisites are met:
○ The user has been granted the SELECT privilege on the view or the schema in which it is located.

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 533
 Note
The user does not require SELECT on the underlying base tables or views of the view.

○ The user has been granted an analytic privilege that is applicable to the view.
Applicable analytic privileges are those that meet all of the following criteria:

XML-Based Analytic Privilege SQL-Based Analytic Privilege

A view restriction that includes the accessed view An ON clause that includes the accessed view

A validity restriction that applies now If the filter condition specifies a validity period (for ex­
ample, WHERE (CURRENT_TIME BETWEEN ...
AND ....) AND <actual filter>) ), it must
apply now

An action in the activity restriction that covers the ac­ An action in the FOR clause that covers the action re­
tion requested by the query quested by the query

Note Note
All analytic privileges created and activated in the All analytic privileges created and activated in the
SAP HANA modeler and SAP HANA Web-based De­ SAP HANA Web-based Development Workbench ful­
velopment Workbench fulfill this condition. The only fill this condition. The only action supported is read
action supported is read access (SELECT). access (SELECT).

An attribute restriction that includes some of the view’s A filter condition that applies to the view
attributes
Note
When the analytic privilege is created, the filter is
checked immediately to ensure that it applies to the
view. If it doesn't, creation will fail. However, if the
view definition subsequently changes, or if a dynam­
ically generated filter condition returns a filter string
that is not executable with the view, the authoriza­
tion check will fail and access is rejected.

If the user has the SELECT privilege on the view but no applicable analytic privileges, the user’s request is
rejected with a Not authorized error. The same is true if the user has an applicable analytic privilege but
doesn't have the SELECT privilege on the view.

2. The value filters specified in the dimension restrictions (XML-based) or filter condition (SQL-based) are
evaluated and the appropriate data is returned to the user. Multiple analytic privileges are combined with
the logical operator OR.
For more information about how multiple attribute restrictions and/or multiple value filters in XML-based
analytic privileges are combined, see XML-Based Analytic Privileges.

Dependent Views

The authorization check for a view that is defined on other column views is more complex. Note the following
behavior.

SAP HANA Developer Guide

534 PUBLIC Setting Up Roles and Privileges
Calculation and SQL views

● Individual views in the hierarchy are filtered according to their respective analytic privileges, which use the
logical OR combination.
● The filtered result of the calculation view is derived from the filtered result of its underlying views. This
corresponds to a logic AND combination of the filters generated by the analytic privileges for the individual
views.

Result filtering on the view is then performed as follows:

● The user has been granted the SELECT privilege on the view or the schema that contains the view.
● The user has been granted analytic privileges that apply to the view itself and all the other column views in
the hierarchy that are registered for a structured privilege check.

A user can access a calculation or SQL view based on other views if both of the following prerequisites are met:

If a user requests access to a calculation view that is dependent on another view, the behavior of the
authorization check and result filtering is performed as follows:

Calculation views and SQL views can be defined by selecting data from other column views, specifically
attribute views, analytic views, and other calculation views. This can lead to a complex view hierarchy that
requires careful design of row-level authorization.

Analytic views

An analytic view can also be defined on attribute views, but this does not represent a view dependency or
hierarchy with respect to authorization check and result filtering. If you reference an attribute view in an
analytic view, analytic privileges defined on the attribute view are not applied.

This represents a view hierarchy for which the prerequisites described above for calculation views also apply.

● Currency or unit conversions

● Calculated attributes
● Calculated measures that use attributes, calculated attributes, or input parameters in their formulas

If an analytic view designed in the SAP HANA modeler contains one of the elements listed below, it will
automatically be activated with a calculation view on top. The name of this calculation view is the name of the
analytic view with the suffix /olap.

Troubleshooting Failed Authorization

Using the EFFECTIVE_STRUCTURED_PRIVILEGES system view, you can quickly see:

● Which analytic privileges apply to a particular view, including the dynamic filter conditions that apply (if
relevant)
● Which filter is being applied to which view in the view hierarchy (for views with dependencies)
● Whether or not a particular user is authorized to access the view

Query EFFECTIVE_STRUCTURED_PRIVILEGES as follows:

SELECT * from "PUBLIC"."EFFECTIVE_STRUCTURED_PRIVILEGES" where ROOT_SCHEMA_NAME

= '<schema>' AND ROOT_OBJECT_NAME = '<OBJECT>' AND USER_NAME = '<USER>'

SAP HANA Developer Guide

Setting Up Roles and Privileges PUBLIC 535
Related Information

Structure of XML-Based Analytic Privileges [page 516]

SAP HANA Developer Guide

536 PUBLIC Setting Up Roles and Privileges
Important Disclaimer for Features in SAP
HANA Platform, Options and Capabilities

SAP HANA server software and tools can be used for several SAP HANA platform and options scenarios as well
as the respective capabilities used in these scenarios. The availability of these is based on the available SAP
HANA licenses and the SAP HANA landscape, including the type and version of the back-end systems the SAP
HANA administration and development tools are connected to. There are several types of licenses available for
SAP HANA. Depending on your SAP HANA installation license type, some of the features and tools described in
the SAP HANA platform documentation may only be available in the SAP HANA options and capabilities, which
may be released independently of an SAP HANA Platform Support Package Stack (SPS). Although various
features included in SAP HANA options and capabilities are cited in the SAP HANA platform documentation,
each SAP HANA edition governs the options and capabilities available. Based on this, customers do not
necessarily have the right to use features included in SAP HANA options and capabilities. For customers to
whom these license restrictions apply, the use of features included in SAP HANA options and capabilities in a
production system requires purchasing the corresponding software license(s) from SAP. The documentation
for the SAP HANA options is available in SAP Help Portal. If you have additional questions about what your
particular license provides, or wish to discuss licensing features available in SAP HANA options, please contact
your SAP account team representative.

SAP HANA Developer Guide

Important Disclaimer for Features in SAP HANA Platform, Options and Capabilities PUBLIC 537
Important Disclaimers and Legal Information

Coding Samples
Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system
environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and
completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP
intentionally or by SAP's gross negligence.

Gender-Neutral Language
As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as
"sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun
does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.

Internet Hyperlinks
The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not
warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any
damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for
transparency (see: https://help.sap.com/viewer/disclaimer).

SAP HANA Developer Guide

538 PUBLIC Important Disclaimers and Legal Information
SAP HANA Developer Guide
Important Disclaimers and Legal Information PUBLIC 539
go.sap.com/registration/
contact.html

© 2018 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any
form or for any purpose without the express permission of SAP SE
or an SAP affiliate company. The information contained herein may
be changed without prior notice.
Some software products marketed by SAP SE and its distributors
contain proprietary software components of other software vendors.
National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company
for informational purposes only, without representation or warranty
of any kind, and SAP or its affiliated companies shall not be liable for
errors or omissions with respect to the materials. The only
warranties for SAP or SAP affiliate company products and services
are those that are set forth in the express warranty statements
accompanying such products and services, if any. Nothing herein
should be construed as constituting an additional warranty.
SAP and other SAP products and services mentioned herein as well
as their respective logos are trademarks or registered trademarks of
SAP SE (or an SAP affiliate company) in Germany and other
countries. All other product and service names mentioned are the
trademarks of their respective companies.
Please see https://www.sap.com/corporate/en/legal/copyright.html
for additional trademark information and notices.