SAP HANA Developer Guide

PUBLIC
SAP HANA Platform SPS 06 Document Version: 1.2 - 03-09-2013
SAP HANA Developer Guide
Table of Contents
1 1.1 Introduction to SAP HANA Development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 SAP HANA Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.1.1 1.1.2 1.1.3 1.1.4 1.2 1.2.1 1.2.2 2 2.1 2.2 2.3 2.4 2.5 SAP HANA In-Memory Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 SAP HANA Database Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 SAP HANA Extended Application Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 SAP HANA-Based Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Scenario: Developing Native SAP HANA Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Scenario: Using Database Client Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Developer Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SAP HANA Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.2.1 The SAP HANA Development Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 SAP HANA XS Application Descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 SAP HANA Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Tutorials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 2.5.1 2.5.2 Tutorial: My First SAP HANA Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Tutorial: Using the SAP HANA OData Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3 3.1 3.2
Setting Up Your Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Roles and Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Maintaining Delivery Units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 3.2.1 3.2.2 3.2.3 Maintaining the Delivery-Unit Vendor ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 SAP HANA Delivery Unit Naming Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Creating a Delivery Unit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 SAP HANA Repository: Workspaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Creating a Repository Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 SAP HANA Studio Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 Creating a Project for SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Sharing a Project for SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Importing a Project in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 SAP HANA Repository Packages and Namespaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56 Defining Repository Package Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Creating a Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Defining a Package Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
3.3
Using SAP HANA Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 3.3.1 3.3.2 3.3.3 3.3.4 3.3.5 3.3.6
3.4
Maintaining Repository Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 3.4.1 3.4.2 3.4.3 3.4.4
3.5
Creating the Application Descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
PUBLIC 2013 SAP AG or an SAP affiliate company. All rights reserved.
SAP HANA Developer Guide Table of Contents
3.5.1 3.5.2 3.5.3 3.5.4 3.5.5 3.5.6 3.5.7 3.5.8 3.6 3.6.1 3.6.2 3.7 3.7.1 3.7.2 3.7.3 3.7.4 3.7.5 3.8 3.9
The SAP HANA XS Application Descriptor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Creating an Application Descriptor File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 The Application-Access File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Application-Access File Keyword Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Application-Access URL Rewrite Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Enabling Access to SAP HANA XS Application Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 The Application-Privileges File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Creating an SAP HANA XS Application Privileges File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 SAP HANA XS Application Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 SAP HANA XS Application Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 The HTTP Destination Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 The HTTP Destination Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 HTTP Destination Configuration Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92 Tutorial: Create an HTTP Destination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Tutorial: Extend an HTTP Destination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Maintaining Application Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Maintaining HTTP Destinations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Design-Time Application Artifacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Developing Applications in Web-based Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 3.9.1 3.9.2 3.9.3 SAP HANA IDE lite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 SAP HANA Web-based Development Workbench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Web-Based Application-Development Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4 4.1 4.2
Setting Up the Persistence Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Creating Schemas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 4.1.1 4.2.1 4.2.2 Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125 Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Table Configuration Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Reusable Table Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Sequences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 SQL Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Table-Import Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145 Table-Import Configuration-File Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Table-Import Configuration Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Tutorial: Importing Data with .hdbtable Table-Import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 CDS Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155 Creating Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
4.3 4.4 4.5 4.6
Creating Reusable Table Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135 4.3.1 4.4.1 4.5.1 4.6.1 4.6.2 4.6.3 4.6.4 Creating Sequences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Creating SQL Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Data Provisioning Using Table Import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
4.7
Data Persistence Objects in Core Data Services (CDS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 4.7.1
PUBLIC
2013 SAP AG or an SAP affiliate company. All rights reserved.
4.7.2 4.7.3 4.7.4 4.7.5 4.7.6 4.7.7 4.7.8 4.7.9 4.7.10 5 5.1
CDS Entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 CDS Structured Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 CDS Contexts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 CDS User-Defined Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Comments in CDS Object Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 CDS Primitive Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 CDS Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Tutorial: Getting Started with CDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Tutorial: Importing Data with CDS Table-Import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Setting Up the Analytic Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Setting Up the Modeling Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 5.1.1 5.1.2 Setting Modeler Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Setting Keyboard Shortcuts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Attributes and Measures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 First Steps to View Creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181 Attribute Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Creating Attribute Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Analytic Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Creating Analytic Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191 Calculation Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198 Creating a Graphical Calculation View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Creating a Script-Based Calculation View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Activating Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Description Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Importing BW Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Display Folders. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Creating Level Hierarchies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Creating Parent-Child Hierarchies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Creating Input Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Assigning Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Using Currency and Unit of Measure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Working with Broken Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 Managing Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Validating Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Maintaining Search Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233 Previewing Data of Content Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233 Functions used in Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Resolving Conflicts in Modeler Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
5.2
Creating Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 5.2.1 5.2.2 5.2.3 5.2.4 5.2.5 5.2.6 5.2.7 5.2.8 5.2.9 5.2.10 5.2.11 5.2.12 5.2.13
5.3
Additional Functionality for Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 5.3.1 5.3.2 5.3.3 5.3.4 5.3.5 5.3.6
5.4
Working with Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 5.4.1 5.4.2 5.4.3 5.4.4 5.4.5 5.4.6
PUBLIC
5.5
Creating Decision Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 5.5.1 5.5.2 5.5.3 Changing the Layout of a Decision Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Using Parameters in a Decision Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Using Calculated Attribute in Decision Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
5.6 6 6.1 6.2
Generating Object Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Developing Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Creating and Editing Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 6.1.1 6.2.1 6.2.2 6.2.3 Defining Local Table Types in Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 Creating Procedure Template Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Updating Procedure Templates and Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Deleting Procedure Templates and Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 Creating Procedure Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
6.3 6.4 6.5 6.6
Debugging Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262 Debugging an External Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Developing Procedures in the Modeler Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Developing Procedures Using Application Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 6.6.1 6.6.2 6.6.3 6.6.4 6.6.5 SAP HANA Application Function Modeler (AFM). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268 Creating an AFM File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 Adding Application Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 Generating Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 Calling a Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
7 7.1
Defining Web-based Data Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 Data Access with OData in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 7.1.1 7.1.2 7.1.3 7.1.4 7.1.5 7.1.6 7.1.7 7.1.8 7.1.9 OData in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 Defining the Data an OData Service Exposes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 OData Service Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Creating an OData Service Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .280 Tutorial: Using the SAP HANA OData Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 OData Service-Definition Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 OData Service Definition Language Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 OData Service Definition: SQL-EDM Type Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 OData Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 XML for Analysis (XMLA). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 XMLA Service Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306 XMLA Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 Multidimensional Expressions (MDX). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 MDX Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 MDX Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312 Defining the Data an XMLA Service Exposes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
7.2
Data Access with XMLA in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305 7.2.1 7.2.2 7.2.3 7.2.4 7.2.5 7.2.6 7.2.7
PUBLIC
7.2.8 7.2.9 8 8.1 8.2
Creating an XMLA Service Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 Tutorial: Using the SAP HANA XMLA Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Writing Server-Side JavaScript Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 Data Access with JavaScript in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319 Server-Side JavaScript in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 8.2.1 8.2.2 8.2.3 JavaScript Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 Server-Side JavaScript Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320 Tutorial: Writing Server-Side JavaScript Application Code. . . . . . . . . . . . . . . . . . . . . . . . . . 331 Writing Server-Side JavaScript Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 Importing Server-Side JavaScript Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 Tutorial: Using the XSJS Outbound API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
8.3
Server-Side JavaScript Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 8.3.1 8.3.2
8.4 8.5 8.6 8.7
Server-Side JavaScript APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 8.4.1 The SQL Connection Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 Connection-language Settings in SAP HANA XS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Server-Side JavaScript Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .346 8.7.1 8.7.2 Tracing Server-Side JavaScript Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Viewing Server-Side JavaScript Application Trace Files. . . . . . . . . . . . . . . . . . . . . . . . . . . .348 The Debug Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 The XSJS Debugger Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Debug Session Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 XSJS-Debugging Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 Troubleshooting Server-Side JavaScript Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
8.8
Debugging Server-Side JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 8.8.1 8.8.2 8.8.3 8.8.4 8.8.5
9 9.1 9.2
Building UIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Building User Interfaces with SAPUI5 for SAP HANA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Building Search UIs with SAP HANA Info Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .362 9.2.1 9.2.2 9.2.3 9.2.4 9.2.5 9.2.6 9.2.7 What's the Idea behind SAP HANA Info Access?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 SAP HANA Info Access Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Installing the Info Access Service, Toolkit, and API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Preparing Your Search Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 Authorizations for SAP HANA Info Access Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 Using the SAP HANA Simple Info Access API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Using the UI Toolkit for SAP HANA Info Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .368 Creating an Application Site. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Designing an Application Site. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Creating a Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Developing Widgets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
9.3
Using UI Integration Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 9.3.1 9.3.2 9.3.3 9.3.4
10 10.1
Enabling Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 Creating Full Text Indexes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 10.1.1 10.1.2 10.1.3 10.1.4 10.1.5 10.1.6 Full Text Index Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 Text Analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Dropping Full Text Indexes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 Altering Full Text Index Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 Full Text Index Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 Search Queries with CONTAINS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 EXACT Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 LINGUISTIC Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 FUZZY Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
10.2
Building SQL Search Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414 10.2.1 10.2.2 10.2.3 10.2.4
11 11.1 11.2 11.3
Setting Up Roles and Authorizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 The Authorization Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 Authentication Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 11.3.1 11.3.2 11.3.3 11.3.4 Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 Roles as Repository Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 Custom Development Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 Creating Roles in the Repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 System Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 Object Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 Package Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .540 Analytic Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 Creating Analytic Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 Granting Privileges to Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
11.4
Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 11.4.1 11.4.2 11.4.3 11.4.4 11.4.5 11.4.6
11.5 12 12.1 12.2
Application Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 Implementing Lifecycle Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 SAP HANA Application Lifecycle Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 Maintaining the SAP HANA Application Lifecycle Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .564 12.2.1 12.2.2 12.2.3 12.2.4 Application Lifecycle Management Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .565 SAP HANA Application Lifecycle Management Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .566 Assigning User Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 Maintaining the Delivery-Unit Vendor ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .568 SAP HANA Repository Packages and Namespaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570 Creating a Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 Defining a Package Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
12.3
Maintaining Repository Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 12.3.1 12.3.2 12.3.3
PUBLIC
12.3.4 12.4 12.4.1 12.4.2 12.4.3 12.4.4 12.4.5 12.4.6 12.4.7 12.5 12.5.1 12.5.2 12.6 12.6.1 12.6.2 12.6.3 12.6.4 12.6.5 12.6.6 13 13.1
Creating an Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 SAP HANA Delivery Units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 SAP HANA Delivery Unit Naming Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 The SAP HANA Delivery-Unit Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Creating a Delivery Unit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 Assigning Packages to a Delivery Unit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Exporting a Delivery Unit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 Importing a Delivery Unit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 Creating a Product. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .587 Assigning a Delivery Unit to a Product. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 Registering a System for a Transport Route. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 Maintaining an SAP HANA Transport Destination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 Adding a Transport Route. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .593 Modifying a Transport Route. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .595 Removing a Transport Route. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 Transporting a Delivery Unit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
Maintaining Delivery Units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Maintaining Products. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
Maintaining Transport Routes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .589
Using Database Client Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 Connecting via ODBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599 13.1.1 13.1.2 Using the User Store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 Testing the ODBC Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 Tracing JDBC Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .604 Valid Java-to-SQL Conversions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 Connecting with Microsoft Excel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 Multidimensional Expressions (MDX). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .612 MDX Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612 MDX Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .616
13.2
Connecting via JDBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 13.2.1 13.2.2
13.3
Connecting via ODBO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 13.3.1 13.3.2 13.3.3 13.3.4
Introduction to SAP HANA Development
This guide presents a developers view of SAP HANA. It explains how to use the SAP HANA development tools to create comprehensive analytical models and to build applications with SAP HANA's programmatic interfaces and integrated development environment, including to develop native code that runs inside SAP HANA. The guide is organized as follows: SAP HANA Architecture [page 10] describes the basic capabilities and architecture of SAP HANA. Developer Scenarios [page 16] describes the main developer scenarios for which you can use SAP HANA to develop applications. Getting Started [page 20] shows you how to get started building a simple SAP HANA-based application, including how to use the SAP HANA studio tools and work with the SAP HANA repository.
Most of the remaining chapters explain how to develop various SAP HANA development objects that you can include in your SAP HANA application.
Note
For the latest information about the availability of features for SAP HANA Extended Application Services (SAP HANA XS) and related development tools, please see SAP Note 1779803.
Audience
This guide is aimed at two developer roles: Modeler: This person, often a business/data analyst or database expert, is concerned with the definition of the model and schemas that will be used in SAP HANA, the specification and definition of tables, views, primary keys, indexes, partitions and other aspects of the layout and inter-relationship of the data in SAP HANA. The data modeler is also concerned with designing and defining authorization and access control, through the specification of privileges, roles and users. The modeler generally uses the Administration Console and Modeler perspectives and tools of the SAP HANA studio. Application Programmer: The programmer is concerned with building SAP HANA applications, which could take many forms but are designed based on the model-view-controller architecture. Programmers develop the code for: View, which could run inside a browser or on a mobile device Controller, which typically runs in the context of an application server Model, which interacts closely with the data model, performs efficient queries, and may be developed to run within the SAP HANA data engine, using embedded procedures or libraries
The programmer generally uses the SAP HANA Development perspective and tools of the SAP HANA studio.
SAP HANA Developer Guide Introduction to SAP HANA Development
PUBLIC
1.1
SAP HANA Architecture
SAP HANA is an in-memory data platform that is deployable on premise or on demand. At its core, it is an innovative in-memory relational database management system that makes full use of the capabilities of current hardware to increase application performance, reduce cost of ownership, and enable new scenarios and applications that were not possible before. With SAP HANA, you can build applications that integrate the business control logic and the database layer with unprecedented performance. As a developer, one of the key questions is how you can minimize data movements. The more you can do directly on the data in memory next to the CPUs, the better the application will perform.
1.1.1
SAP HANA In-Memory Database
SAP HANA runs on multi-core CPUs with fast communication between processor cores, and containing terabytes of main memory. With SAP HANA, all data is available in main memory, which avoids the performance penalty of disk I/O. Either disk or solid-state drives are still required for permanent persistency in the event of a power failure or some other catastrophe. This does not slow down performance, however, because the required backup operations to disk can take place asynchronously as a background task.
1.1.1.1
Columnar Data Storage
A database table is conceptually a two-dimensional data structure organized in rows and columns. Computer memory, in contrast, is organized as a linear structure. A table can be represented in row-order or column-order. A row-oriented organization stores a table as a sequence of records. Conversely, in column storage the entries of a column are stored in contiguous memory locations. SAP HANA supports both, but is particularly optimized for column-order storage.
Columnar data storage allows highly efficient compression. If a column is sorted, often there are repeated adjacent values. SAP HANA employs highly efficient compression methods, such as run-length encoding, cluster coding and dictionary coding. With dictionary encoding, columns are stored as sequences of bit-coded integers. That means that a check for equality can be executed on the integers; for example, during scans or join operations. This is much faster than comparing, for example, string values.
10
Columnar storage, in many cases, eliminates the need for additional index structures. Storing data in columns is functionally similar to having a built-in index for each column. The column scanning speed of the in-memory column store and the compression mechanisms especially dictionary compression allow read operations with very high performance. In many cases, it is not required to have additional indexes. Eliminating additional indexes reduces complexity and eliminates the effort of defining and maintaining metadata.
1.1.1.2
Parallel Processing
SAP HANA was designed to perform its basic calculations, such as analytic joins, scans and aggregations in parallel. Often it uses hundreds of cores at the same time, fully utilizing the available computing resources of distributed systems. With columnar data, operations on single columns, such as searching or aggregations, can be implemented as loops over an array stored in contiguous memory locations. Such an operation has high spatial locality and can efficiently be executed in the CPU cache. With row-oriented storage, the same operation would be much slower because data of the same column is distributed across memory and the CPU is slowed down by cache misses. Compressed data can be loaded into the CPU cache faster. This is because the limiting factor is the data transport between memory and CPU cache, and so the performance gain exceeds the additional computing time needed for decompression. Column-based storage also allows execution of operations in parallel using multiple processor cores. In a column store, data is already vertically partitioned. This means that operations on different columns can easily be processed in parallel. If multiple columns need to be searched or aggregated, each of these operations can be assigned to a different processor core. In addition, operations on one column can be parallelized by partitioning the column into multiple sections that can be processed by different processor cores.
PUBLIC
11
1.1.1.3
Simplifying Applications
Traditional business applications often use materialized aggregates to increase performance. These aggregates are computed and stored either after each write operation on the aggregated data, or at scheduled times. Read operations read the materialized aggregates instead of computing them each time they are required. With a scanning speed of several gigabytes per millisecond, SAP HANA makes it possible to calculate aggregates on large amounts of data on-the-fly with high performance. This eliminates the need for materialized aggregates in many cases, simplifying data models, and correspondingly the application logic. Furthermore, with on-the fly aggregation, the aggregate values are always up-to-date unlike materialized aggregates that may be updated only at scheduled times.
1.1.2
SAP HANA Database Architecture
A running SAP HANA system consists of multiple communicating processes (services). The following shows the main SAP HANA database services in a classical application context.
Such traditional database applications use well-defined interfaces (for example, ODBC and JDBC) to communicate with the database management system functioning as a data source, usually over a network
12
PUBLIC
connection. Often running in the context of an application server, these traditional applications use Structured Query Language (SQL) to manage and query the data stored in the database. The main SAP HANA database management component is known as the index server, which contains the actual data stores and the engines for processing the data. The index server processes incoming SQL or MDX statements in the context of authenticated sessions and transactions. The SAP HANA database has its own scripting language named SQLScript. SQLScript embeds data-intensive application logic into the database. Classical applications tend to offload only very limited functionality into the database using SQL. This results in extensive copying of data from and to the database, and in programs that slowly iterate over huge data loops and are hard to optimize and parallelize. SQLScript is based on side-effect free functions that operate on tables using SQL queries for set processing, and is therefore parallelizable over multiple processors. In addition to SQLScript, SAP HANA supports a framework for the installation of specialized and optimized functional libraries, which are tightly integrated with different data engines of the index server. Two of these functional libraries are the SAP HANA Business Function Library (BFL) and the SAP HANA Predictive Analytics Library (PAL). BFL and PAL functions can be called directly from within SQLScript. SAP HANA also supports the development of programs written in the R language. SQL and SQLScript are implemented using a common infrastructure of built-in data engine functions that have access to various meta definitions, such as definitions of relational tables, columns, views, and indexes, and definitions of SQLScript procedures. This metadata is stored in one common catalog. The database persistence layer is responsible for durability and atomicity of transactions. It ensures that the database can be restored to the most recent committed state after a restart and that transactions are either completely executed or completely undone. The index server uses the preprocessor server for analyzing text data and extracting the information on which the text search capabilities are based. The name server owns the information about the topology of SAP HANA system. In a distributed system, the name server knows where the components are running and which data is located on which server. The statistics server collects information about status, performance and resource consumption from the other servers in the system. Monitoring clients, such as the SAP HANA studio, access the statistics server to get the status of various alert monitors. The statistics server also provides a history of measurement data for further analysis. Related Information SAP HANA SQLScript Reference SAP HANA Business Function Library (BFL) Reference SAP HANA Predictive Analysis Library (PAL) Reference SAP HANA R Integration Guide
1.1.3
SAP HANA Extended Application Services
Traditional database applications use interfaces such as ODBC and JDBC with SQL to manage and query their data. The following illustrates such applications using the common Model-View-Controller (MVC) development architecture.
PUBLIC
13
SAP HANA greatly extends the traditional database server role. SAP HANA functions as a comprehensive platform for the development and execution of native data-intensive applications that run efficiently in SAP HANA, taking advantage of its in-memory architecture and parallel execution capabilities. By restructuring your application in this way, not only do you gain from the increased performance due to the integration with the data source, you can effectively eliminate the overhead of the middle-tier between the userinterface (the view) and the data-intensive control logic, as shown in the following figure.
In support of this data-integrated application paradigm, SAP HANA Extended Application Services provides a comprehensive set of embedded services that provide end-to-end support for Web-based applications. This includes a lightweight web server, configurable OData support, server-side JS execution and, of course, full access to SQL and SQLScript. These SAP HANA Extended Application Services are provided by the SAP HANA XS server, which provides lightweight application services that are fully integrated into SAP HANA. It allows clients to access the SAP HANA system via HTTP. Controller applications can run completely natively on SAP HANA, without the need for an additional external application server.The following shows the SAP HANA XS server as part of the SAP HANA system.
14
The application services can be used to expose the database data model, with its tables, views and database procedures, to clients. This can be done in a declarative way using OData services or by writing native applicationspecific code that runs in the SAP HANA context . Also, you can use SAP HANA XS to build dynamic HTML5 UI applications. In addition to exposing the data model, SAP HANA XS also hosts system services that are part of the SAP HANA system. The search service is an example of such a system application. No data is stored in the SAP HANA XS server itself. To read tables or views, to modify data or to execute SQLScript database procedures and calculations, it connects to the index server (or servers, in case of a distributed system).
Note
For the latest information about the availability of features for SAP HANA Extended Application Services (SAP HANA XS) and related development tools, please see SAP Note 1779803. Related Information Building UIs with SAPUI5 Enabling Search [page 397] With a SAP HANA database, your users will want to search tables and views much like they would when searching for information on the Internet. In SAP HANA, you can either directly query data using SQL queries or build search UIs using SAP HANA info access.
PUBLIC
15
1.1.4
SAP HANA-Based Applications
The possibility to run application-specific code in SAP HANA raises the question: What kind of logic should run where? Clearly, data-intensive and model-based calculations must be close to the data and, therefore, need to be executed in the index server, for instance, using SQLScript or the code of the specialized functional libraries. The presentation (view) logic runs on the client for example, as an HTML5 application in a Web browser or on a mobile device. Native application-specific code, supported by SAP HANA Extended Application Services, can be used to provide a thin layer between the clients on one side, and the views, tables and procedures in the index server on the other side. Typical applications contain, for example, control flow logic based on request parameters, invoke views and stored procedures in the index server, and transform the results to the response format expected by the client. The communication between the SAP HANA XS server and index server is optimized for high performance. However, performance is not the only reason why the SAP HANA XS server was integrated into SAP HANA. It also leads to simplified administration and a better development experience. The SAP HANA XS server completes SAP HANA to make it a comprehensive development platform. With the SAP HANA XS server, developers can write SAP HANA-based applications that cover all server-side aspects, such as tables and database views, database procedures, server-side control logic, integration with external systems, and provisioning of HTTP-based services. The integration of the SAP HANA XS server into the SAP HANA system also helps to reduce cost of ownership, as all servers are installed, operated and updated as one system.
1.2
Developer Scenarios
The possibility to run application specific code in SAP HANA creates several possibilities for developing SAP HANA based applications, representing various integration scenarios, and corresponding development processes. Broadly, we distinguish SAP HANA based applications into two broad categories: Web-based scenarios that take full advantage of the SAP HANA Extended Application Services. In these scenarios, clients access SAP HANA data using standard OData or XMLA interfaces, or directly use a Webbased GUI that was developed using the SAPUI5 toolkit, and that uses custom-developed server-side JavaScript, as well as native SQLScript procedures. Traditional client-based scenarios, where an external application accesses the SAP HANA data model (tables, analytic views, etc.) via client interfaces such as ODBC, ODBO and JDBC, and only uses SQL and native SQLScript procedures.
In either case, as a developer you need to understand the SAP HANA development environment, which enables you to design and develop your data and analytical models, and your other HANA-based development objects in the form of portable and deployable delivery units. Common activities include: Table 1: Common Activities Activity Setting up your development environment. More Information Setting Up Your Application [page 42]
16
Activity Setting up your schema and tables. Setting up views of your data. Developing procedures for data-intensive logic. Setting Up Roles and Authorizations. Managing the delivery of your application.
More Information Setting Up the Persistence Model [page 123] Setting Up the Analytic Model [page 176] Developing Procedures [page 254] The Authorization Model [page 527] SAP HANA Delivery Units [page 579]
For these activites, you will want to keep handy the following references: SAP HANA SQL and System Views Reference, to help you writing SQL statements within procedures and from your server-side JavaScript. SAP HANA SQLScript Reference, to help you if you are writing procedures.
The next two sections describes the main scenarios and what activities you may need to perform for them.
1.2.1
Scenario: Developing Native SAP HANA Applications
Here, you want to create a Web-based scenario that takes full advantage of SAP HANA Extended Application Services. In this scenario, clients access SAP HANA data using standard OData or XMLA interfaces, or directly use a Web-based GUI that was developed using the SAPUI5 toolkit, and that uses custom-developed server-side JavaScript, as well as native SQLScript procedures.
For this scenario, you may need to perform the following activities:
PUBLIC
17
Table 2: Developing Native SAP HANA Applications Activity Develop server-side JavaScript for control logic. Define OData data interfaces. Define XMLA data interfaces. Build HTML pages with SAPUI5. You will also want to keep handy the following references: SAP HANA SQL and System Views Reference, to help you write SQL statements within procedures and from your server-side JavaScript. SAP HANA XS JavaScript Reference, to help you use the SAP HANA XS JavaScript API. More Information Writing Server-Side JavaScript Code [page 319] Data Access with OData in SAP HANA XS [page 274] Data Access with XMLA in SAP HANA XS [page 305] Building UIs with SAPUI5
1.2.2
Scenario: Using Database Client Interfaces
Here, you want to build an application outside of SAP HANA, for example, within SAP NetWeaver, that accesses the SAP HANA data model (for example, tables and analytic views) via client interfaces such as ODBC, ODBO and JDBC, and only uses SQL and native SQLScript procedures.
For this scenario, you may need to perform the following activities: Table 3: Using Database Client Interfaces Activity Install and use the SAP HANA client interfaces. More Information Using Database Client Interfaces [page 599]
18
PUBLIC
Activity Develop procedures for data-intensive logic. You will also want to keep handy several references:
More Information Developing Procedures [page 254]
SAP HANA SQL and System Views Reference, to help you write SQL statements. For information on MDX in SAP HANA, see MDX Functions [page 308]. SAP HANA SQLScript Reference, to help you if you are writing procedures.
PUBLIC
19
Getting Started
To understand which tools SAP HANA Extended Application Services (SAP HANA XS) provides to enable you to start developing native applications, you need to run through the process of building a small application, for example, in the form of a Hello World application. As part of the getting-started process, you go through the following steps: Prerequisites A short list of the tools and permissions required to start working with the SAP HANA applicationdevelopment tools. Using the SAP HANA studio A quick tour of the features provided by the SAPA HANA Development perspective, which is a designed to provide the tools a developer needs to build native applications for SAP HANA. Creating an SAP HANA project Before you can start the application-development workflow, you must create a project, which you use to group all your application-related artifacts. Creating application descriptors Each native SAP HANA application requires descriptor files. The application descriptors are the core files that you use to describe an application's framework within SAP HANA XS, for example: to mark the root point from which content can be served, which content is to be exposed, or who has access to the content. Tutorials Some simple Hello World tutorials to demonstrate the application-development process in SAP HANA XS and show how to produce a simple application quickly and easily.
2.1
Prerequisites
To start working with the tools provided to enable application development on SAP HANA Extended Application Services (SAP HANA XS), it is necessary to ensure that the developers have the required software and access permissions. Before you start developing applications using the features and tools provided by the SAP HANA XS, bear in mind the following prerequisites. Developers who want to build applications to run on SAP HANA XS need the following tools, accounts, and privileges:
Note
The following can only be provided by someone who has the required authorizations in SAP HANA, for example, an SAP HANA administrator. Access to a running SAP HANA development system (with SAP HANA XS) A valid user account in the SAP HANA database on that system Access to the SAP HANA studio
Note
To provide access to the SAP HANA repository from the SAP HANA studio, the EXECUTE privilege is required for SYS.REPOSITORY_REST, the database procedure through with the REST API is tunneled.
20
SAP HANA Developer Guide Getting Started
Access to the SAP HANA client (which SAP HANA studio uses to connect to the repository) Access to the SAP HANA repository Access to selected run-time catalog objects
2.2
SAP HANA Studio
The SAP HANA studio is an Eclipse-based development and administration tool for working with SAP HANA. You use the SAP HANA studio to develop native applications that can take advantage of the benefits provided by SAP HANA Extended Application Services (SAP HANA XS). One of the most important features of the Eclipse-based environment is the perspective. SAP HANA provides a number of dedicated perspectives that are aimed at the application developer. As an application developer, you frequently use the following perspectives: The SAP HANA Development perspective Provides views and menu options that enable you to perform all the tasks relating to application development on SAP HANA XS, for example: to manage application-development projects, display content of application packages, and browse the SAP HANA repository. You can also define your data-persistence model here by using design-time artifacts to define tables, views, sequences, and schemas. The Debug perspective Provides views and menu options that help you test your applications, for example: to view the source code, monitor or modify variables, and set break points. The Modeler perspective Provides views and menu options that enable you to define your analytic model, for example, attribute, analytic, and calculation views of SAP HANA data. The Administration Console perspective Provides views that enable you to perform administrative tasks on SAP HANA instances.
2.2.1
The SAP HANA Development Perspective
The SAP HANA Development perspective is where you will do most of your programming work, for example: Creating and sharing projects Creating and modifying development objects Managing development object versions Committing development objects to the SAP HANA repository Activating development objects in the SAP HANA repository
The SAP HANA Development perspective contains the following main work areas: Explorers/Browsers Selected views enable you to browse your development artifacts: the objects on your workstation, and the objects in the repository of the SAP HANA system you are working with. Editors Specialized editors enable you to work with different types of development objects, for example, applicationconfiguration files, JavaScript source files, SQLScript files.
PUBLIC
21
2.2.1.1
The SAP HANA Repositories View
The SAP HANA Repositories view enables you to browse the contents of the repository on a specific SAP HANA system; you can display the package hierarchy and use the Checkout feature to download files to the workspace on your local file system.
22
PUBLIC
The SAP HANA Repositories view is a list of repository workspaces that you have created for development purposed on various SAP HANA systems. Generally, you create a workspace, check out files from the repository, and then do most of your development work in the Project Explorer.
2.2.1.2
The Project Explorer View
The Project Explorer view is the most commonly used element of the SAP HANA Development perspective; it shows you the development files located in the repository workspace you create on your workstation. You use the Project Explorer view to create and modify development files. Using context-sensitive menus, you can also commit the development files to the SAP HANA repository and activate them.
2.2.1.3
The SAP HANA Systems View
The SAP HANA Systems view is one of the basic elements of the SAP HANA Development perspective. You can use the SAP HANA Systems view to display the contents of the SAP HANA database that is hosting your development project artifacts. The SAP HANA Systems view of the SAP HANA database shows both activated objects (objects with a runtime instance) and the design-time objects you create but have not yet activated.
PUBLIC
23
The SAP HANA Systems view is divided into the following main sections: Security Contains the roles and users defined for this system. Catalog 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. Content Contains design-time database objects, both those that have been activated and those not activated. If you want to see other development objects, use the SAP HANA Repositories view.
24
Related Information The SAP HANA Repositories View [page 22]
2.3
SAP HANA XS Application Descriptors
Each application that you want to develop and deploy on SAP HANA Extended Application Services (SAP HANA XS) required so-called application descriptor files. The application descriptors describe an application's framework within SAP HANA XS. The framework defined by the SAP HANA XS application descriptors includes the root point in the package hierarchy where content is to be served to client requests. When defining the application framework, you also have to specify whether the application is permitted to expose data to client requests, what (if any) authentication method is required to access application content, and (optionally) what if any privileges are required to perform actions on the packages and package content that are exposed. The application descriptor 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. The application-access file The configuration file you use to specify who or what is authorized to access the content exposed by an SAP HANA XS application package and what content they are allowed to see. For example, you use the application-access file to specify the following: The application content that can be exposed to client requests The authentication method used to enable access to package content, for example, form-based, basic, or none at all.
2.4
SAP HANA Projects
In SAP HANA, a project group together all the artifacts you need for a specific part of the application-development environment. Before you can start the application-development workflow, you must create a project, which you use to group together all your application-related artifacts. However, a project requires a repository workspace, which enables you to synchronize changes in local files with changes in the SAP HANA repository. You can create the workspace before or during the project-creation step. As part of the project-creation process, you perform the following tasks: 1. 2. Add a development system Create a development workspace. The place where you work on development objects is called a repository workspace. The workspace is the link between the SAP HANA repository and your local file system. When you check out a package from the repository, SAP HANA copies the contents of the package hierarchy to your workspace. To ensure that the changes you make to project-related files are visible to other team members, you must commit the artifacts back into the repository and activate them.
PUBLIC
25
3.
Create a project You use the project to collect all your application-related artifacts in one convenient place. Shared projects enable multiple people to work on the same files at the same time.
Note
Files checked out of the repository are not locked; conflicts resulting from concurrent changes to the same file must be resolved manually, using the Merge tools provided in the context-sensitive Team menu. 4. Share a project Sharing a project establishes a link between project-specific files in your development workspace and the SAP HANA repository. A shared project ensures that changes you make to project-related files in your development workspace are synchronized with the SAP HANA repository and, as a result, visible to other team members. Shared projects are available for import by other members of the application-development team.
2.5
Tutorials
Tutorials are a good way to understand quickly what is required to write a simple native application for SAP HANA XS. In this section you can use the following tutorials to help you understand the basic steps you need to perform when developing native SAP HANA XS applications: Hello OData A simple application that enables you to test the SAP HANA OData interface by exposing an OData collection for analysis and display in a client application. Hello World in server-side JavaScript (XSJS) A simple application written in server-side JavaScript which displays the words Hello World in a Web browser along with a string extracted from a table in the SAP HANA database.
Note
The namespace sap in the SAP HANA repository is restricted. Place the new packages and application artifacts that you create during the tutorials in your own namespace, for example, com.acme, or use the system.local area for testing. Related Information Tutorial: Using the SAP HANA OData Interface [page 39] The package you put together to test the SAP HANA OData interface includes all the artifacts you need to use SAP HANA Extended Application Services (SAP HANA XS) to expose an OData collection for analysis and display by client applications. Tutorial: My First SAP HANA Application [page 27] This topic describes the steps required to develop a simple application that runs natively in SAP HANA.
26
2.5.1
Tutorial: My First SAP HANA Application
This topic describes the steps required to develop a simple application that runs natively in SAP HANA.
Context
This tutorial shows you how to use the SAP HANA studio to develop a functional SAP HANA application. Although it is simple, the tutorial demonstrates the development process that you can apply to all types of applicationdevelopment scenarios. The tutorial shows how to create a simple SAP HANA application. The application uses server-side JavaScript code to retrieve data from SAP HANA by executing SQL statements in the SAP HANA database. The retrieved data is displayed in a Web browser. During the tutorial, you use tools provided in the SAP HANA studio to perform the following tasks: Connect to an SAP HANA system Add (and connect to) an SAP HANA system, which hosts the repository where development objects are stored Create a repository workspace Create a development workspace which enables you to synchronize the development artifacts in your local file system with the repository hosted on the SAP HANA system you connect to. Create a project Add a project which you can use to hold the application-development artifacts in a convenient central location. Share the project Make the contents of the new application-development project available to other members of the applicationdevelopment team by linking the local project to the SAP HANA repository. In this way, you can manage object versions and synchronize changes to development objects. Write server-side JavaScript code Use JavaScript code to extract data from the SAP HANA database in response to a client request; the code will include SQLScript to perform the data extraction. Display data Display data extracted from the SAP HANA database in a Web browser.
Related Information Tutorial: Add an SAP HANA System [page 28] Application-development artifacts are stored and managed in the SAP HANA repository. To connect to an SAP HANA repository, you must add the system to SAP HANA studio. Tutorial: Add a Repository Workspace [page 30] The place where you work on development objects is called a repository workspace. The workspace is the link between the SAP HANA repository and your local file system. Tutorial: Add an Application Project [page 32] You use the project to collect all the development artifacts relating to a particular part of application in one convenient place. Tutorial: Share an Application Project [page 34] Sharing a project establishes a link between project-specific files in your development workspace and the repository hosted by the SAP HANA system you are connected to.
PUBLIC
27
Tutorial: Write Server-Side JavaScript [page 35] SAP HANA Extended Application Services (SAP HANA XS) supports server-side application programming in JavaScript. In this step we add some simple JavaScript code that generates a page which displays the words Hello, world!. Tutorial: Retrieve Data from SAP HANA [page 38] The final step of the data display tutorial is to extract data from the database and display it in a Web Browser.
2.5.1.1
Tutorial: Add an SAP HANA System
Application-development artifacts are stored and managed in the SAP HANA repository. To connect to an SAP HANA repository, you must add the system to SAP HANA studio.
Context
You must add a connection to the SAP HANA system hosting the repository that stores the applicationdevelopment artifacts you will be working with.
Procedure
1. In the SAP HANA Systems view, right-click anywhere in the view and select Add System.
2.
Enter the following fields for the SAP HANA system: Server name Instance number on that server A display name for this system. When you start working with a lot of systems, you will want to have a way to label the systems in the SAP HANA studio. Enter Development System.
28
PUBLIC
3. 4.
Select Next. Enter a user name and password for the connection, and select Finish.
PUBLIC
29
Results
After adding the system, you will see the system in the SAP HANA Systems view.
2.5.1.2
Tutorial: Add a Repository Workspace
The place where you work on development objects is called a repository workspace. The workspace is the link between the SAP HANA repository and your local file system.
Context
After you add the SAP HANA system hosting the repository that stores your application-development files, you must specify a repository workspace, which is the location in your file system where you save and work on the development files. To create a repository workspace, perform the following steps:
Procedure
1. 2.
In the SAP HANA Repositories view, click You must provide the following information:
in the upper-right of the view.
SAP HANA system The name of the SAP HANA system hosting the repository that you want to synchronize your workspace with; choose the same system you just added for this tutorial. Workspace Name The workspace name can be anything you like. For this tutorial, enter DevWS. A folder with this name is created below the Workspace root. Workspace root The Workspace Root is a folder that contains the workspace you create in this step. The Workspace Root can be anywhere on your local file system. For this tutorial, create a folder at C:\SAPHANAworkspaces and make this the Workspace Root.
30
3.
Click Finish.
Results
In the SAP HANA Repositories view, you will see your workspace, which enables you to browse the repository of the system tied to this workspace. You will see the repository's packages, displayed as folders.
At the same time, a folder will be added to your file system to hold all your development files.
PUBLIC
31
2.5.1.3
Tutorial: Add an Application Project
You use the project to collect all the development artifacts relating to a particular part of application in one convenient place.
Context
After you set up a development environment for the chosen SAP HANA system, you can add a project to contain all the development objects you want to create as part of the application-development process. There are a variety of project types for different types of development objects. Generally, these projects types import necessary libraries for working with specific types of development objects. In this tutorial, you create an XS Project.
Procedure
1. 2. 3. From the File menu in the SAP HANA studio, select Enter the following details for the new project: Project name Enter mycompany.myorg.testing. Since a project name must be unique within the same Eclipse workspace, a good convention is to use the fully qualified package name as the project name. Project location You can keep this as the default Eclipse workspace. New Project .
In the New Project dialog, under SAP HANA Development, select XS Project, and choose Next.
32
PUBLIC
4.
Choose Finish.
Results
The Project Explorer view, you have a project that is ready to be shared. You must share a project to associate it with your workspace and synchronize the project with the repository hosted on the SAP HANA system you are connected to.
PUBLIC
33
2.5.1.4
Tutorial: Share an Application Project
Sharing a project establishes a link between project-specific files in your development workspace and the repository hosted by the SAP HANA system you are connected to.
Context
After creating a new project, you must share it. Sharing a project associates the project with your repository workspace and synchronizes the project with the repository hosted on the SAP HANA system you are connected to. To share a project, perform the following steps:
Procedure
1. In the Project Explorer view, right-click the project you want to share, and choose the context-sensitive popup menu to display the Share Project dialog. Team Share Project in
Since you only have one workspace, the wizard selects it for you automatically. If you have more than one workspace, you must choose the workspace to host the shared project. The dialog also shows the Current project location (the current location of your project, in the repository workspace), and the New project location (where your project will be copied so it can be associated with the repository workspace).
34
Also, since Add project folder as subpackage is checked, subpackages will be created based on the name of your project. 2. Choose Finish. The shared project is displayed in the Project Explorer view associated with your workspace.
The .project file is shown with an asterisk committed to the repository. 3. Right-click the .project file, and select
, which indicates that the file has changed but has yet to be Commit from the context-sensitive popup menu to add ,
Team
your project and its files to the repository. The .project file is now displayed with a diamond icon, indicating that the latest version of the file on your workstation has been committed to the SAP HANA repository.
In addition, the SAP HANA Repositories view shows that a new hierarchy of packages has been created based on the name of your project, mycompany.myorg.testing.
2.5.1.5
Tutorial: Write Server-Side JavaScript
SAP HANA Extended Application Services (SAP HANA XS) supports server-side application programming in JavaScript. In this step we add some simple JavaScript code that generates a page which displays the words Hello, world!.
PUBLIC
35
Context
As part of this server-side JavaScript tutorial, you create the following files: MyFirstSourceFile.xsjs This contains your server-side JavaScript code. .xsapp This marks the root point in the application's package hierarchy from which content can be exposed via HTTP. You still need to explicitly expose the content and assign access controls. .xsaccess Expose your content, meaning it can be accessed via HTTP, and assign access controls, for example, to manage who can access content and how.
Procedure
1. 2. 3. In the Project Explorer view, right-click your XS project, and choose popup menu. In the New dialog, select choose Finish. The file, which is blank, opens in the SAP HANA studio's JavaScript editor. 4. In the MyFirstSourceFile.xsjs file, enter the following code and save the file: $.response.contentType = "text/html"; $.response.setBody( "Hello, World !"); This uses the SAP HANA XS JavaScript API's response object to write out HTML. By typing $. you have access to the API's objects. 5. Add a blank file called .xsapp (no name, just a file extension) by right-clicking to the root of your project. To add a file, right-click the project to which you want to add a new file, select context-sensitive popup menu, enter a file name, and choose Finish. 6. new .xsaccess file: { New File from the SAP HANA Development New Other in the context-sensitive
XS JavaScript Source File .
In the New XS JavaScript Source File dialog, enter MyFirstSourceFile.xsjs in File name text boc, and
Add a file called .xsaccess (no name, just a file extension), and copy the following code into the
"exposed" : true, "authentication" : [ { "method" : "Basic" } ]
This code exposes the contents via HTTP, and requires you to log in with your SAP HANA credentials to access the file. 7. Commit the new files to the SAP HANA repository. Right-click the project containing the files you added and choose sensitive popup menu. Team Commit from the context-
36
The commit operation adds your new files (.xsjs, .xsapp, .xsaccess and .project) to the repository. After the commit operation completes, only you can see the new files, and no one can run them. 8. Activate the new files in the SAP HANA repository. Right-click on the project, and select Team Activate .
The activate operation publishes your work, and you can now test it.
Results
To access your JavaScript code, open a browser and enter the following URL: http://myServer:8000/mycompany/myorg/testing/MyFirstSourceFile.xsjs
Note
Change the server name to your server. The port number is 80<SAPHANA_ID>, where <SAPHANA_ID> is two digits representing your SAP HANA instance number. For example, if your SAP HANA instance is 00, then the port number to use is 8000. If everything works as expected, you should see the following result:
After logging in with your SAP HANA user name and password, the following page should be displayed:
PUBLIC
37
2.5.1.6
Tutorial: Retrieve Data from SAP HANA
The final step of the data display tutorial is to extract data from the database and display it in a Web Browser.
Context
To extract data from the database we use our JavaScript code to open a connection to the database and then prepare and run an SQL statement. The results are added to the response which is displayed in the Web Browser. You use the following SQL statement to extract data from the database: select * from DUMMY The SQL statement returns one row with one field called DUMMY, whose value is X.
Procedure
1. 2. Open the MyFirstSourceFile.xsjs in the JavaScript editor. In MyFirstSourceFile.xsjs, replace your existing code with the code in the following example. $.response.contentType = "text/html"; var output = "Hello, World !<br><br>"; var conn = $.db.getConnection(); var pstmt = conn.prepareStatement( "select * from DUMMY" ); var rs = pstmt.executeQuery(); if (!rs.next()) { $.response.setBody( "Failed to retrieve data" ); $.response.status = $.net.http.INTERNAL_SERVER_ERROR; } else { output = output + "This is the response from my SQL: " + rs.getString(1); } rs.close(); pstmt.close(); conn.close(); $.response.setBody(output); 3. 4. Save the file MyFirstSourceFile.xsjs. Commit the file MyFirstSourceFile.xsjs by right-clicking the file and choosing Team Commit .
38
PUBLIC
5.
Activate the file MyFirstSourceFile.xsjs by right-clicking the file and choosing
Team
Activate .
Results
In your browser, refresh the page. If everything works as expected, you should see the following page:
2.5.2
Tutorial: Using the SAP HANA OData Interface
The package you put together to test the SAP HANA OData interface includes all the artifacts you need to use SAP HANA Extended Application Services (SAP HANA XS) to expose an OData collection for analysis and display by client applications.
Prerequisites
Since the artifacts required to get a simple OData application up and running are stored in the repository, it is assumed that you have already performed the following tasks: Create a development workspace in the SAP HANA repository Create a project in the workspace Share the new project
Context
To create a simple OData application, perform the following steps:
Procedure
1. Create a root package for your OData application, for example, helloodata and save and activate it in the repository.
PUBLIC
39
Note
The namespace sap is restricted. Place the new package in your own namespace, which you can create alongside the sap namespace. 2. 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 that you save in the repository and which you must activate. Enter the following code in the HELLO_ODATA.hdbschema file: schema_name="HELLO_ODATA"; 3. Create the database table that contains the data to be exposed by your OData service definition, for example, otable.hdbtable. The database table is a flat file with the file extension .hdbtable that you save in the repository and which you must activate. 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"]; 4. Grant SELECT privileges to the owner of the new schema. After activation in the repository, the 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 in the SAP HANA studio's Modeler perspective, you must grant the user the required SELECT privilege. a) In the SAP HANA studio SAP HANA Systems view, right-click the SAP HANA system hosting the repository where the schema was activated and choose SQL Console in the context-sensitive popup menu. b) In the SQL Console, execute the statement illustrated in the following example, where <SCHEMANAME> is the name of the newly activated schema, and <username> is the database user ID of the schema owner: call _SYS_REPO.GRANT_SCHEMA_PRIVILEGE_ON_ACTIVATED_CONTENT('select','<SCHEMANAME>', '<username>'); 5. Create an application descriptor for your new OData application in your root OData package helloodata. The application descriptor (.xsapp) is the core file that you use to define an application's availability within SAP HANA application. The .xsapp file sets the point in the application-package structure from which content will be served to the requesting clients.
40
PUBLIC
Note
The application-descriptor file has no content and no name; it only has the extension .xsapp. 6. 7. Save, commit, and activate the application-descriptor file in the repository. Create an application-access file for your new OData application and place it in your root OData package helloodata. The application-access file enables you to specify who or what is authorized to access the content exposed by the application.
Note
The application-access file has no name; it only has the extension .xsaccess. Enter the following content in the .xsaccess file for your new OData application: { } 8. 9. "exposed" : true
Save, commit, and activate the application-access file in the repository. Create an OData service-definition file and place it in your root OData package helloodata. 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: Enter the following content in the hello.xsodata OData service-definition file: service { "helloodata::otable"; }
10. Save, commit, and activate the OData service-definition file in the repository. 11. Open a browser and enter the following URL. http://<hana.server.name>:80<HANA_instance_number>/helloodata/hello.xsodata
PUBLIC
41
Setting Up Your Application
In SAP HANA Extended Application Services (SAP HANA XS), the design-time artifacts that make up your application are stored in the repository like files in a file system. You first choose a root folder for your applicationdevelopment activities, and within this folder you create additional subfolders to organize the applications and the application content according to your own requirements.
Note
For the latest information about the availability of features for SAP HANA Extended Application Services (SAP HANA XS) and related development tools, see SAP Note 1779803. As part of the application-development process, you typically need to perform the tasks described in the following list. Each of the tasks in more detail is described in its own section: Table 4: Application Setup Steps Step 1 Action Check prerequisites Notes Before you start developing applications using the features and tools provided by the SAP HANA XS, developers who want to build applications to run on SAP HANA XS need to be granted access to development tools, SAP HANA systems, database accounts, and so on. To create and manage delivery units, for example, using the SAP HANA XS Lifecycle Manger, you must set the identity of the vendor with whom the delivery units are associated. To avoid conflicts with applications from SAP or other providers, we recommend that you use the DNS name of your company as the name of your root applicationdevelopment folder, for example, acme.com.
Set up delivery units
Set up an SAP HANA project In SAP HANA, projects enable you to group together all the artifacts you need for a specific part of the application-development environment. To create a project, you must first create a repository workspace, a directory structure to store files on your PC. Maintain repository packages 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, which you use to manage the artifacts in your applications. 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 defines if the application is permitted to expose data to client requests, what kind of access to the data is allowed. As part of the application-development process, you must decide how to grant access to the applications you develop. For example, you must specify which (if any) authentication method is used to grant access to content exposed by an application, and what content is visible.
Maintain application descriptors
Maintain application security
42
SAP HANA Developer Guide Setting Up Your Application
3.1
Roles and Permissions
To enable application-developers to start building native applications that take advantage of the SAP HANA Extended Application Services (SAP HANA XS), the SAP HANA administrator must set up the applicationdevelopment environment in such a way that developers have access to the tools and objects that they need to perform the tasks required during the application-development process. Before you start developing applications using the features and tools provided by the SAP HANA XS, bear in mind the following prerequisites. Developers who want to build applications to run on SAP HANA XS need the following tools, accounts, and privileges:
Note
The following privileges can only be granted by someone who has the required authorizations in SAP HANA, for example, an SAP HANA administrator. Access to a running SAP HANA development system (with SAP HANA XS) A valid user account in the SAP HANA database on that system Access to SAP HANA studio tools Access to the SAP HANA client (which SAP HANA studio uses to connect to the repository) Access to the SAP HANA repository Access to selected run-time catalog objects
Note
To provide access to the repository for application developers, you can use a predefined role or create your own custom role to which you assign the privileges that the application developers need to perform the everyday tasks associated with the application-development process. To provide access to the repository from the SAP HANA studio, the EXECUTE privilege is required for SYS.REPOSITORY_REST, the database procedure through with the REST API is tunneled. To enable the activation and data preview of information views, the technical user _SYS_REPO also requires SELECT privilege on all schemas where source tables reside. In SAP HANA, you can use roles to assign one or more privileges to a user according to the area in which the user works; the role defines the privileges the user is granted. For example, a role enables you to assign SQL privileges, analytic privileges, system privileges, package privileges, and so on. To create and maintain artifacts in the SAP HANA repository, you can assign application-development users the following roles: One of the following: MODELING The predefined MODELING role assigns wide-ranging SQL privileges, for example, on _SYS_BI and _SYS_BIC. It also assigns the analytic privilege _SYS_BI_CP_ALL, and some system privileges. If these permissions are more than your development team requires, you can create your own role with a set of privileges designed to meet the needs of the application-development team. Custom DEVELOPMENT role A user with the appropriate authorization can create a custom DEVELOPMENT role specially for application developers. The new role would specify only those privileges an application-developer needs to perform the everyday tasks associated with application development, for example: maintaining packages in the repository, executing SQL statements, displaying data previews for views, and so on.
PUBLIC
43
PUBLIC This is a role that is assigned to all users by default.
Related Information Creating Roles in the Repository [page 534] You model roles in the SAP HANA repository in a domain-specific language (DSL). Defining Repository Package Privileges [page 59] In the SAP HANA repository, 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. You can also specify if the assigned user authorizations can be passed on to other users.
3.2
Maintaining Delivery Units
A delivery unit is a collection of packages that are to be transported together. You assign all the packages belonging to your application to the same delivery unit to ensure that they are transported consistently together within your system landscape. Each delivery unit has a unique identity.
Prerequisites
To maintain delivery units with the SAP HANA Application Lifecycle Manager, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been granted the SAP HANA user role sap.hana.xs.lm.roles::Administrator A vendor ID is already defined
Context
The identity of a delivery unit consists of two parts: a vendor name and a delivery-unit name. The combined ID ensures that delivery units from different vendors are easy to distinguish and follows a pattern that SAP uses for all kinds of software components. To create and manage delivery units you first need to maintain the identity of the vendor, with whom the delivery units are associated, and in whose namespace the packages that make up the delivery unit are stored. As part of the vendor ID maintenance process, you must perform the following tasks:
Procedure
1. Understand delivery units
44
You must be familiar with the conventions that exist for delivery-unit names and understand the phases of the delivery-unit lifecycle. 2. Maintain details of the vendor ID associated with a delivery unit. Delivery units are located in the namespace associated with the vendor who creates them and who manages the delivery-unit's lifecycle. 3. 4. Create a delivery unit. Assign packages to a delivery unit.
Related Information Maintaining the Delivery-Unit Vendor ID [page 45] In SAP HANA, the vendor ID is used primarily to define the identity of the company developing a software component, which it plans to ship for use with SAP HANA, for example, sap. If you want to create a delivery unit, it is a prerequisite to maintain a vendor ID in your system. Creating a Delivery Unit [page 46] A delivery unit is a group of transportable objects used for content delivery. You can use the SAP HANA Application Lifecycle Manager to create a delivery unit for your application content or your software component.
3.2.1
Maintaining the Delivery-Unit Vendor ID
In SAP HANA, the vendor ID is used primarily to define the identity of the company developing a software component, which it plans to ship for use with SAP HANA, for example, sap. If you want to create a delivery unit, it is a prerequisite to maintain a vendor ID in your system.
Prerequisites
To set the vendor ID, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been assigned the SAP HANA XS user role sap.hana.xs.lm.roles::Administrator
Context
Before creating your first own delivery unit you must set the identity of the vendor in the development system's configuration. To maintain details of the delivery-unit vendor ID, perform the following steps:
Procedure
1. Start the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm
PUBLIC
45
Note
To start the SAP HANA Application Lifecycle Manager, you must use the logon credentials of an existing database user, who has the appropriate user role assigned. 2. 3. Switch to the CONFIGURATION tab. Maintain details of the vendor ID. In the CONFIGURATION tab, perform the following steps: a) Choose Change Vendor. b) In the Setup Vendor dialog, enter the name of the new vendor, for example, mycompany.com. c) Choose OK to save the changes. The new vendor ID is displayed in the Vendor box.
Note
The vendor ID is required to create a delivery unit.
3.2.2
SAP HANA Delivery Unit Naming Conventions
The delivery unit (DU) is the vehicle that lifecycle management (LCM) uses to ship software components from SAP (or a partner) to a customer. The DU is also the container you use to transport application content in your system landscape. In SAP HANA, the name of a DU must adhere to conventions and guidelines. If you create a delivery unit, the name of the new delivery unit must adhere to the following conventions A delivery-unit name must contain only capital letters (A-Z), digits (0-9), and underscores (_). You cannot use an underscore (_) as the first character of a delivery-unit name. The maximum length of a delivery-unit name must not exceed 30 characters
Note
The naming conventions for packages in a delivery unit differ from the naming conventions that apply to the delivery unit itself. For example, the maximum length of a package name is not restricted to 30 characters; however, it must be less than 190 characters (including the namespace hierarchy).
3.2.3
Creating a Delivery Unit
A delivery unit is a group of transportable objects used for content delivery. You can use the SAP HANA Application Lifecycle Manager to create a delivery unit for your application content or your software component.
46
PUBLIC
Prerequisites
To create a delivery unit with the SAP HANA Application Lifecycle Manager, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been granted the SAP HANA user role sap.hana.xs.lm.roles::Administrator The vendor ID is defined for the delivery unit; the vendor ID defines the repository namespace in which the new delivery unit resides
Context
You use a delivery unit to transport the design-time objects that are stored in the SAP HANA repository between two systems, for example, from a development system to a consolidation system. To create a new delivery unit using the SAP HANA Application Lifecycle Manager, perform the following steps.
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. 5. Choose the PRODUCTS tab. Choose the DELIVERY UNITS tab. Choose the plus sign (+) on the left-hand side of the DELIVERY UNITS tab. The New Delivery Unit dialog box appears. Enter details of the new delivery unit. When entering details, note the following points: Name The field is mandatory and you must follow strict naming conventions, for example, use capital letters. Vendor ID This field is mandatory. However, you cannot enter a vendor ID here; the box is populated by the value you enter when defining the vendor ID in the CONFIGURATION tab. Version Version numbers must take the form #.#.#, for example, 1.0.5, where: 1 = the DU version number 0 = the support package version (if required) 5 = the patch version (if required)
Note
The numbers you enter here refer to the application component that you are developing; the numbers do not refer to the patch or service-pack level deployed on the SAP HANA server.
PUBLIC
47
6.
Choose Create. The new delivery unit is added to the SAP HANA repository in the namespace specified by the vendor ID and the application path.
7.
Check the status bar at the bottom of the browser window for error messages. Click the message link to display the message text.
Results
You have created a delivery unit. Related Information SAP HANA Application Lifecycle Manager [page 563] The SAP HANA Application Lifecycle Manager enables you to create your product, delivery unit, package, and basic application components. Additionally, the SAP HANA Application Lifecycle Manager enables administrators to set up the transport of delivery units, start and monitor transports, and upload or download delivery unit archives.
3.3
Using SAP HANA Projects
Projects group together all the artifacts you need for a specific part of the application-development environment.
Context
Before you can start the application-development workflow, you must create a project, which you use to group together all your application-related artifacts. However, a project requires a repository workspace, which enables you to synchronize changes in local files with changes in the repository. You can create the workspace before or during the project-creation step. As part of the project-creation process, you perform the following tasks:
Procedure
1. Create a development workspace. The workspace is the link between the SAP HANA repository and your local filesystem, where you work on project-related objects. 2. Create a project. Create a new project for a particular application or package; you can use the project to collect in a convenient place all your application-related artifacts. 3. Share a project.
48
Sharing a project enables you to ensure that changes you make to project-related files are visible to other team members and applications. Shared projects are available for import by other members of the application-development team.
Note
Files checked out of the repository are not locked; conflicts resulting from concurrent changes to the same file must be resolved manually, using the Merge tools provided in the context-sensitive Team menu. 4. Import a project. Import a project (and its associated artifacts) that has been shared by another member of the applicationdevelopment team. Related Information Creating a Repository Workspace [page 50] A workspace is a local directory that you map to all (or part) of a package hierarchy in the SAP HANA repository. When you check out a package from the repository, SAP HANA copies the contents of the package hierarchy to your workspace, where you can work on the files. Creating a Project for SAP HANA XS [page 51] Before you can start the application-development workflow, you must create a project, which you use to group all your application-related artifacts. Sharing a Project for SAP HANA XS [page 52] Before you can start working on files associated with a new project, you must share the project; sharing a project enables you to track and synchronize local changes with the repository. Importing a Project in SAP HANA XS [page 54] Before you can start the application-development workflow, you must either create a new project and share it (with the repository), or import a shared project from the repository into your workspace. Importing a project enables you to track and synchronize local changes with the colleagues working on the objects in the imported project.
3.3.1
SAP HANA Repository: Workspaces
The place where you work on project-related objects is called a repository workspace. A workspace is an environment that maps a local directory to all (or part) of a package hierarchy in the SAP HANA repository. In SAP HANA studio, the repository tools enable you to browse the entire hierarchy of design-time objects stored in the repository. However, when you check a package out of the repository, SAP HANA copies the contents of the package hierarchy to your workspace, where you can work on the files in your local file system.
Note
Before you can create a workspace you must maintain connection information in the SAP HANA database user store. To start development work with SAP HANA studio, for example, to checkout the contents of a package, you must create a repository workspace. The workspace contains a system folder with metadata and package folders for the repository content. The file-system folders and their subfolders reflect the package hierarchy in the repository; the repository client ensures that changes are synchronized.
PUBLIC
49
3.3.2
Creating a Repository Workspace
A workspace is a local directory that you map to all (or part) of a package hierarchy in the SAP HANA repository. When you check out a package from the repository, SAP HANA copies the contents of the package hierarchy to your workspace, where you can work on the files.
Context
Before you can start work on the development of the application, you need to set up a workspace, where you store checked-out copies of your applications source-code files. To create a new workspace in the SAP HANA studio, perform the following steps:
Procedure
1. 2. 3. 4. 5. Open the SAP HANA studio. Open the SAP HANA Development perspective. Choose the SAP HANA Repositories view. Choose Create Workspace The Create Workspace button is located in the top right-hand corner of the SAP HANA Repositories view. Specify the workspace details. In the Create New Repository Workspace dialog, enter the following information and choose Finish: a) Specify the SAP HANA system, for which you want to create a new workspace. b) Enter a workspace name, for example the name of the SAP HANA system where the repository is located. To avoid the potential for confusion, it is recommended to associate one workspace with one repository. c) Specify where the workspace root directory should be located on your local file system, for example: C: \users\username\workspaces The new workspace is displayed in the SAP HANA Repositories view.
Note
Although the packages and objects in the chosen repository are visible in the SAP HANA Repositories view, you cannot open or work on the objects here. To work on objects, you must create a project and use the Project Explorer view.
3.3.3
SAP HANA Studio Projects
Before you can start the application-development workflow, you must create a project, which you use to group all your application-related artifacts.
50
Projects group together all the artifacts you need for a specific part of the application-development environment. A basic project contains folders and files. More advanced projects are used for builds, version management, sharing, and the organization and maintenance of resources. Projects enable multiple people to work on the same files at the same time. You can use SAP HANA studio to perform the following project-related actions in the repository: Checkout folders and files from the repository Commit changes to the repository Activate the committed changes Revert inactive changes to the previously saved version
Note
Files checked out of the repository are not locked; conflicts resulting from concurrent changes to the same file must be resolved manually, using the Merge tools provided in the context-sensitive Team menu. By committing project-related files to the repository and activating them, you enable team members to see the latest changes. The commit operation detects all changes in packages that you configure SAP HANA studio tool to track and writes the detected changes back to the repository. The repository client tools also support synchronization with changes on the server, including conflict detection and merging of change. All workspacerelated repository actions are available as context-sensitive menu options in SAP HANA studio. For example, if you right click a repository object at the top of the package hierarchy in the Project Explorer in SAP HANA studio, you can commit and activate all changed objects within the selected hierarchy.
Note
If you create a new project using SAP HANA studio, you can assign the new project to an existing workspace. You can share and unshare projects. Sharing a project associates it with a particular package in the repository linked to a particular workspace. The act of sharing the project sets up a link between the workspace and the repository and enables you to track and synchronize local changes with the versions of the objects stored in the repository. When a project is shared, it becomes available to other people with authorization to access to the repository, for example, colleagues in an application-development team. Team members can import a shared project and see and work on the same files as the creator of the project.
Note
Always unshare a project before deleting it. In the SAP HANA studio you can create a project at any package level, which enables a fine level of control of the artifacts that may (or may not) be exposed by sharing the project.
3.3.4
Creating a Project for SAP HANA XS
Before you can start the application-development workflow, you must create a project, which you use to group all your application-related artifacts.
PUBLIC
51
Context
Projects group together all the artifacts you need for a specific part of your application-development environment. A basic project contains folders and files. More advanced projects are used for builds, version management, sharing, and the organization and maintenance of resources. To create a new project in the SAP HANA studio, perform the following steps:
Procedure
1. 2. 3. 4. Open the SAP HANA studio. Open the SAP HANA Development perspective. Choose the Project Explorer view. Right-click the white space in the Project Explorer view and choose New > Project in the popup menu. The type of project you create determines the details you have to provide in the New Project dialog that appears. a) Enter a project name that describes what the project is about, for example: XS_JavaScript, XS_OData or XS_SAPUI5. b) Click Finish to create the new project. The new project is displayed in the Project Explorer view.
Note
The contents of the project depend on the type of project you create. For example, a general project is empty immediately after creation; a JavaScript project contains all the resource files associated with a JavaScript project, such as libraries and build-environment artifacts.
3.3.5
Sharing a Project for SAP HANA XS
Before you can start working on files associated with a new project, you must share the project; sharing a project enables you to track and synchronize local changes with the repository.
Context
When you share a project, you set up a connection to the SAP HANA repository associated with a particular SAP HANA instance. Sharing the project enables you to ensure that changes you make to project-related files are visible to other team members and applications. Other developers can import a shared project and work on the same files.
52
Note
Use the Project Explorer view in the SAP HANA studio to check if a project is shared. In addition to the project name, a shared project displays the SAP HANA system ID of the repository where the shared artifacts are located, an SAP HANA user name, and the path to the repository package to which the shared project is assigned, for example. "XSJS_myproject [SID (dbusername, 'sap.hana.xs.app1')]. To share a project in the SAP HANA studio, perform the following steps:
Procedure
1. 2. 3. 4. Open the SAP HANA studio Open the SAP HANA Development perspective. Open the Project Explorer view. Share the project Right-click the project you want to share and choose 5. Select the repository type. The Share Project dialog displays a list of all available repository types; choose SAP HANA Repository and choose Next. 6. 7. Select the repository workspace where the project should be located. Specify the package that you want to associate the shared project with. The Share Project dialog displays the suggested location for the shared project in the New Project location screen area. The default location is the name of the workspace with the name of the project you want to share. Choose Browse... to locate the package you want to associate the shared project with. The selected package is displayed in the Path to package text box. Team Share Project in the pop-up menu.
Note
The Keep project folder option appends the name of the project you are sharing to the name of the workspace in which you are sharing the project and creates a new package with the name of the shared project under the workspace location displayed. Use this option only if you want to create multiple projects for a selected package, for example, if you are creating a root project in your root application package. 8. 9. Click Finish to complete the project-sharing procedure. Add new files as required At this point you can start adding project-specific files to the shared project. These artifacts can then be committed to the repository, where they reside as inactive objects until they are activated, for example, using the Team Activate option in the context-sensitive menus available in the Project Explorer view.
Note
The Project Explorer view decorates the file icons to indicate the current state of the repository files, for example: local (not yet committed), committed (inactive), and active (available for use by others). 10. Make the project available for import, for example, so that others can join it and make changes to project content.
PUBLIC
53
The project-sharing procedure creates some artifacts (for example, the .project file) that must be committed to the repository and activated so that other team members can import the project more easily into their workspace. The .project file is used in several dialogs to populate the list of available projects.
Note
Use the SAP HANA Repositories view to import projects (and checkout project content). Related Information Importing a Project in SAP HANA XS [page 54] Before you can start the application-development workflow, you must either create a new project and share it (with the repository), or import a shared project from the repository into your workspace. Importing a project enables you to track and synchronize local changes with the colleagues working on the objects in the imported project.
3.3.6
Importing a Project in SAP HANA XS
Before you can start the application-development workflow, you must either create a new project and share it (with the repository), or import a shared project from the repository into your workspace. Importing a project enables you to track and synchronize local changes with the colleagues working on the objects in the imported project.
Context
To import an existing project from the repository into your workspace, perform the following steps.
Procedure
1. 2. 3. 4. Open the SAP HANA studio Open the SAP HANA Development perspective. Choose the HANA Repositories view. Right-click the package where the project you want to import is located and choose Checkout and Import Projects... in the popup menu. Projects can be assigned to a package at any level of the package hierarchy. If you know where the project is located, browse to the package first before choosing the Checkout and Import Projects... option. This reduces the amount of files to checkout and download to your local file system.
Note
The existence of a .project file in a package identifies the package as being associated with a project. The SAP HANA studio checks out the content of the selected package and displays any projects it finds in the Projects screen area.
54
PUBLIC
5. 6.
Select the projects to import. If multiple projects are available for import, select the projects you want to import. Choose Finish to import the selected projects. You can add the imported project to your Working Sets.
Note
A working set is a concept similar to favorites in a Web browser, which contain the objects you work on most frequently.
3.4
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.
Note
You can also create and delete packages in the Project Explorer, for example, by creating or deleting folders in shared projects and committing and activating these changes. However, to maintain advanced package properties (for example, privileges, component, the package maintainer, and so on) you must use the Modeling perspective in the SAP HANA studio. As part of the process of maintaining your application packages, you typically perform the following tasks:
Procedure
1. Creating a package Packages are necessary to group logically distinct artifacts together in one object location that is easy to transport. 2. Defining 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.
PUBLIC
55
3.
Defining 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.
Related Information Creating a Package [page 60] 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. Defining the Package Hierarchy [page 60] Packages belonging to an application-development delivery unit (DU) should be organized in a clear hierarchical structure under a single root package representing the vendor, for example, acme.com. Defining Package Privileges [page 59] In the SAP HANA repository, 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. You can also specify if the assigned user authorizations can be passed on to other users.
3.4.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. 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.
56
Package Hierarchy
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 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.
Note
You can only assign one project per package; this is important to remember if you have a mixture of designtime objects that need to be used in multiple projects, for example: server-side JavaScript (XSJS), SAPUI5, and a general project (for procedures). 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
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.
Package Types
SAP HANA Application Services provide or allow the following package types:
PUBLIC
57
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 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.
Package Naming Conventions

The following rules apply to package names: Permitted characters Lower/upper case letters (aA-zZ), digits (0-9), hyphens (-), 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 maximum permitted length of a package name is 190 characters. To avoid problems, we recommend you restrict the length of package names to well under the 190-character limit. Package namespace 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. To avoid problems, we recommend you restrict the length of the package namespace to well under the 190-character limit.
58
3.4.2
Defining Repository Package Privileges
In the SAP HANA repository, 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. You can also specify if the assigned user authorizations can be passed on to other users.
Context
To set user (or role) authorizations for repository packages, perform the following steps:
Procedure
1. 2. Open the SAP HANA Systems view in the SAP HANA studio's Modeler perspective. In the SAP HANA Systems view, expand the Security Roles/Users repository that contains the packages you want to grant access to. node for the system hosting the
You can also define roles via source files; roles defined in this way can be assigned to a delivery unit and transported to other systems. 3. 4. 5. 6. 7. 8. Double click the user (or role) to whom you want to assign authorizations. Open the Package Privileges tab page. Choose [+] to add one or more packages. Press and hold the Ctrl key to select multiple packages. In the Select Repository Package dialog, use all or part of the package name to locate the repository package that you want to authorize access to. Select one or more repository packages that you want to authorize access to; the selected packages appear in the Package Privileges tab page. Select the packages to which you want authorize access and, in the Privileges for screen page, check 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
PUBLIC
59
3.4.3
Creating a Package
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 packages to manage the various elements of your application development project. To create a package, perform the following steps:
Procedure
1. 2. 3. In the SAP HANA studio, start the SAP HANA Development perspective. In the SAP HANA Systems view, select the SAP HANA system where you want to create a new package and expand the Content node to display the namespace hierarchy for package content. Right-click the package where you want to add a new package and choose context-sensitive popup menu. SAP HANA studio displays the New Package dialog. Maintain the package details. In the New Package dialog, enter information in the following fields: a) Enter a name for the new package. The package Name is mandatory. Add the new name to the end of the full package path, for example, acme.com.package1. b) Fill in the other optional information as required: Use the Delivery Unit drop-down list to assign the new package to a delivery unit. Choose Translation if you intend to have the package content localized. You must maintain the translation details. 5. 6. Create the new package. In the New Package dialog, click OK to create a new package in the specified location. Activate the new package. In the SAP HANA Systems view, right-click the new package and choose Activate from the context-sensitive popup menu. Related Information SAP HANA Delivery-Unit Translation Details New Package... in the
4.
3.4.4
Defining a Package Hierarchy
Packages belonging to an application-development delivery unit (DU) should be organized in a clear hierarchical structure under a single root package representing the vendor, for example, acme.com.
60
Context
The package hierarchy for a new project might include 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.
Note
You can only assign one project per package; this is important to remember if you have a mixture of designtime objects that need to be used in multiple projects, for example: server-side JavaScript (XSJS), SAPUI5, and a general project (for procedures). The following simple example shows a package structure containing tutorials for the use of a new application: acme \
hana \
app1
docs
tutorials
Package hierarchy Each vendor uses a dedicated namespace, for example, acme.
Note
Do not use the namespace sap to build your application hierarchy. The namespace sap is reserved for use by SAP; packages created in the sap namespace are overwritten by system updates. 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.
To set up a package hierarchy in the SAP HANA repository, perform the following steps:
Procedure
1. Create a new root package. Open the Modeler perspective and perform the following steps: a) Choose b) Choose 2. New > Package Create... .
Maintain the package details. In the Create Package dialog, perform the following steps: a) Enter the name of the package (mandatory).
PUBLIC
61
Guidelines and conventions apply to package names. b) Enter a package description (optional). c) Specify the delivery unit that the package is assigned to. You can add additional packages to a delivery unit at a later point in time, too. d) Specify a language for the package content. e) Assign responsibility of the package to a specific user (optional). By default, the responsible user for a new package is the database user connected to the SAP HANA repository in the current SAP HANA studio session. f) Maintain translation details. If you plan to have the content translated, you need to maintain the translation details; this is covered in another topic. 3. Create a new subpackage. In the SAP HANA Systems view of the Modeler perspective, perform the following steps: a) Right-click the package to which you want to add a new subpackage. b) In the pop-up menu, choose 4. Maintain the subpackage details. In the Create Package dialog, perform the following steps: a) Enter the name of the subpackage (mandatory). Guidelines and conventions apply to package names. b) Enter a description for the new subpackage (optional). c) Specify the delivery unit that the subpackage is assigned to. You can add additional packages to a delivery unit at a later point in time, too. d) Specify a language for the subpackage content. e) Assign responsibility of the subpackage to a specific user (optional). By default, the responsible user for a new package is the database user connected to the SAP HANA repository in the current SAP HANA studio session. f) Maintain translation details. If you plan to have the content translated, you need to maintain the translation details; this is covered in another topic. Related Information SAP HANA Delivery Unit Naming Conventions [page 46] The delivery unit (DU) is the vehicle that lifecycle management (LCM) uses to ship software components from SAP (or a partner) to a customer. The DU is also the container you use to transport application content in your system landscape. In SAP HANA, the name of a DU must adhere to conventions and guidelines. New > Package...
3.5
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.
62
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. Creating the 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. Creating the application-access file. The application-access 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. 3. Creating the application-privileges file. (Optional) The application-privileges file can be used to define the authorization privileges required for access to an application, for example, to start the application or to perform administrative actions on an application. Related Information Create an application descriptor [page 64] 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. Create an application-access file [page 75] The application-access 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. Create an application-privileges file [page 79] The application-privileges (.xsprivileges) file enables you to define the authorization levels required for access to 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.
3.5.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.
PUBLIC
63
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 contents and no name; it only has the file extension xsapp, for example, .xsapp. For backward compatibility, content is allowed in the .xsapp file but ignored. The application descriptor file performs the following operations: Determines the called application The application root is determined by the package containing the .xsapp file. If the package sap.test contains the file .xsapp, the application will be available under the URL http://<host>:<port>/ sap.test/.
3.5.2
Creating an Application Descriptor File
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.
Context
The package that contains the application-descriptor file becomes the root path of the resources exposed by the application you develop.
Procedure
1. Create a root package for your application, for example, MyPackage.
Note
The namespace sap is restricted. Place the new package in your own namespace, which you can create alongside the sap namespace. a) Start the SAP HANA studio and open the SAP HANA Development perspective. b) In the Project Explorer view, right-click the folder where you want to create the new (MyPackage) package. c) In the context-sensitive popup menu, choose d) Enter the name MyPackage and choose Finish. 2. Activate the new package in the repository. a) In the SAP HANA Development perspective, open the Project Explorer view and right-click the new (MyPackage) package. New Folder .
64
PUBLIC
b) In the context-sensitive popup menu, choose 3. created in the previous step.
Team
Activate .
Create an application descriptor for your new application and place it in the package (MyPackage) you The application descriptor is the core file that you use to indicate an application's availability within SAP HANA XS. The application descriptor marks the point in the package hierarchy at which an application's content is available to clients. The application-descriptor file has no contents and no name; it only has the file extension .xsapp.
Note
For backward compatibility, content is allowed in the.xsapp file but ignored. a) In the SAP HANA studio and open the SAP HANA Development perspective. b) In the Project Explorer view, right-click the folder where you want to create the new (.xsapp) file. c) In the context-sensitive popup menu, choose d) Enter the name .xsapp and choose Finish. Files with names that begin with the period (.), for example, .xsapp, are sometimes not visible in the Project Explorer. To enable the display of all files in the Project Explorer view, use the Available Customization 4. option and clear all check boxes. Save and activate your changes and additions. a) In the SAP HANA Development perspective, open the Project Explorer view and right-click the new (.xsapp) package. b) In the context-sensitive popup menu, choose Team Activate . Customize View New File .
3.5.3
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 is associated with the package it belongs to as well as any subpackages lower in the package hierarchy. Multiple .xsaccess files are allowed, but only at different levels in the package hierarchy. This enables you to specify different application-access rules for individual packages and subpackages in the package hierarchy.
Note
You cannot place two .xsaccess files in the same package. Furthermore, the rules specified in a .xsaccess file that is associated with a subpackage take precedence over any rules specified in a .xsaccess file associated with any parent package higher up the package hierarchy.
PUBLIC
65
The application-access file performs the following operations: Authentication rules Use the authentication keyword to enable authorization for the requests in URLs either at the application level or for single packages in an application. The following authentication methods are supported:
Note
You can use the SAP HANA XS Administration Tool to configure applications to use additional authentication methods, for example Single Sign On (SSO) providers such as SAML2, and X509. Form-based authentication Redirect the logon request to a form to fill in, for example, on a Web page.
Note
If you need to troubleshoot problems when developing a form-based logon solution for your application, 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.formlogon. Anonymous connections Use the anonymous_connection keyword to define the name of the .xssqlcc file that will be used for SQL access when no user credentials are provided. You can execute SQL statements from inside a server-side JavaScript application with credentials that are different to the credentials of the requesting user. 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. Application authorization Use the authorization keyword in the .xsaccess file to specify which authorization level is required by a user for access to a particular application package. The authorization levels you can choose from are defined in the .xsprivileges file, for example, "execute" for basic privileges, or "admin" for administrative privileges on the specified package. Cache control Use the cache_control keyword to override the cache-control header for static 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. If you set the cache_control keyword, you need to consider setting the enable_etags keyword, too. Connection security Use the force_ssl keyword in the .xsaccess file to enforce the use of secure HTTP (SSL/HTTPS) for client connections. Browser requests that do not use SSL/HTTPS are refused and the 403 Forbidden page is displayed. Note that if you set the force_ssl option, then you must ensure that the SAP Web Dispatcher is configured to accept and manage HTTPS requests. For more information about configuring the SAP Web Dispatcher to use HTTPS/SSL see the SAP HANA Security Guide.
Note
If the SAP Webdispatcher sends the header x-sap-webdisp-ap with the HTTPS port, the request is redirected to a HTTPS page, for example: http://..:80/test -> https://..:433/test. Otherwise, a 403 error is displayed.
66
Cross-origin requests Use the cors keyword to provide support for cross-origin requests. Cross-origin resource sharing (CORS) permits Web pages to make HTTP requests to another domain, where normally such requests would automatically be refused by the Web browser's security policy. If you enable support for cross-origin requests, for example, by setting the cors keyword to {"enabled" : true}, you permit requests from any origin. If no value is set, the default setting is null. Cross-Site Request Forgery (C/XSRF) You can use the prevent_xsrf keyword in the .xsaccess file to guard against cross-site request-forgery attacks. XSRF attacks attempt to trick a user into clicking a specific hyperlink, which shows a (usually wellknown) Web site and perform some actions on the users behalf, for example, in a hidden iframe. The prevent_xsrf keyword checks the validity of a session-specific security token to ensure that it matches the token that SAP HANA XS generates in the backend for the corresponding session.
Default entry (index) file Use the default_file keyword to override the default setting for the file displayed (index.html) when the package is accessed without specifying a file name in the URI. If you use the default_file but do not specify a value, the default setting is index.html assumed.
Data exposure Use the exposed keyword to specify if package content is to be exposed to client requests via HTTP.
Note
Exposed package content can include design-time objects, for example, tables and views. Entity Tags You can allow or prevent the generation of entity tags (etags) for static Web content using the enable_etags keyword in the .xsaccess file. Etags are used to improve caching performance, for example, so that the same data is not resent if no change has occurred since the last request. MIME Mapping MIME means Multipurpose Internet Mail Extensions. You can use the mime_mapping keyword in the .xsaccess file to define the way in which to map certain file suffixes to required MIME types: "mime_mapping": [ {"extension":"jpg", "mimetype":"image/jpeg"} ] URL rewrite rules Use the rewrite_rules keyword in the .xsaccess file to hide internal URL path details from external users, clients, and search engines. It is not possible to define global rewrite rules; the rules you define apply to the specified local application only. 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 the groups found can be inserted using $groupnumber.
Example
The Application-Access (.xsaccess) File The following example, shows the composition and structure of the SAP HANA XS application access (.xsaccess) file. In this file, data is available to client requests. The authentication methods specified are SAP logon ticket and then, as a fall-back option if the logon with the SAP logon ticket fails, a logon with a user name and password. Allowing a fall-back log-on mechanism is useful if the requesting client has problems handling the SAP logon ticket mechanism. { "exposed" : true, "authentication" : [ // Expose data via http
PUBLIC
67
{ },
"method": "Form"
], "authorization": // Grant package privileges [ "sap.xse.test::Execute", "sap.xse.test::Admin" ], "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" : false, // Prevent etag generation "prevent_xsrf" : true, // Prevent cross-site request forgery "anonymous_connection" : "sap.hana.sqlcon::AnonConn", //.xssqlcc object "cors" : // Permit cross-origin browser requests [ { "enabled" : true } ], "default_file" : index_1.html, // Override default access setting "cache_control" : "", // Manage static Web content cache
Related Information http://help.sap.com/hana/SAP_HANA_Security_Guide_en.pdf Application-Access File Keyword Options [page 68] 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. Maintaining Application Security [page 82] 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.
3.5.4
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 The following example shows all possible keyword combinations in the SAP HANA XS application-access (.xsaccess) file.
68
Note
In the form shown below, the .xsaccess file is not a working model; it is used to illustrate the syntax for all possible options. {
"exposed" : false, "authentication" : [ { "method": "Form" }, ], "authorization": [ "sap.xse.test::Execute", "sap.xse.test::Admin" ], "anonymous_connection" : "sap.hana.sqlcon::AnonConn", "cache_control" : "no-store", "cors" : { "enabled" : true }, "default_file" : index_1.html, "enable_etags" : false, "force_ssl" : true, "mime_mapping" : [ { "extension":"jpg", "mimetype":"image/jpeg" } ], "prevent_xsrf" : false, "rewrite_rules" : [{ "source" : "...", "target" : "..." }],
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.
PUBLIC
69
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.
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 formbased 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. 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 displayed, ask the SAP HANA administrator to add it. application_list . If it is not
70
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.formlogon.
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 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.
cache_control
{ }
"cache_control":"no-store",
The cache_control keyword enables you to override the cache-control header for static 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. If no value is set, the default setting is null.
cors
{
"cors" :
PUBLIC
71
{ }
"enabled" : true },
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 to make HTTP requests to another domain, where normally such requests would automatically be refused by the Web browser's security policy. If you enable support for CORS, for example, by setting the cors keyword to {enabled:true}, you allow requests from any origin. If no value is set, the default setting is null.
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 is index.html assumed.
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.
mime_mapping
{
"mime_mapping" : [ { "extension":"jpg", "mimetype":"image/jpeg"
72
PUBLIC
],
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 .
force_ssl
{ }
"force_ssl" : false,
The force_ssl keyword enables you to refuse Browser requests that do not use secure HTTP (SSL/HTTPS) for client connections. If no value is set for exposed, the default setting (false) applies and non-secured connections (HTTP) are allowed.
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.
prevent_xsrf
{ }
"prevent_xsrf" : true,
You can use the prevent_xsrf keyword in the .xsaccess file to protect applications from cross-site requestforgery (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 users 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. 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.
PUBLIC
73
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. 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); Related Information Server-Side JavaScript Security Considerations [page 320] 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 SQL Connection Configuration File [page 342] In SAP HANA Extended Application Services (SAP HANA XS), you use the SQL-connection configuration file to enable the execution of SQL statements from inside your server-side JavaScript application with credentials that are different to the credentials of the requesting user.
3.5.5
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
74
| |---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": "target": }, { "source": "target": } ] [ "/users/(\\d+)/", "/logic/users.xsjs?id=$1" "/posts/(\\d+)/(\\d+)/(\\d+)/", "/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/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.5.6 Enabling Access to SAP HANA XS Application Packages

The application-access 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.
Context
You can use a set of keywords in the application-access file .xsaccess 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.
PUBLIC
75
Procedure
1. If it does not already exist, create a root package for the application you want to enable access to, for example, MyPackage.
Note
The namespace sap is restricted. Place the new package in your own namespace, which you can create alongside the sap namespace. a) Start the SAP HANA studio and open the SAP HANA Development perspective. b) In the Project Explorer view, right-click the folder where you want to create the new (MyPackage) package. c) In the context-sensitive popup menu, choose d) Enter the name MyPackage and choose Finish. 2. Activate the new package in the repository. a) In the SAP HANA Development perspective, open the Project Explorer view and right-click the new (MyPackage) package. b) In the context-sensitive popup menu, choose 3. Team Activate . New Folder .
If it does not already exist, create an application descriptor for the application and place it in the package (MyPackage) you created in the previous step. The application descriptor is the core file that you use to indicate an application's availability within SAP HANA XS. The application descriptor marks the point in the package hierarchy at which an application's content is available to clients.
Note
The application-descriptor file has no contents and no name; it only has the file extension .xsapp. a) In the SAP HANA studio and open the SAP HANA Development perspective. b) In the Project Explorer view, right-click the folder where you want to create the new (.xsapp) file. c) In the context-sensitive popup menu, choose d) Enter the name .xsapp and choose Finish. Files with names that begin with the period (.), for example, .xsapp, are sometimes not visible in the Project Explorer. To enable the display of all files in the Project Explorer view, use the Available Customization 4. option and clear all check boxes. e) Activate the new .xsapp file in the repository. Create the application access file. The application-access file is a JSON-compliant file with the file suffix .xsaccess. Note that the applicationaccess file does not have a name before the dot (.); it only has the suffix .xsaccess. Create a file called .xsaccess and place it in the root package of the application to which you want to enable access. 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. a) In the SAP HANA studio and open the SAP HANA Development perspective. Customize View New File .
76
b) In the Project Explorer view, right-click the folder where you want to create the new (.xsaccess) file. c) In the context-sensitive popup menu, choose d) Enter the name .xsaccess and choose Finish. 5. Enable application access to data. You use the expose keyword to enable or disable access to content at a package or subpackage level. { } 6. "exposed" : true New File .
Define the application authentication method. You use the authentication keyword to define how to manage the authentication process for requests to access package content, for example, SAP logon ticket, form-based logon, or a basic user name and password . { "authentication" : [ { "method" : "Basic" } ]
} 7.
Specify the application privileges if required. (Optional) Use the authorization keyword in the .xsaccess file to specify which authorization level is required by a user for access to 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": ["sap.xse.test::Execute", "sap.xse.test::Admin" ] }
8. 9.
Save the .xsaccess file in the package with which you want to associate the rules you have defined. Commit the .xsaccess file to the repository and activate it. In the Project Explorer view, right click the object you want to activate and choose popup menu. Team > Activate in the
Related Information Application-Access File Keyword Options [page 68] 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. The Application-Privileges File [page 78] 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.
PUBLIC
77
3.5.7
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 must use the GRANT_APPLICATION_PRIVILEGE or REVOKE_APPLICATION_PRIVILEGE procedure in the _SYS_REPO schema.
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" } ] }
78
PUBLIC
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.8
Creating an SAP HANA XS Application Privileges File
The application-privileges (.xsprivileges) file enables you to define the authorization levels required for access to 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.
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 .xsaccess file, for example, using the authorization keyword.
Procedure
1. If you have not already done so, create a root package for your new application, for example, MyPackage. a) In the SAP HANA studio, open the SAP HANA Development perspective. b) In the Project Explorer view, right-click the folder where you want to create the new (MyPackage) package. c) In the context-sensitive popup menu, choose d) Enter the name MyPackage and choose Finish. 2. If you have not already done so, create an application descriptor for your new application and place it in the root package (MyPackage) you created in the previous step. The application descriptor is the core file that you use to indicate an application's availability within SAP HANA XS. The application descriptor marks the point in the package hierarchy at which an application's content is available to clients. New Folder .
Note
The application-descriptor file has no contents and no name; it only has the file extension .xsapp. 3. If you have not already done so, create an application-access file for your new application and place it in the package to which you want to grant access.
PUBLIC
79
The application-access file does not have a name; it only has the file extension .xsaccess. a) In the SAP HANA studio, open the SAP HANA Development perspective. b) In the Project Explorer view, right-click the folder where you want to create the new (.xsaccess) file. c) In the context-sensitive popup menu, choose d) Enter the name .xsaccess and choose Finish. e) Specify the privileges required for access to the application or application package. Use the authorization keyword in the .xsaccess file to specify which authorization level is required by a user for access to a particular application package. New File .
Note
If you enable the authorization keyword in the .xsaccess file, you must add a corresponding entry to the .xsprivileges file, too. {
} 4.
"exposed" : true "authentication" : [ { "method" : "Basic" } ] "authorization": [ "com.acme.myApp::Execute", "com.acme.myApp::Admin" ]
Create the application-privileges (.xsprivileges) file and place it in the application package whose access privileges you want to define. 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.
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. a) In the SAP HANA studio and open the SAP HANA Development perspective. b) In the Project Explorer view, right-click the folder where you want to create the new (.xsprivileges) file. c) In the context-sensitive popup menu, choose e) Activate the new (.xsprivileges) file 5. 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, New File . d) Enter the name .xsprivileges and choose Finish.
80
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.
Note
The .xsprivileges file lists the authorization levels defined for an application package. A corresponding entry is required in the same application's access file .xsaccess file to define which authorization level is assigned to which application package. {
"privileges" : [ { "name" : "Execute", "description" : "Basic execution privilege" }, { "name" : "Admin", "description" : "Administration privilege" } ] }
6.
Save and activate your changes and additions. The activation of the application privileges creates the corresponding objects, which you can use to assign the specified privileges to an author. 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 them 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, run the following command in the SAP HANA studio's SQL Console: call "_SYS_REPO"."GRANT_APPLICATION_PRIVILEGE"('"com.acme.myApp::Execute"','<UserName> ') To revoke the execute application privilege to a user, run the following command in the SAP HANA studio's SQL Console: call "_SYS_REPO"."REVOKE_APPLICATION_PRIVILEGE"('"com.acme.myApp::Execute"','<UserName >')
7.
Related Information Creating an Application Descriptor File [page 64] 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. Enabling Access to SAP HANA XS Application Packages [page 75] The application-access 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.
PUBLIC
81
3.6
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.
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. 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.
82
PUBLIC
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. 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.
b) Use the Force SSL option to specify if client requests must use secure HTTP (HTTPS).
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 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
PUBLIC
83
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 SAP HANA XS Application Security [page 84] You can set some basic security options to increase the security of the applications you develop for SAP HANA. SAP HANA XS Application Authentication [page 86] The authentication method determines whether or not authentication is required to access an application, and if required, which authentication methods must be used. The Application-Access File [page 65] SAP HANA XS enables you to define access to each individual application package that you want to develop and deploy. http://help.sap.com/hana/SAP_HANA_Security_Guide_en.pdf
3.6.1
SAP HANA XS Application Security
You can set some basic security options to increase the security of the applications you develop for SAP HANA. SAP HANA Extended Application Services (SAP HANA XS) provides a dedicated tool that is designed to help you configure and maintain some of the basic aspects of security relating to the applications you develop. For example, you can specify if the applications you develop are publicly available for anyone to start, or if the applications can only be started by an authenticated user.
84
You can set the following security-related options for the application you develop for SAP HANA XS: Public (no authentication required) Use the Public option to specify if applications require user authentication to start. By default, the Public option in the application Security screen area is disabled and the Form-based authentication and Basic authentication options are enabled automatically in the Authentication screen area. However, you can disable both form-based and basic authentication and enable other, additional authentication methods (for example, SAP logon tickets or X509 authentication).
Note
If you enable the Public option in the application Security screen area, no authentication is required to start an application; the Authentication screen area is hidden, and you cannot select any authentication-method options. Force SSL The force_ssl option enables you to ensure that only Browser requests that use secure HTTP (SSL/HTTPS) for client connections are accepted; any request using basic (and insecure) HTTP is refused. If no value is set for exposed, the default setting (false) applies and non-secured connections (HTTP) are allowed.
Related Information SAP HANA XS Application Authentication [page 86] The authentication method determines whether or not authentication is required to access an application, and if required, which authentication methods must be used. The Application-Access File [page 65] SAP HANA XS enables you to define access to each individual application package that you want to develop and deploy.
PUBLIC
85
3.6.2
SAP HANA XS Application Authentication
The authentication method determines whether or not authentication is required to access an application, and if required, which authentication methods must be used. SAP HANA Extended Application Services (SAP HANA XS) provides a dedicated tool that is designed to help you configure and maintain the authentication mechanism used to control access to the applications you develop. The authentication method you select for access to your application depends on which application methods are supported by SAP HANA and whether or not your system administrator has configured the authentication method.
You can configure applications running in SAP HANA XS to use the following authentication mechanisms: SAML2 Choose this option if you have configured SAML2 assertions to enable SSO in Web browsers. SAML2 is version 2 of the Security Assertion Markup Language (SAML), which enables Web-based authentication including single sign-on across domains.
Note
The user who connects to the database using an external authentication provider must also have a database user known to the database. SAP HANA maps the external identity to the identity of the internal database user. X509 Authentication X.509 client certificates For secure HTTP (HTTPS) access to SAP HANA XS applications, users can be authenticated by client certificates signed by a trusted Certification Authority (CA), which can be stored in the SAP HANA XS trust store.
86
SAP logon ticket For HTTPS access to SAP HANA XS applications, a user can 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). To configure the trust relationship between the issuer of the SAP logon ticket and SAP HANA, you must specify the path to the SAP logon ticket trust store, which contains the trust chain for the ticket issuer. You can use the SapLogonTicketTrustStore keyword in the xsengine.ini file. Default values are: $SECUDIR/ saplogon.pse or $HOME/.ssl/saplogon.pem.
Note
SAP HANA XS does not issue SAP logon tickets; it only accepts them. Since the tickets usually reside in a cookie, the issuer and SAP HANA XS need to be in the same domain to make sure that your browser sends the SAP logon ticket cookie with each call to SAP HANA XS. Form-based authentication This option is used if interactive logon is desired. With form-based authentication, the logon request is redirected to a form to fill in, for example, displayed in Web page. The Form-based authentication option is enabled by default if the Public option is disabled in the application Security screen area.
Note
You must also enable the Form-based authentication in the .xsaccess file, if you want your application (or applications) to use form-based logon as the authentication method. Note that any other keywords in the authentication section of the .xsacess file are ignored. 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 displayed, ask the SAP HANA administrator to add it. application_list . If it is not
Tip
If you need to troubleshoot problems with form-based authentication, 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.formlogon. Basic authentication Logon with a recognized database user name and password. This option is used if non-interactive logon is desired. The Basic authentication option is enabled by default if the Public option is disabled in the application Security screen area.
The authentication configuration enables you to define the authentication methods to use for Browser requests either at the application level or for single packages in an application.
Note
The authentication mechanism set at the root of the application/package hierarchy is inherited by applications further down the application hierarchy. By default, the Public option in the application Security screen area is disabled and the Form-based authentication and Basic authentication options are enabled automatically in the Authentication screen area. However, you can
PUBLIC
87
disable both form-based and basic authentication and enable other, additional authentication methods (for example, SAP logon tickets or X509 authentication). If multiple authentication methods are enabled, SAP HANA XS enforces the following order of priority: For non-interactive logon: 1. 2. 3. 1. 2. X509 authentication SAP logon ticket Basic authentication SAML Form-based authentication
For interactive logon:
If you enable the Public option in the application Security screen area, no authentication is required to start an application; the Authentication screen area is hidden, and you cannot select any authentication-method options. Related Information The Application-Access File [page 65] SAP HANA XS enables you to define access to each individual application package that you want to develop and deploy. Application-Access File Keyword Options [page 68] 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.
3.7
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.
88
PUBLIC
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. 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 configurationfile 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/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.
3.7.1
The HTTP Destination Configuration
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. You use the HTTP destination file to define not only the details of the host you want an application to reach by means of HTTP but also any further details that are necessary to establish the connection, for example, any proxy settings. If necessary, the proxy settings can also be defined in a separate, so-called "extension file". Both the configuration file you use to define an HTTP destination and the file used to specify any extensions to the HTTP destination are text files that must have the suffix .xshttpdest, for example, myHTTPdestination.xshttpdest or myHTTPdestExtension.xshttpdest.
Note
For security reasons, the HTTP destination configuration and the XSJS application that uses it must be in the same application package or one of the application's subpackages. An application cannot reference an HTTP destination configuration that is located in a different application. You configure an HTTP destination in a text file that contains the details of the connection to the HTTP destination, using a mandatory syntax comprising a list of keyword=value pairs, for example, host = "download.finance.yahoo.com";. After creating and saving the HTTP destination, you must commit it to the SAP HANA repository and activate it. The following configuration file for the HTTP destination yahoo.xshttpdest illustrates how to define an HTTP destination that can be used to access a financial service running on an external host. host = "download.finance.yahoo.com"; port = 80; description = "my stock-price checker";
PUBLIC
89
useSSL = false; pathPrefix = "/d/quotes.csv?f=a"; authType = none; useProxy = false; proxyHost = ""; proxyPort = 0; timeout = 0; After activating the configuration in the SAP HANA repository, you can view the details of the new HTTP destination 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
90
Related Information HTTP Destination Configuration Syntax [page 92] 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. Tutorial: Create an HTTP Destination [page 96] Create an HTTP destination defining connection details for services running on specific hosts. The definition can be referenced by an application.
3.7.2
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 commit it to the SAP HANA repository and activate it.
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; useProxy = true; proxyHost = "proxy.mycompany.com"; proxyPort = 8080; 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:
PUBLIC
91
HTTPDestViewer HTTPDestAdministrator
3.7.3
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.
92
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. 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 = "download.finance.yahoo.com"; port = 80; //All the following keywords are optional description = ""; useSSL = false; pathPrefix = "/d/quotes.csv?f=a"; authType = none; useProxy = false; proxyHost = ""; //in-line comments are allowed proxyPort = 0; timeout = 0;
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.
PUBLIC
93
description =
description = "my short description of the HTTP connection"; 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.
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]"; The optional keyword authType enables you to specify the authentication method that must be used for connections to the service located at the HTTP destination specified in the configuration, for example, basic (user name and password). Permitted values are "none" and "basic".
Note
Optional default =
94
PUBLIC
useProxy =
useProxy = false; The optional keyword useProxy enables you to specify if a proxy server must be used to resolve the host name specified in the HTTP destination configuration file.
Note
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 useProxy = false in the original HTTP destination configuration. In the HTTP destination extension that references and modifies the original HTTP destination, you can modify the proxy setting to useProxy = true. 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"
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 how long an application must wait before terminating any attempt to connect to the remote host specified in the HTTP destination configuration. By default, the timeout interval is set to -1, which means there is no timeout defined in the HTTP destination configuration. The
PUBLIC
95
connection to the host specified in the HTTP destination configuration is is closed either by the host (where a timeout is set), or because a problem occurs during the connection session.
modifies
modifies pkg.path.testApp:yahoo.xshttpdest; The keyword modifies enables you to reference an existing HTTP destination (or extension) whose settings you want to 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.
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 HTTP Destination Syntax Error Messages The HTTP Destination Configuration [page 89] 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. The HTTP Destination Extension [page 91] 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.
3.7.4
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
Since the artifacts required to create a simple HTTP destination are stored in the repository, it is assumed that you have already performed the following tasks: Create a development workspace in the SAP HANA repository Create a project in the workspace Share the new project The HTTPDestViewer SAP HANA user role
96
Context
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. 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.
Note
HTTP destinations configurations are defined in a text file; you can use the editing tools provided with SAP HANA studio or your favorite text editor.
Procedure
1. Create a package for the SAP HANA XS application that will use the HTTP destination you define in this tutorial. For example, create a package called testApp. Make sure you can write to the schema where you create the new application. a) Start the SAP HANA studio and open the SAP HANA Development perspective. b) In the SAP HANA Systems view, right-click the node in the package hierarchy where you want to create the new package and, in the pop-up menu that displays, choose Packages... c) In the New Package dialog that displays, enter the details of the new package (testApp) that you want to add and click OK. 2. 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) Create a plain-text file called yahoo.xshttpdest and open it in a text editor. b) 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; useProxy = false; proxyHost = ""; proxyPort = 0; timeout = 0; c) Save, commit, and activate the file.
PUBLIC
97
3.
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. a) Open a Web browser. b) Start the SAP HANA XS Administration Tool. The SAP HANA XS Administration Tool tool is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/admin/.
Note
98
c) In the XS Applications tab, expand the nodes in the application tree to locate the application testApp. d) Choose yahoo.xshttpdest to display details of the HTTP destination . Related Information Tutorial: Extend an HTTP Destination [page 100] Extend an HTTP destination defining connection details for services running on specific hosts, for example, by providing additional details. The definition and the extension details can be referenced by an application. The HTTP Destination Configuration [page 89] 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. HTTP Destination Configuration Syntax [page 92] 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. HTTP Destination Syntax Error Messages
PUBLIC
99
3.7.5
Tutorial: Extend an HTTP Destination
Extend an HTTP destination defining connection details for services running on specific hosts, for example, by providing additional details. The definition and the extension details can be referenced by an application.
Prerequisites
Since the artifacts required to create an HTTP destination extension are stored in the repository, it is assumed that you have already performed the following tasks: Create a development workspace in the SAP HANA repository Create a project in the workspace Share the new project The HTTPDestViewer SAP HANA user role
Note
This tutorial shows you how to modify an HTTP destination by providing details of a proxy server that must be used to resolve host names specified in the connection details; you must supply the name of a working proxy server that is available in your environment.
Context
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. 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.
Note
HTTP destinations configurations and any extensions are defined in a plain-text file; you can use the editing tools provided with SAP HANA studio or your favorite text editor to add entries to the configuration file.
Procedure
1. Create a package for the SAP HANA XS application that will use the HTTP destination (and extension) you define in this tutorial. For example, create a package called testApp. Make sure you can write to the schema where you create the new application. a) Start the SAP HANA studio and open the SAP HANA Development perspective. b) In the SAP HANA Systems view, right-click the node in the package hierarchy where you want to create the new package and, in the pop-up menu that displays, choose Packages...
100
c) In the New Package dialog that displays, enter the details of the new package (testApp) that you want to add and click OK. 2. Define the details of the new 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 in the application package that uses it. An application cannot reference an HTTP destination configuration that is located in another application package. a) Create a plain-text file called yahoo.xshttpdest and open it in a text editor. b) 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; useProxy = false; proxyHost = ""; proxyPort = 0; timeout = 0; c) Save, commit, and activate the file. 3. View the activated HTTP destination. You can use the SAP HANA XS Administration Tool to check the contents of an HTTP destination configuration.
Note
Note
PUBLIC
101
c) In the XS Applications tab, expand the nodes in the application tree to locate the application testApp. d) Choose yahoo.xshttpdest to display details of the HTTP destination . 4. Define the details of the extension to the HTTP destination you created in the previous steps. Like the HTTP destination itself, you define an extension to 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 suffix .xshttpdest.
Caution
You must place the HTTP destination configuration (and any extensions to the configuration) in the application package that uses them. An application cannot reference an HTTP destination configuration (or an extension) that is located in another application package. a) Create a plain-text file called yahooProxy.xshttpdest and open it in a text editor. b) Enter the following code in the new file yahooProxy.xshttpdest. modifies testApp:yahoo.xshttpdest; useProxy = true;
102
PUBLIC
proxyHost = "proxy.mycompany.com"; proxyPort = 8080; c) Save, commit, and activate the file. 5. View and check the details of the activated HTTP destination extension yahooProxy.xshttpdest. You can use the SAP HANA XS Administration Tool to check the contents of an HTTP destination configuration or an extension to the configuration.
Note
To make changes to the HTTP Destination configuration (or any extension), you must use a text editor, save the changes and reactivate the file. a) Open a Web browser. b) Start the SAP HANA XS Administration Tool. The SAP HANA XS Administration Tool 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.
PUBLIC
103
c) In the XS Applications tab, expand the nodes in the application tree to locate the application testApp. d) Choose yahooProxy.xshttpdest to display details of the HTTP destination extension. Related Information Tutorial: Create an HTTP Destination [page 96] Create an HTTP destination defining connection details for services running on specific hosts. The definition can be referenced by an application. The HTTP Destination Configuration [page 89] 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. HTTP Destination Configuration Syntax [page 92] 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. HTTP Destination Syntax Error Messages
104
3.8
Design-Time Application Artifacts
The design-time building blocks of your SAP HANA applications are called development objects (or artifacts), and many have a mandatory file extension, for example, .hdbtable (design-time table definition) or .hdbview (design-time SQL-view definition). Some of these development objects, such as projects and packages, are concepts that help you structure your application. Others, like schemas, table definitions, or analytical and attribute views, help you organize your data. Procedures and server-side JavaScript code are the core objects of an SAP HANA application. Other types of development objects help you control the access to runtime objects. The following tables list the 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. Table 5: Design-time Application Building Blocks File Extension .analyticview Object Analytic view Description More Information
A file containing a design-time definition of Data Access with OData in an analytic view, which can be referenced in SAP HANA XS [page 274] an OData service definition. A file containing a design-time definition of an attribute view, which can be referenced in an OData service definition.
.attributeview
Attribute view
.calculationvi ew .hdbdd
Calculation view A file containing a design-time definition of an calculation view, which can be referenced in an OData service definition. CDS document A file containing a design-time definition of Data Persistence Objects in a CDS-compliant data-persistence object Core Data Services (CDS) (for example, an entity or a data type) using [page 154] the Data Definition Language (DDL). A file containing a design-time definition of an SAP HANA user role. A design-time definition of a database schema, which organizes database objects into groups. A design-time definition of a database sequence, which is set of unique numbers, for example, for use as primary keys for a specific table. 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. Creating Roles in the Repository [page 534] Schema [page 125]
.hdbrole .hdbschema
Role Schema
.hdbsequence
Sequence
Sequences [page 140]
.hdbstructure
Table type
Creating Reusable Table Structures [page 135]Defining Local Table Types in Procedures [page 257]
PUBLIC
105
File Extension .hdbtable
Object Table Resource Bundle Table Import definition SQL View
Description A design-time definition of a database table using the .hdbtable syntax.
More Information Tables [page 128]
.hdbtextbundle .hdbti
A file for defining translatable UI texts for an Creating an SAPUI5 application. Used in SAP UI5 applications. Application A table-import configuration that specifies which .csv file is imported into which table in the SAP HANA system A design-time definition of a database view, which is a virtual table based on an SQL query. A design-time definition of a database function for performing complex and dataintensive business logic that cannot be performed with standard SQL. A design-time artifact containing a base script with predefined placeholders for objects such as tables, views and columns. 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. Data Provisioning Using Table Import [page 144] SQL Views [page 142]
.hdbview
.procedure
Procedure
Developing Procedures [page 254]
.proceduretemp late .project
Procedure template Project
Creating Procedure Templates [page 258] SAP HANA Studio Projects [page 50]
.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. Application Access File An application-specific configuration file that defines permissions for a native SAP HANA application, for example, to manage access to the application and running objects in the package. 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.
Search Rules [page 490]
.xsaccess
Enabling Access to SAP HANA XS Application Packages [page 75]
.xsapp
Application Descriptor
Creating the Application Descriptors [page 62]
.xsappsite .xshttpdest
Application Site A file that defines an application site. HTTP destination configuration Server-Side JavaScript Code A file that defines details for connections to a remote destination by HTTP (or HTTPS) A file containing JavaScript code that can run in SAP HANA Extended Application Services and that can be accessed via URL.
Creating an Application Site [page 378] Maintaining HTTP Destinations [page 88] Tutorial: Writing ServerSide JavaScript Application Code [page 331]
.xsjs
106
File Extension .xsjslib
Object Server-Side JavaScript Library
Description A file containing JavaScript code that can run in SAP HANA Extended Application Services but cannot be accessed via URL. The code can be imported into an .xsjs code file.
More Information Tutorial: Writing ServerSide JavaScript Application Code [page 331]
.xsodata
OData Descriptor Application Privilege
A design-time object that defines an OData Data Access with OData in service that exposes SAP HANA data from a SAP HANA XS [page 274] specified end point. A file that defines a privilege that can be The Application-Privileges assigned to an SAP HANA Extended File [page 78] Application Services application, for example, the right to start or administer the application. The SQL Connection Configuration File [page 342] Creating a Widget [page 384] Data Access with XMLA in SAP HANA XS [page 305]
.xsprivileges
.xssqlcc
SQL Connection A file that enables execution of SQL Configuration statements from inside server-side JavaScript code with credentials that are different to those of the requesting user. Widget A file that defines a standalone SAP HANA application for the purpose of integration into an application site. . A design time object that defines an XMLA service that exposes SAP HANA data.
.xswidget
.xsxmla
XMLA Descriptor
Table 6: Additional Application Building Blocks Object Package Description A container in the repository for development objects. A view created with modeling tools and designed to model a business use case. File Extension Packages are represented by folders. Created with the SAP HANA Systems view. More Information Maintaining Repository Packages [page 55] Setting Up the Analytic Model [page 176]
Attribute, Analytic and Calculation View Decision Table
A table used to model business rules, for example, to manage data validation and quality. A set of rules that allows users to seeing a subset of data in a table or view.
Creating Decision Tables [page 242] Creating Analytic Privileges [page 554]
Analytic Privilege
PUBLIC
107
3.9
Developing Applications in Web-based Environments
Web-based development environments provide application developers with tools that enable access to repository objects from a remote location, for example, using a Web browser. As a developer, you need to access your SAP HANA repository and perform simple development tasks. However, often you either cannot install and use SAP HANA studio locally, or you need to develop from a remote location. To enable quick and easy development of repository objects from a remote location, SAP HANA supports Webbrowser-based integrated development environments (IDE). SAP HANA Extended Application Services (SAP HANA XS) provides the following Web-browser-based IDEs that you can use to create, delete, and rename development artifacts in the SAP HANA repository: SAP HANA IDE lite SAP HANA Web-based Development Workbench
Both Web-browser-based IDEs include a code editor that provides basic development features, such as syntax highlights, code folding, and client- or server-side checks. In addition, when you save a repository object in either of the Web-browser-based IDEs, the saved object is automatically committed to the SAP HANA repository and activated.
Note
In the Web-browser-based IDEs, you can only perform file-based operations; modeling activities are not possible. Before you start using one of the SAP HANA Web-browser-based IDEs, the SAP HANA administrator must set up a user account for you in the database and assign the required developer roles. For example, to enable you to use the debugging features of the browser-based IDEs, your administrator must assign you the role (sap.hana.xs.debugger::Debugger and, in addition, add the section debugger with the parameter enabled and the value true in the file xsengine.ini.
3.9.1
SAP HANA IDE lite
SAP HANA IDE lite is a browser-based integrated development environment (IDE) for SAP HANA Extended Services (SAP HANA XS). SAP HANA IDE lite is intended as a quick and easy alternative to using SAP HANA studio for developing native applications for SAP HANA XS. SAP HANA IDE lite provides an intuitive user interface and simplifies development by providing many convenient functions. For example, SAP HANA IDE lite includes a wizard for creating applications and automatically generates the application-descriptors that are required for an SAP HANA application (the .xsapp and .xsaccess files).
Note
SAP HANA IDE lite is available on the SAP HANA XS Web server at the following URL: http:// <WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/editor
108
PUBLIC
In addition to the basic functions of creating, editing, and executing repository objects, SAP HANA IDE lite provides application developers with the additional features, for example: Multi-file drop zone You can upload multiple files at once to a repository package. Multiple editors You can open multiple editor tabs or you can open an editor as its own browser tab. Templates You can use templates for standard SAP HANA XS applications such as mobile and UI5 applications. You can also use code snippet templates for individual files, such as for .hdbtable files or .hdbschema files. Direct testing You can test html pages and XSJS services directly from the editor in the browser. SAP HANA IDE lite also include special mobile device emulation modes for testing. Debugger You can use the integrated debugging features to debug your application.
Note
SAP HANA IDE lite supports all newer versions of major browsers, such as Internet Explorer, Mozilla Firefox and Google Chrome. However, the embedded debugging features support only Mozilla Firefox or Google Chrome Web-browsers. For more information about the features of SAP HANA IDE lite, use the URL http://<WebServerHost>: 80<SAPHANAinstance>/sap/hana/xs/editor/info.html, or choose lite tool bar. (information) in the SAP HANA IDE
3.9.1.1 Tutorial: Creating a Simple SAPUI5 Application with SAP HANA IDE lite
The SAPUI5 application you create in this tutorial displays a button in a browser window which fades out when you choose it.
Prerequisites
You have access to a running SAP HANA system You have a valid user account in the SAP HANA database on that system
Procedure
1. Open the SAP HANA IDE lite. SAP HANA IDE lite is available on the SAP HANA XS Web server at the following URL: http:// <WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/editor
PUBLIC
109
Note
SAP HANA user credentials are required to log on. 2. From the context menu of the Content folder, choose Create Application. Create the application in a package that does not already contain application descriptors, for example, the .xsaccess and .xsapp files. 3. 4. 5. 6. 7. Choose the Hello World - SAP UI5 Hello World template. 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. From the menu, choose Run Run . A browser window opens that displays a button. Choose the button. The button fades out.
3.9.1.2 Tutorial: Creating a Simple Mobile Application with SAP HANA IDE lite
The application you develop in this tutorial displays a simple mobile user interface (UI) with sliding navigation. You also learn how to add files to your packages by dragging them into SAP HANA IDE lite.
Prerequisites
You have access to a running SAP HANA system You have a valid user account in the SAP HANA database on that system
Procedure
1. Open the SAP HANA IDE lite. SAP HANA IDE lite is available on the SAP HANA XS Web server at the following URL: http:// <WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/editor
Note
SAP HANA user credentials are required to log on. 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, the .xsaccess and .xsapp files.
110
PUBLIC
3. 4.
Choose the Simple Mobile Application template. Enter a package name, for example, demo.mobile and choose Create. The system creates the index.html, .xsaccess, and .xsapp files for a mobile application, and automatically opens the index.html file.
5. 6. 7. 8.
To create an images subpackage, from the context menu of the mobile package, choose Create Package and enter a package name, for example, images. Open the images package. The system displays the Multi-File Drop Zone to insert several files at a time. From the file system, drag the image files into the Multi-File Drop Zone. The system adds the files to the images folder. Test the mobile application as follows: For mobile devices running the iOS operating system, choose Run Simulate SAPUI5 iOS . Run Simulate SAPUI5 Android .
For mobile devices running the Android operating system, choose
A browser window opens, displaying the required URL parameters and a button. 9. Choose the button. The screen slides to open another view.
3.9.1.3 Tutorial: Creating and Debugging a Server-side JavaScript Application with SAP HANA IDE lite
In this tutorial the server-side JavaScript application you create and debug 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 access to a running SAP HANA system You have a valid user account in the SAP HANA database on that system Your administrator has assigned you the user role sap.hana.xs.debugger::Debugger Your SAP HANA administrator has enabled debugging on the SAP HANA system To use the embedded debugging functionality, you must run SAP HANA IDE lite in either a Mozilla Firefox or a Google Chrome browser.
Procedure
1. Open SAP HANA IDE lite. SAP HANA IDE lite is available on the SAP HANA XS Web server at the following URL: http:// <WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/editor
PUBLIC
111
Note
SAP HANA user credentials are required to log on. 2. From the context menu of the Content folder, choose Create Application. Create the application in a package that does not already and application descriptors, for example, the .xsaccess and .xsapp files. 3. 4. Choose the Blank Application - (.xsapp and .xsaccess) template. 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 folder, choose Create File. c) Rename the new file using the .xsjs extension. d) Enter the following server-side JavaScript code into the file: $.response.contentType = "application/json"; $.response.status = 200; $.response.contentType = "text/plain"; var variable1 = $.request.parameters.get("var1"); var variable2 = $.request.parameters.get("var2"); try { 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()); } function doMultiply(var1, var2){ return var1+" X "+var2+" = "+var1*var2; } function doAdd(var1, var2){ return var1+" + "+var2+" = "+(parseInt(var1)+parseInt(var2)); } 6. 7. From the menu, choose A window opens. Run Run .
Edit the URL parameters as follows and press Enter : For multiply, enter <your_file_name>.xsjs?mode=multiply&var1=10&var2=200. For addition, enter <your_file_name>.xsjs?mode=add&var1=10&var2=200.
The system computes the results and displays it in the browser window. 8. To debug a function, enter a break point in front of the line number and choose Run.
112
During program execution, the debugger pane opens as soon as a break point is encountered.
3.9.2
SAP HANA Web-based Development Workbench
SAP HANA Web-based Development Workbench is a browser-based integrated development environment (IDE) for SAP HANA Extended Application Services (SAP HANA XS). The SAP HANA Web-based Development Workbench is intended as a quick and easy alternative to using SAP HANA studio for developing native applications for SAP HANA XS. In addition to the basic functions of creating, editing, and executing repository objects, SAP HANA Web-based Development Workbench provides application developers with the following features: Text editor (based on ACE) The text editor provides standard features such as copy, undo, search, and replace. You can also highlight syntax and check for various file types, such as JavaScript. SQL editor You can use the SQL editor to execute arbitrary SQL statements and display the results of select statements in a table. Image viewer You can view images directly in the browser. Debugger The embedded debugger is a JavaScript debugger that runs in the browser session and uses WebSockets (extended Crossfire Protocol with SAP HANA Server). With the embedded debugger, you can also view and edit global, closure, and local variables in different stacks.
Note
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/xs/ide. SAP HANA Webbased Development Workbench supports only Mozilla Firefox and Google Chrome Web browsers. The default interface provided by SAP HANA Web-based Development Workbench comprises the following views: View Repository Projects Catalog Security Open Files Trace Files Inactive Objects Description Shows all entities in the repository as folders and files with attributes in a tree Shows all XS projects of the system as root nodes Enables you to browse schemas, tables, and views Enables you to view and create users and assign roles Shows a list of open files in the IDE and their status, enabling quick navigation Shows a list of all backend trace files Shows a list of objects that are committed but not activated. These objects are inactive either due to errors in backend activation or they were manually
PUBLIC
113
View
Description committed without activation. You can revert (delete inactive files) or activate the files.
Delivery Unit
Shows all delivery units and their properties in the system
Related Information XSJS-Debugging Security Considerations [page 355] User authentication and a dedicated debugging role are just two aspects of security to be considered by anyone who wants to debug server-side JavaScript on SAP HANA Extended Application Services(SAP HANA XS).
3.9.2.1 Tutorial: My First Project in SAP HANA Web-based Development Workbench

This tutorial shows you how to use the SAP HANA Web-based Development Workbench to develop a functional SAP HANA application. Although it is simple, the tutorial demonstrates the development process that you can apply to all types of application-development scenarios.
Prerequisites
You have access to a running SAP HANA system You have a valid user account in the SAP HANA database on that system Your administrator has assigned you the user role sap.hana.xs.debugger::Debugger Your SAP HANA administrator has enabled debugging on the SAP HANA system You run SAP HANA Web-based Development Workbench in either a Mozilla Firefox or a Google Chrome browser.
Context
As part of the process of setting up and developing a simple application project using the SAP HANA Web-based Development Workbench you perform the following high-level steps:
Procedure
1. 2. 3. Create a project, run the project, and view the trace. Create a table, insert data, and view data. Debug server-side JavaScript with the embedded debugging tools.
114
4. 5.
Import an image from your local file system. Create and assign a delivery unit and export the delivery unit to another system.
Related Information Tutorial: Creating a Project and Viewing the Trace [page 115] In this tutorial, you use the SAP HANA Web-based Development Workbench to create a hello world project, set a trace level, run the project, and view the trace. Tutorial: Creating a Table [page 116] In this tutorial, you use the SAP HANA Web-based Development Workbench to create a table, insert data into the table, and view the data with the embedded SQL editor. Tutorial: Debugging Server-side Javascript [page 117] In this tutorial, you use the embedded debugging tools provided by SAP HANA Web-based Development Workbench to debug server-side JavaScript, read the table data, and change a value in the debugger. Tutorial: Importing an Image [page 118] In this tutorial, you use the tools provided by the SAP HANA Web-based Development Workbench to import an image from your local file system. The image is then displayed image in the header of hello world application. Tutorial: Creating, Assigning, and Exporting a Delivery Unit [page 119] In this tutorial, you use the SAP HANA Web-based Development Workbench to create a delivery unit, assign project packages to the new delivery unit, export the delivery unit, and import the delivery unit into another system.
3.9.2.1.1
Tutorial: Creating a Project and Viewing the Trace
In this tutorial, you use the SAP HANA Web-based Development Workbench to create a hello world project, set a trace level, run the project, and view the trace.
Prerequisites
You have access to a running SAP HANA system You have a valid user account in the SAP HANA database on that system You run SAP HANA Web-based Development Workbench in either a Mozilla Firefox or a Google Chrome browser.
Procedure
1. Open the SAP HANA Web-based Development Workbench. 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/xs/ide
Note
SAP HANA user credentials are required to log on.
PUBLIC
115
2. 3. 4. 5.
In the Project menu, choose
Project Templates
Create Hello World Project .
In the Create new Folder dialog box, replace /sap/hana/xs/testProjects with /sap/hana/xs/XSDEMO. In the project sap.hana.xs.XSDEMO, open the file logic.xsjs. At line 5 of logic.xsjs, insert a new line with the following syntax: $.trace.debug(lets say hello to my demo);
6. 7. 8. 9.
Save the file logic.xsjs and refresh the Project view. Right-click the project sap.hana.xs.XSDEMO and choose Set Trace Level. In the Set Trace Level for Project dialog box, specify the trace level Debug. In the project sap.hana.xs.XSDEMO, open the file indexUI5.html, and choose Execute File in Browser Window.
10. In the browser window, choose Call Backend.
3.9.2.1.2
Tutorial: Creating a Table
In this tutorial, you use the SAP HANA Web-based Development Workbench to create a table, insert data into the table, and view the data with the embedded SQL editor.
Prerequisites
You have access to a running SAP HANA system You have a valid user account in the SAP HANA database on that system You run SAP HANA Web-based Development Workbench in either a Mozilla Firefox or a Google Chrome browser
Procedure
Note
SAP HANA user credentials are required to log on. 2. 3. 4. In the Projects view, right-click the project <mycompany>/package/DEMO/XSDEMO and choose Create File. In the Create new File dialog box, enter the name /<mycompany>/package/DEMO/XSDemo.hdbtable. In the new table-definition file, XSDemo.hdbtable, insert the following syntax: table.schemaName = "DEMO"; table.tableType = COLUMNSTORE;
116
PUBLIC
table.columns = [ {name = "ID"; sqlType = BIGINT; nullable = false;}, {name = "COMMENT"; sqlType = NVARCHAR; length = 256; nullable = true;} ]; table.primaryKey.pkcolumns = ["ID"]; 5. 6. 7. Save the file and refresh the Projects view. In the Project view, select the file XSDemo.hdbtable. In the Catalog view, under DEMO Tables select the table sap.hana.xs.XSDEMO::XSDemo to open the SQL editor pane, and choose Execute. At this point, the table is empty. 8. Insert a new line at the beginning of the table and insert the following syntax: INSERT into "DEMO"."mycompany.package.DEMO::XSDEMO"(ID,COMMENT) values(1, 'hello world'); 9. Choose Execute. The values 1 and hello world are stored in the table view, which appears in the table view at the bottom of the window.
3.9.2.1.3
Tutorial: Debugging Server-side Javascript
In this tutorial, you use the embedded debugging tools provided by SAP HANA Web-based Development Workbench to debug server-side JavaScript, read the table data, and change a value in the debugger.
Prerequisites
You have access to a running SAP HANA system You have a valid user account in the SAP HANA database on that system Your administrator has assigned you the user role sap.hana.xs.debugger::Debugger Your SAP HANA administrator has enabled debugging on the SAP HANA system You run SAP HANA Web-based Development Workbench in either a Mozilla Firefox or a Google Chrome browser.
Procedure
Note
SAP HANA user credentials are required to log on.
PUBLIC
117
2. 3.
From the Project view, open the file logic.xsjs. Select lines 5 and 6 and replace them with the following syntax: function getComment() { var comment= ""; var conn = $.db.getConnection(); var pstmt = conn.prepareStatement( 'SELECT COMMENT FROM "D059073"."sap.hana.xs.XSDEMO::XSDEMO" WHERE ID=1' ); var rs = pstmt.executeQuery(); $.response.contentType = "text/plain"; if (rs.next()) { comment = rs.getString(1); } // close result set, prepared statement and connection rs.close(); pstmt.close(); conn.close(); return comment; } $.trace.debug("let's say hello to my demo"); var result = "My database entry is: " + getComment(); $.response.setBody(result);
4. 5. 6. 7. 8. 9.
Save the file and refresh the view. Set debugger break points on lines 6 and 19. To do so, simply choose the lines. The debugger automatically attaches in its own browser session on the server-side. Right-click the file indexUI5.html and choose Execute File in Browser Window. In the browser window, choose Call Backend. In the Scope Variables view, choose Continue. Change the value of the comment variable from hello world to helloXSDemo, press ENTER, and choose Continue.
10. Right-click the file indexUI5.html and choose Execute File in Browser Window.
3.9.2.1.4
Tutorial: Importing an Image
In this tutorial, you use the tools provided by the SAP HANA Web-based Development Workbench to import an image from your local file system. The image is then displayed image in the header of hello world application.
Prerequisites
118
Procedure
Note
SAP HANA user credentials are required to log on. 2. 3. 4. 5. 6. In the Projects view, right-click the project sap.hana.xs.XSDEMO and choose Create Subpackage. In the Create new Package dialog box, change the name from /sap/hana/xs/XSDEMO to /sap/hana/xs/ XSDEMO/Images. Under sap.hana.xs.XSDEMO, right-click the images folder and choose Import File. In the Import File from File System dialog box, choose the image file SAPLogo.gif from your local system and import the file to SAP HANA. Right-click the file indexUI5.html and choose Execute File in Browser Window.
Results
The image appears in the top left corner of the screen.
3.9.2.1.5 Tutorial: Creating, Assigning, and Exporting a Delivery Unit

In this tutorial, you use the SAP HANA Web-based Development Workbench to create a delivery unit, assign project packages to the new delivery unit, export the delivery unit, and import the delivery unit into another system.
Prerequisites
PUBLIC
119
Procedure
Note
SAP HANA user credentials are required to log on. 2. 3. 4. 5. 6. 7. 8. 9. In the Projects view, right-click the project sap.hana.xs.XSDEMO and choose Create new Delivery Unit and assign Project. In the dialog box Create Delivery Unit and assign Package, choose OK. Open and refresh the Delivery Units view. Right-click the XSDEMO delivery unit and choose Export Delivery Unit to local File System. In the Export Delivery Unit dialog box, choose OK. In your browser, open a new instance of the SAP HANA Web-based Development Workbench. In the new instance of SAP HANA Web-based Development Workbench, choose Delivery Unit to local File System . In the Import Delivery Unit from File System dialog box, choose and import the file you exported in the previous step. After you refresh the Delivery Units view, the imported file appears under XSDEMO Packages . Delivery Unit Import
3.9.3
Web-Based Application-Development Tools
SAP HANA Extended Application Services (SAP HANA XS) provides additional, Web-based tools that enable you to maintain SAP HANA and develop your applications, too. In addition to the integrated development environment included with the SAP HANA studio, you can also use a selection of tools, which SAP HANA XS provides in the form of Web-based applications that you can run in Browser; the tools cover the full range of application-development tasks and are available to anyone with remote access to SAP HANA and the appropriate logon credentials.
Note
The Web-based tools provided by SAP HANA XS are available on the SAP HANA XS Web server at the following root URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/. Most tools require logon authentication credentials. The following table lists the Web-based tools that SAP HANA XS provides to facilitate the applicationdevelopment process.
120
PUBLIC
Table 7: Web-based SAP HANA Application-Development Tools Application Name SAP HANA XS Administration Tool URL/Name /sap/hana/xs/admin Inteneded Use Maintain all essential aspects of the application-development process, for example: Application security configuration Application authentication methods HTTP destinations Server/provider trust relationships SAML (Security Assertion Markup Language) configuration including both service and identity providers
SAP HANA XS Debugging
/sap/hana/xs/debugger
Grant access to your debugging sessions based on session tokens and time. Perform light-weight applicationdevelopment tasks without the need for SAP HANA Studio, for example: Inspect, create, change, delete and activate SAP HANA repository objects Navigate the content of the SAP HANA repository according to the package hierarchy View and edit all objects stored in the SAP HANA repository
SAP HANA IDE (Integrated Development Environment) lite
/sap/hana/xs/editor
SAP HANA Web-based Development Workbench
/sap/hana/xs/ide
Perform more robust applicationdevelopment tasks without the need for SAP HANA Studio, for example: Inspect, create, change, delete and activate SAP HANA repository objects Check out SAP HANA repository objects Perform lifecycle management tasks, for example, create, export and import delivery units Commit and activate objects in the SAP HANA repository
PUBLIC
121
Application Name
URL/Name
Inteneded Use View inactive objects in the SAP HANA repository Edit and execute SQL statements Inspect the SAP HANA XS trace files
SAP HANA Application Lifecycle Manager
/sap/hana/xs/lm
Manage the complete applicationdevelopment lifecycle, for example: Use data-provisioning tools Transport content Deploy content Create/maintain delivery units
Related Information Maintaining HTTP Destinations [page 88] 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. Implementing Lifecycle Management [page 563] Application lifecycle management includes all the activities that you need to plan and perform to ensure that the software components you develop for SAP HANA Extended Application Services (SAP HANA XS) are not only produced and shipped in a regulated way but also meet the requirements laid out for the SAP HANA platform. This applies to related objects as well, for example, analytic views and SQLScript artifacts.
122
Setting Up the Persistence Model
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. 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: 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 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 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 transportable sequence has the file extension .hdbsequence, for example, MYSEQUENCE.hdbsequence Import table content Define data-provisioning rules that enable you to import data from comma-separated values (CSV) 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.
SAP HANA Developer Guide Setting Up the Persistence Model
PUBLIC
123
4.1
Creating Schemas
A schema defines the container that holds database objects such as tables, views, and stored procedures.
Prerequisites
This task describes how to create a file containing a schema definition. Schema definition files are stored in the SAP HANA repository. To complete this task successfully, note the following prerequisites: You must have access to an SAP HANA system. You must have already created a development workspace and a project. You must have shared the project so that the newly created files can be committed to (and synchronized with) the repository.
Context
SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database schema as a designtime file in the repository. To create a schema definition file in the repository, perform the following steps:
Procedure
1. 2. 3. 4. Start the SAP HANA studio. Open the SAP HANA Development perspective. Open the Project Explorer view. Create the schema definition file. Browse to the folder in your project workspace where you want to create the new schema-definition file and perform the following tasks: a) Right-click the folder where you want to save the schema-definition file and choose New in the contextsensitive popup menu. b) Enter the name of the schema in the File Name box and add the file suffix .hdbschema, for example, MYSCHEMA.hdbschema. c) Choose Finish to save the new schema in the repository. 5. Define the schema name. To edit the schema file, in the Project Explorer view double-click the schema file you created in the previous step, for example, MYSCHEMA.hdbschema, and add the schema-definition code to the file:
124
Note
The following code example is provided for illustration purposes only. schema_name=MYSCHEMA; 6. 7. Save the schema file. Commit the schema file to the repository. a) Locate and right-click the new schema file in the Project Explorer view. b) In the context-sensitive pop-up menu, choose 8. Activate the schema. a) Locate and right-click the new schema file in the Project Explorer view. b) In the context-sensitive pop-up menu, choose 9. Team Activate . Grant SELECT privileges to the owner of the new schema. After activation in the repository, the 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 in the SAP HANA studio's Modeler perspective, you must grant the user the required SELECT privilege. a) In the SAP HANA studio SAP HANA Systems view, right-click the SAP HANA system hosting the repository where the schema was activated and choose SQL Console in the context-sensitive popup menu. b) In the SQL console, execute the statement illustrated in the following example, where <SCHEMANAME> is the name of the newly activated schema, and <username> is the database user ID of the schema owner: call _SYS_REPO.GRANT_SCHEMA_PRIVILEGE_ON_ACTIVATED_CONTENT('select','<SCHEMANAME>', '<username>'); Related Information Using SAP HANA Projects [page 48] Projects group together all the artifacts you need for a specific part of the application-development environment. Team Commit .
4.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.
PUBLIC
125
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.
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.
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. Name usage The Data Definition Language (DDL) rendered by the repository contains the schema name as a delimited identifier.
126
PUBLIC
4.2
Creating Tables
SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database table as a designtime file in the repository.
Prerequisites
This task describes how to create a file containing a table definition. Table definition files are stored in the SAP HANA repository. To complete this task successfully, note the following prerequisites: You must have access to an SAP HANA system. You must have already created a development workspace and a project. You must have shared the project so that the newly created files can be committed to (and synchronized with) the repository. You must have created a schema definition MYSCHEMA.hdbschema
Context
To create a table file in the repository, perform the following steps:
Procedure
1. 2. 3. 4. Start the SAP HANA studio. Open the SAP HANA Development perspective. Open the Project Explorer view. Create the table definition file. Browse to the folder in your project workspace where you want to create the new table file and perform the following steps: a) Right-click the folder where you want to save the table file and choose New in the context-sensitive popup menu. b) Enter the name of the table in the File Name box and add the file suffix .hdbtable, for example, MYTABLE.hdbtable. c) Choose Finish to save the new table-definition file. 5. Define the table. To edit the table definition, in the Project Explorer view double-click the table-definition file you created in the previous step, for example, MYTABLE.hdbtable, and add the table-definition code to the file:
PUBLIC
127
Note
The following code example is provided for illustration purposes only.
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; indexColumns = ["Col2"];}, {name = "MYINDEX2"; unique = true; indexColumns = ["Col1", "Col4"];}]; table.primaryKey.pkcolumns = ["Col1", "Col2"]; 6. 7. Save the table file. Commit the changes to the repository. a) Locate and right-click the new table file in the Project Explorer view. b) In the context-sensitive pop-up menu, choose Related Information Using SAP HANA Projects [page 48] Projects group together all the artifacts you need for a specific part of the application-development environment. Creating Schemas [page 124] A schema defines the container that holds database objects such as tables, views, and stored procedures. Team Commit .
4.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 designtime 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.
128
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 }; 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; indexColumns = ["Col2"];}, {name = "MYINDEX2"; unique = true; 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. Related Information Table Configuration Schema [page 129] SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database table as a designtime file in the repository. The design-time artifact that contains the table definition must adhere to the .hdbtable syntax specified below.
4.2.2
Table Configuration Schema
SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database table as a designtime file in the repository. The design-time artifact that contains the table definition must adhere to the .hdbtable syntax specified below.
PUBLIC
129
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.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; indexColumns = ["Col2"];}, {name = "MYINDEX2"; unique = true; 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 };
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";
130
PUBLIC
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; The following configuration schema illustrates the parameters you can specify with the tableType keyword: enum TableType { COLUMNSTORE; ROWSTORE; };
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; The following configuration schema illustrates the parameters you can specify with the tableLoggingType keyword: enum TableLoggingType { LOGGING; NOLOGGING; };
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 =
PUBLIC
131
"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; };
Table Order
To define the table order type using the .hdbtable syntax, use the order keyword. In the table definition, the order keyword must adhere to the syntax shown in the following example. table.order = ASC; The following configuration schema illustrates the parameters you can specify with the order keyword: enum Order { ASC; DSC; };
132
You can choose to filter the table contents either by ascending (ASC) or descending (DSC) order.
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 type 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; indexColumns = ["Col2"];}, {name = "MYINDEX2"; unique = true; indexColumns = ["Col1", "Col4"];}]; The following configuration schema illustrates the parameters you can specify with the indexes keyword: struct IndexDefinition { string name; bool unique; optional Order order; optional IndexType indexType; list<string> indexColumns; };
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. table.indexType = B_TREE; The following configuration schema illustrates the parameters you can specify with the indexType keyword: enum IndexType { B_TREE;
PUBLIC
133
};
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 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 nonunique constraint B_TREE All column data types other than those specified for CPB_TREE
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;
134
}; 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 128] 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. Creating Tables [page 127] SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database table as a designtime file in the repository.
optional optional optional optional optional
int32 length; int32 scale; int32 precision; string defaultValue; string comment;
4.3
Creating Reusable Table Structures
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
To complete this task successfully, note the following prerequisites: You must have access to an SAP HANA system. You must have already created a development workspace and a project. You must have shared the project so that the newly created files can be committed to (and synchronized with) the repository. You must have created a schema definition MYSCHEMA.hdbschema
PUBLIC
135
Context
This task describes how to create a file containing a table-structure definition. 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. To create a table-structure file in the repository, perform the following steps:
Procedure
1. 2. 3. 4. Start the SAP HANA studio. Open the SAP HANA Development perspective. Open the Project Explorer view. Create a folder (package) to hold the table-structure definition files. Browse to the folder (package) in your project workspace where you want to create the new folder (package), and perform the following steps: a) In the Project Explorer view, right-click the folder where you want to create a new folder called Structures, and choose New Folder in the context-sensitive popup menu. b) Enter a name for the new folder in the Folder Name box, for example, Structures. c) Choose Finish to create the new Structures folder. 5. Create the table-structure definition file. Browse to the Structures folder (package) in your project workspace and perform the following steps: a) In the Project Explorer view, right-click the Structures folder you created in the previous step and choose New File in the context-sensitive popup menu. b) Enter a name for the new table-structure in the File Name box and add the file suffix .hdbstructure file extension, for example, TableStructure.hdbstructure. c) Choose Finish to save the new table-structure definition file. 6. Define the table structure. To edit the table-structure definition file, in the Project Explorer view double-click the table file you created in the previous step, for example, TableStructure.hdbstructure, and add the table-structure code to the file:
Note
The following code example is provided for illustration purposes only. 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"];
136
PUBLIC
7. 8.
Save the table-structure definition file. Activate the changes in the repository. You can activate the changes to the folder structure and the folder contents in one step. a) In the Project Explorer view, locate and right-click the new folder (Structures) that contains the new table-structure definition file TableStructure.hdbstructure. b) In the context-sensitive pop-up menu, choose c) In the context-sensitive pop-up menu, choose Team Team Commit . Activate .
Activating a table-definition called TableStructure.hdbstructure in the package Structures creates a new table type in SAP HANA, in the same way as the following SQL statement: CREATE TABLE "MySchema"."MyTypeTable" like "MySchema"."Structures::TableStructure" 9. Check that the new table-type object Structures::TableStructure is added to the catalog. You can find the new table type in the SAP HANA Systems view under Table Types . a) In the SAP HANA Development perspective, open the SAP HANA Systems view. b) Select the SAP HANA System where the new is located and navigate to the following node: MYSCHEMA Procedures Table Types Catalog Catalog MYSCHEMA Procedures
c) Right-click the new table-structure object and choose Open Definition to display the specifications for the reusable table-structure in the details panel. d) Check that the entry in the Type box is Table Type. Related Information Creating Schemas [page 124] A schema defines the container that holds database objects such as tables, views, and stored procedures. Creating Tables [page 127] SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database table as a designtime file in the repository.
4.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.
Note
The primary use case for a design-time representation of a table structure is creating reusable type definitions for procedure interfaces..
PUBLIC
137
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. 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 Schema [page 129] SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database table as a designtime file in the repository. The design-time artifact that contains the table definition must adhere to the .hdbtable syntax specified below.
138
4.4
Creating Sequences
A database sequence generates a serial list of unique numbers that you can use while transforming and moving data to between systems.
Prerequisites
This task describes how to create a file containing a sequence definition. Sequence-definition files are stored in the SAP HANA repository. To complete this task successfully, note the following prerequisites: You must have access to an SAP HANA system. You must have already created a development workspace and a project. You must have shared the project so that the newly created files can be committed to (and synchronized with) the repository.
Context
SAP HANA Extended Application Services (SAP HANA XS) enables you to create a database sequence as a design-time file in the repository. To create a sequence definition file in the repository, perform the following steps:
Procedure
1. 2. 3. 4. Start the SAP HANA studio. Open the SAP HANA Development perspective. Open the Project Explorer view. Create the sequence-definition file. Browse to the folder in your project workspace where you want to create the new sequence-definition file and perform the following tasks: a) Right-click the folder where you want to save the sequence-definition file and choose New in the contextsensitive popup menu. b) Enter the name of the sequence in the File Name box and add the file suffix .hdbsequence, for example, MYSEQUENCE.hdbsequence. c) Choose Finish to save the new sequence in the repository. 5. Define the sequence properties. To edit the sequence file, in the Project Explorer view double-click the sequence file you created in the previous step, for example, MYSEQUENCE.hdbsequence, and add the sequence code to the file: schema= "TEST_DUMMY"; start_with= 10;
PUBLIC
139
maxvalue= 30; nomaxvalue=false; minvalue= 1; nominvalue=true; cycles= false; reset_by= "SELECT \"Col2\" FROM \"TEST_DUMMY\".\"com.sap.test.tables::MY_TABLE\" WHERE \"Col2\"='12'"; depends_on_table= "com.sap.test.tables::MY_TABLE"; 6. 7. Save the sequence file. Commit the changes to the repository. a) Locate and right-click the new sequence file in the Project Explorer view. b) In the context-sensitive pop-up menu, choose Related Information Using SAP HANA Projects [page 48] Projects group together all the artifacts you need for a specific part of the application-development environment. Team Commit .
4.4.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
If you want to define a transportable sequence using the design-time sequence specifications, use the configuration schema illustrated in the following example. 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);
140
optional string depends_on_table; optional string depends_on_view; 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 \"Col2\" FROM \"TEST_DUMMY\".\"com.sap.test.tables::MY_TABLE\" WHERE \"Col2\"='12'"; depends_on_table= "com.sap.test.tables::MY_TABLE"; The sequence definition is stored in the repository with the suffix hdbsequence, for example, MYSEQUENCE.hdbsequence. 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.
Note
The sequence cannot be dropped even if the deletion of a sequence object is activated.
4.5
Creating SQL Views
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
This task describes how to create a file containing an SQL view definition. SQL view definition files are stored in the SAP HANA repository. To complete this task successfully, note the following prerequisites: You must have access to an SAP HANA system. You must have already created a development workspace and a project. You must have shared the project so that the newly created files can be committed to (and synchronized with) the repository.
PUBLIC
141
Context
To create a view-definition file in the repository, perform the following steps:
Procedure
1. 2. 3. 4. Start the SAP HANA studio. Open the SAP HANA Development perspective. Open the Project Explorer view. Create the view-definition file. Browse to the folder in your project workspace where you want to create the new view-definition file and perform the following tasks: a) Right-click the folder where you want to save the view-definition file and choose New in the contextsensitive popup menu. b) Enter the name of the view-definition file in the File Name box and add the file suffix .hdbview, for example, MYVIEW.hdbview. c) Choose Finish to save the new view-definition file in the repository. 5. Define the view. To edit the view-definition file, in the Project Explorer view double-click the view-definition file you created in the previous step, for example, MYVIEW.hdbview, and add the view-definition code to the file:
Note
The following code example is provided for illustration purposes only. schema="TEST_DUMMY"; query="SELECT * FROM \"TEST_DUMMY\".\"com.sap.test.tables::02_HDB_DEPARTMENT_VIEW \""; depends_on_view=["com.sap.test.tables::02_HDB_DEPARTMENT_VIEW"]; 6. 7. Save the view-definition file. Commit the changes to the repository. a) Locate and right-click the new view-definition file in the Project Explorer view. b) In the context-sensitive pop-up menu, choose Related Information Using SAP HANA Projects [page 48] Projects group together all the artifacts you need for a specific part of the application-development environment. Team Commit .
4.5.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.
142
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 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. To define a transportable view using the design-time view specifications, use the configuration schema illustrated in the following example: string schema; string query; bool public(default=true); optional list<string> depends_on_table; optional list<string> depends_on_view; The following example shows the contents of a valid transportable view-definition file for a view called MYVIEW: schema="TEST_DUMMY"; query="SELECT * FROM \"TEST_DUMMY\".\"acme.com.test.tables::02_HDB_DEPARTMENT_VIEW \""; depends_on_view=["acme.com.test.tables::02_HDB_DEPARTMENT_VIEW"]; 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.
Note
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.
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
PUBLIC
143
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.6
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 .hdbtable file) can either be created separately or be part of 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 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 145] 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. Table-Import Configuration-File Syntax [page 147]
144
PUBLIC
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. Using Imported Table Data in SAP HANA
4.6.1
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. 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
PUBLIC
145
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
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. 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. Related Information Table-Import Configuration-File Syntax [page 147] 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.
146
4.6.2
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; delimField = ";"; 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 tableimport 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";
PUBLIC
147
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. However, if the table specified with the cdstable or .hdbtable keyword is not defined with the corresponding syntax, SAP HANA displays an error on activation, 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 does not exist, SAP HANA XS displays an error message during the activation of the configuration file, for example: Schema could not be resolved. or 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 tableimport 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";
148
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;
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.
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
PUBLIC
149
4.6.3
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 8: Table-Import Error Messages Message Number 40200 Message Text Invalid combination of table declarations found, you may only use [cdstable | hdbtable | table] Message Reason 1. The table keyword is specified in a tableimport configuration that references a table defined using the .hdbtable (or .hdbdd) syntax. 2. The hdbtable keyword is specified in a table-import configuration that references a table defined using another table-definition syntax, for example, the .hdbdd syntax. The cdstable keyword is specified in a table-import configuration that references a table defined using another table-definition syntax, for example, the .hdbtable syntax. You specified a target table with the table keyword but did not specify a schema with the schema keyword. The schema specified with the schema keyword does not exist or could not be found (wrong name). 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). The database could not complete the schema-resolution process for some reason - perhaps unrelated to the tableimport configuration (.hdbti), for example, an inconsistent database status. 40204 Table import target table cannot be found 1. The table specified with the table keyword does not exist or could not be found (wrong name or wrong schema name).
3.
40201
If you import into a catalog table, please provide schema
1.
40202
Schema could not be resolved
1.
2.
2.
150
Message Number 40210
Message Text Table import syntax error
Message Reason 1. The table-import configuration file (.hdbti) contains one or more syntax errors.
40211
Table import constraint checks failed
1.
The same key is specified in multiple table-import configurations (.hdbti files), which leads to overlaps in the range of data to import.
2.
If keys are specified for an import in a table-import configuration, multiple imports into the same target table are checked for potential data collisions
4.6.4
Tutorial: Importing 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 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. Before you start this task, make sure that the following prerequisites are met: An SAP HANA database instance is available. The SAP HANA database client is installed and configured. You have a database user account set up with the roles containing sufficient privileges to perform actions in the repository, for example, add packages, add objects, and so on. The SAP HANA studio is installed and connected to the SAP HANA repository. You have a development environment including a repository workspace, a package structure for your application, and a shared project to enable you to synchronize changes to the project files in the local file system with the repository.
Note
The names used in the following task are for illustration purposes only; where necessary, replace the names of schema, tables, files, and so on shown in the following examples with your own names.
PUBLIC
151
Procedure
1. Create a root package for your table-import application. In SAP HANA studio, open the SAP HANA Development perspective and perform the following steps: a) In the package hierarchy displayed in the SAP HANA Systems view, right-click the package where you want to create the new package for your table-import configuration and choose own namespace, for example mycompany.tests.TiTest New > Package... . b) Enter a name for your package, for example TiTest. You must create the new TiTest package in your
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. a) Choose OK to create the new package. 2. Create a set of table-import files. The following files are required for a table import scenario.
Note
For the purposes of this tutorial, the following files must all be created in the same package, for example, a package called TiTest. However, the table-import feature also allows you to use files distributed in different packages. The table-import configuration file, for example, TiConfiguration.hdbti Specifies the source file containing the data values to import and the target table in SAP HANA into which the data must be inserted A CSV file, for example, myTiData.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. 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 TiTable.hdbtable, a design-time table defined using the .hdbtable syntax. The schema definition, for example, TISCHEMA.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 a source file, such as a CSV file, into the desired target table. 3. Using any code editor, create or open the schema definition (AMT.hdbschema) file and enter the name of the schema you want to use to contain the target table. schema_name="AMT";
152
PUBLIC
4.
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 = "";}, {name = "name"; sqlType = VARCHAR; nullable = true; length = 30; comment = "";}, {name = "city"; sqlType = VARCHAR; nullable = true; length = 30; comment = "";} ]; table.primaryKey.pkcolumns = ["ID"];
5.
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. . 6. Create or open the table-import configuration file (inhabitants.hdbti) and enter the following lines of text. import = [ {
]; 7.
table = "mycompany.tests.TiTest::inhabitants"; schema = "AMT"; file = "mycompany.tests.TiTest:inhabitants.csv"; header = false;
Deploy the table import. a) Select the package that you created in the first step, for example, mycompany.tests.TiTest. b) Click the alternate mouse button and choose Commit. c) Click the alternate mouse button and choose Activate. This activates all the repository objects. The result is that the data specified in the 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.
8.
In the SAP HANA studio, check the contents of the runtime table inhabitants in the catalog to ensure that the correct data was imported into the correct columns.
PUBLIC
153
4.7
Data Persistence Objects in Core Data Services (CDS)
Core data services (CDS) is a new infrastructure for defining and consuming semantically rich data models in SAP HANA. Using a a data definition language (DDL), a query language (QL), and an expression language (EL), CDS is envisioned to encompass write operations, transaction semantics, constraints, and more. The model described in CDS enables you to use the Data Definition Language to define the objects that make up the data-persistence model. You can save the data-persistence object definition as a design-time object that you manage in the SAP HANA repository and activate when necessary. You can use the CDS specification to define tables (known as entities). These design-time objects are used to generate runtime objects on activation in the repository. The objects can be referenced using either the runtime name in the catalog or the name of the design-time object in the repository. The design-time object definition that you create using the CDS-compliant syntax must have the file extension .hdbdd, for example, MyCDSTable.hdbdd.
Naming Conventions for CDS Objects

The rules for naming CDS documents or packages are identical. 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: Permitted characters CDS object and package names can include the following characters: Lower or upper case letters (aA-zZ) 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 or acme.com.1package The CDS parser does not recognize either CDS document names or package names that consist exclusively of digits, for example, 1234.hdbdd or acme.com.999.
Related Information CDS Entities [page 156] 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. CDS Contexts [page 159] You can define multiple CDS-compliant entities (tables) in a single file by assigning them to a context. CDS Structured Types [page 158] 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 by another structured type. CDS User-Defined Types [page 161]
154
User-defined data types reference existing structured types (Integer, String...) or the individual types (for example, field, type, or context) used in another data-type definition.
4.7.1
CDS Editor
The CDS editor is a tool that is designed to help you create and modify design-time objects containing data definitions specified with the Core Data Services (CDS) syntax. SAP HANA studio includes a dedicated editor that you can use to define data-persistence objects using the CDS syntax. SAP HANA studio recognizes the .hdbdd file extension required for CDS object definitions and calls the appropriate repository plugin. If you double-click a file with the .hdbdd extension in the Project Explorer view, SAP HANA studio automatically displays the selected file in the CDS editor. The CDS editor provides the following features: Syntax highlights The CDS DDL editor supports syntax highlighting, for example, for keywords and any assigned values (@Schema: 'MySchema'). You can customize the colors and fonts used in the Eclipse Preferences ( Window Preferences General Appearance Colors and Fonts CDS DDL ).
Note
The CDS DDL editor automatically inserts the mandatory keywords namespace and context into any new DDL source file that you create using the New DDL Source File dialog. The following values are assumed: namespace = <Current Project Name> context = <New DDL File Name>
Keyword completion The editor displays a list of DDL suggestions that could be used to complete the keyword you start to enter. You can insert any of the suggestions using the TAB key. Code validity You can check the validity of the syntax in your DDL source file before activating the changes in the SAP HANA repository. Right-click the file containing the syntax to check and use the the context menu. Team Check option in
Note
Activating a file automatically commits the file first. Comments Text that appears after a double forward slash (//) is interpreted as a comment and highlighted in the CDS editor (for example, //this is a comment).
Tip
The Project Explorer view associates the .hdbdd file extension with the DDL icon. You can use this icon to determine which files contain CDS-compliant DDL code.
PUBLIC
155
4.7.2
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.
156
The following code illustrates an example of a single design-time entity definition using CDS-compliant DDL:
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 below, you would 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; Publisher : String(100); }; 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 plugin 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.
Entity Element Modifiers

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 nullable modifier. The key element is non nullable by default because NULL cannot be used in the key element. In combination with a default value nullable Defines if the entity element can (nullable) or cannot (not nullable) have the value NULL. If neither nullable nor not nullable is specified for the element, the default value nullable applies (except for
PUBLIC
157
the key element), which means the element can have the value NULL. If you use the nullable modifier, note the following points: The not nullable modifier can only be added with the first (initial) activation of a CDS entity. Existing nullable elements cannot subsequently be changed to not nullable since existing data might already contain NULL values. When adding a new not nullable 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. nullable elements with default values are permitted default <literal_value> Defines the default value for the 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 key nullable MyKey2 key MyKey3 elem2 nullable elem3 not nullable elem4 }; : : : : : : Integer; Integer; Integer default 2; String(20) default "John Doe"; String(20) default "John Doe"; String default "Jane Doe"; // // // // // // ok illegal combination illegal combination ok ok ok
Note the following illegal combinations of entity element and element modifier in the example above: key nullable MyKey2 : Integer; You cannot combine the element key with the element modifier nullable. key MyKey3 : Integer default 2; You cannot combine the element key with the element modifier default. Related Information CDS Primitive Data Types [page 165] In Data Definition Language (DDL), primitive (or core) data types are the basic building blocks that you use to define entities or structure types such as tables and views with DDL. For example, you can use the String, Binary, or Integer data types to specify the content of entity (table) columns.
4.7.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 by another structured type. 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 CDScompliant 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. If you want to define a transportable structured type using the CDS, design-time .hdbdd specifications, use the configuration schema illustrated in the following example:
158
PUBLIC
Note
If you are using a CDS document to specify a single CDS-compliant data type, the name of the CDS document must match the name of the data type defined in the CDS document, for example, with the type keyword. In the example below, you would save the data-type definition Type1 in the CDS document Type1.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' // Structured types type Type1 { Fstr: String( 5000 ); Flstr: LargeString; Fbin: Binary( 4000 ); Flbin: LargeBinary; Fint: Integer; Fint64: Integer64; Ffixdec: Decimal( 34, 34 ); Fdec: DecimalFloat; Fflt: BinaryFloat; Flocdat: LocalDate; Floctim: LocalTime; Futcdatim: UTCDateTime; Futctstmp: UTCTimestamp; }; On activation, the data types appear in the SAP HANA Systems view of the SAP HANA Development perspective under Catalog SchemaName Procedures Table Types .
4.7.4
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 would 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 {
PUBLIC
159
key AuthorID key BookTitle ISBN Publisher };
: : : :
String(10); String(100); Integer; String(100);
@Catalog.tableType: #COLUMN @Catalog.index : [ { name: 'MYINDEX2', unique: true, order: #DESC, elementNames: ['AuthorName'] } ] entity AUTHOR { key AuthorName : String(100); key AuthorNationality : String(20); AuthorBirthday : String(100); AuthorAddress : String(100); }; }; Activation of the file BOOKS.hdbdd containing the context and entity definitions would create the catalog objects BOOK and AUTHOR.
Note
The namespace specified at the start of the file, for example, com.acme.myapp1 corresponds to the location of the entity definition file (.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 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, or type).
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, table or structured type. namespace com.acme.myapp1; @Schema: 'MySchema' context MyContext { // Nested contexts context InnerCtx { Entity MyEntity { }; Type CtxType { a : Integer; b : String(59);
160
}; }; 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'] }] 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; // refers to nested context field7 : InnerCtx.CtxType; // more context references }; }; Related Information CDS Configuration Schema CDS User-Defined Data Types [page 161] User-defined data types reference existing structured types (Integer, String...) or the individual types (for example, field, type, or context) used in another data-type definition.
4.7.5
CDS User-Defined Data Types
User-defined data types reference existing structured types (Integer, String...) 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: Integer, String, Binary... Referencing another data type
In the following example, the data-type definition field2 : MyType1; specifies a new data type field2 that is based on the specification in the user-defined data type MyType1.
PUBLIC
161
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 example below, you would 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' // Simple user-defined data types 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; }; The following code example shows how to use the type of keyword to define a data-type field 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; @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 data-type (field4) using the definition specified in another user-defined data-type field3: field4 : type of field3; Define a new data-type field5 using the definition specified in a field (field2) that belongs to another userdefined data type (MyType1): field5 : type of MyType1.field2; Define a new data-type (field6) using an existing field (b) that belongs to a data type (CtxType) in another context (InnerCtx): field6 : type of InnerCtx.CtxType.b;
162
PUBLIC
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'] }] 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; // refers to nested context field7 : InnerCtx.CtxType; // more context references }; };
4.7.6
Comments in CDS Object Definitions
You can add comments to the code you use to define CDS objects such as contexts, entities, and data types. You can use the forward slash (/) and the asterisk (*) characters in various combinations to add comments and general information to CDS object-definition files, as illustrated in the following examples:
PUBLIC
163
End-of-line comment: element Flocdat: LocalDate; // Comment text
Ignore everything after the double forward slash (//) and up to the end of the line. Complete line comment // element Flocdat: LocalDate; Additional comment text
Ignore the contents of an entire line. In-line comment: element Flocdat: /*comment text*/ LocalDate;
Ignore all text placed between the forward slash-asterisk (/*) and the asterisk-forward slash (*/) characters. Multi-line comment: /** * multiline, * doxygen-style * comments and annotations */ Ignore all text placed between the forward slash-asterisk (/**) and the asterisk-forward slash (*/) characters including any intervening lines that start with the asterisk (*).
Example
Comments in CDS Object Definitions namespace com.acme.myapp1; @Schema: 'MYSCHEMA' // CDS syntax for comments /** * multiline, * 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; //element Flocdat: LocalDate; LocalDate temporarily switched off // Floctim: LocalTime; element Futcdatim: UTCDateTime; Futctstmp: UTCTimestamp; };
164
4.7.7
CDS Primitive Data Types
In Data Definition Language (DDL), primitive (or core) data types are the basic building blocks that you use to define entities or structure types such as tables and views with DDL. For example, you can use the String, Binary, or Integer data types to specify the content of entity (table) columns. The following table lists all currently supported simple SAP HANA and DDL core 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. Table 9: SAP HANA DDL Primitive Types Name String (n) Description Variable-length Unicode string with a specified maximum length of n=1-1333 characters (5000 for SAP HANA specific objects). Default = maximum length. Variable length string of up to 2 GB (no comparison) Variable length byte string with user-defined length limit of up to 4000 bytes SQL Literal Syntax 'text with quote' SQL Name NVARCHAR EDM Name String
LargeString Binary(n)
'text with quote' x'01Cafe', X'01Cafe'
NCLOB VARBINARY
String Binary
LargeBinary Integer
Variable length byte string of up to x'01Cafe', X'01Cafe' 2 GB (no comparison) Respective container's standard signed integer. Signed 32 bit integers in 2's complement, -2**31 .. 2**31-1. Default=0 Signed 64-bit integer with a value range of -2^63 to 2^63-1. Default=0. Decimal number with fixed precision (p) in range of 1 to 34 and fixed scale (s) in range of 0 to p. 13, -1234567
BLOB BIGINT
Binary Int64
Integer64
13, -1234567
BIGINT
Int64
Decimal( p, s )
12.345, -9.876
DECIMAL( p, s )
Decimal
DecimalFloat
Decimal floating-point number 12.345, -9.876 (IEEE 754-2008) with 34 mantissa digits; range is roughly 1e-6143 through 9.99e+6144 Binary floating-point number (IEEE 754), 8 bytes (roughly 16 decimal digits precision); range is roughly 2.2207e-308 through 1.7977e+308 1.2, -3.4, 5.6e+7
DECIMAL
Decimal
BinaryFloat
DOUBLE
Double
PUBLIC
165
Name LocalDate
Description Local date with values ranging from 0001-01-01 through 9999-12-31, and a special initial value
SQL Literal Syntax date'1234-12-31'
SQL Name DATE
EDM Name DateTimeOffs et Combines date and time; with time zone must be converted to offset
LocalTime
Time values (with seconds time'23:59:59', precision) and values ranging from time'12:15' 00:00:00 through 24:00:00, and a special initial value
TIME
Time For duration/ period of time (==xsd:durati on). Use DateTimeOffs et if there is a date, too.
UTCDateTime
UTC date and time (with seconds timestamp'2011-12-31 precision) and values ranging from 23:59:59' 0001-01-01 00:00:00 through 9999-12-31 23:59:59, and a special initial value
SECONDDATE
DateTimeOffs et Values ending with Z for UTC. Values before 1753-01-01T0 0:00:00 are not supported; transmitted as NULL.
UTCTimestam p
UTC date and time (with a precision of 0.1 microseconds) and values ranging from 0001-01-01 00:00:00 through 9999-12-31 23:59:59.9999999, and a special initial value
timestamp'2011-12-31 23:59:59.7654321'
TIMESTAMP
DateTimeOffs et With Precision = 7
4.7.8
CDS Annotations
CDS supports built-in annotations, for example, @Catalog and @Schema, which are used in the definition of CDScompliant catalog objects.
166
@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/nonunique @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 contexts 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; 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' 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 column. 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.
PUBLIC
167
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 { key 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 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.
168
PUBLIC
@Schema
The @Schema annotation used in the following code example ensures that a schema called 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); };
Note
If the schema specified with the @Schema annotation does not already exist, an activation error is displayed and the entity-creation process fails.
4.7.9
Tutorial: Getting 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
This task describes how to create a file containing a CDS entity (table definition) using DDL. Before you start this task, note the following prerequisites: You must have access to an SAP HANA system. You must have already created a development workspace and a project. You must have shared the project so that the newly created files can be committed to (and synchronized with) the repository. You must have created a schema definition MYSCHEMA.hdbschema.
Context
The SAP HANA studio provides a dedicated DDL editor to help you define data-related artifacts. To create a simple database table with the name "MyTable", perform the following steps:
PUBLIC
169
Procedure
1. 2. 3. 4. Start the SAP HANA studio. Open the SAP HANA Development perspective. Open the Project Explorer view. Create the CDS document that defines the entity you want to create. Browse to the folder in your project workspace where you want to create the new CDS document (for example, in a project you have already created and shared) and perform the following tasks: a) Right-click the folder where you want to create the CDS document and choose File in the context-sensitive popup menu. New DDL Source
Note
This menu option is only available from shared projects; projects that are linked to the SAP HANA repository. b) Enter the name of the entity in the File Name box, for example, MyFirstCDSSourceFile.
Note
The file extension .hdbdd is added automatically to the new DDL file name when you click Finish. The repository uses the file extension to make assumptions about the contents of repository artifacts, for example, that .hdbdd files contain DDL statements.
170
PUBLIC
c) Choose Finish to save the new empty CDS document.
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. 5. Define the table entity. To edit the CDS document, in the Project Explorer view double-click the file you created in the previous step, for example, BOOK.hdbdd, and add the entity-definition code:
Note
The CDS DDL editor automatically inserts the mandatory keywords namespace and context into any new DDL source file that you create using the New DDL Source File dialog. The following values are assumed: namespace = <Current Project Name> 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; Publisher : String(100); }; 6. 7. Save the CDS document. Commit the changes to the repository. a) Locate and right-click the new CDS document BOOK.hdbdd in the Project Explorer view. b) In the context-sensitive pop-up menu, choose 8. Team Commit .
Save the new CDS document and activate it in the repository. a) In the Project Explorer view, locate the newly created artifact BOOK.hdbdd. b) Right-click BOOK.hdbdd and choose Team > Activate in the context-sensitive popup menu. The CDS/DDL editor checks the syntax of the source file code, highlights the lines where an error occurs, and provides details of the error in the Problems view.
PUBLIC
171
The activation creates the following table in the schema MYSCHEMA, both of which are visible using the SAP HANA studio: "MYSCHEMA"."mycompany.myapp1::BOOK" The following public synonym is also created, which can be referenced using the standard CDS-compliant query notation: "mycompany.myapp1::BOOK" 9. Add an entry to the BOOK entity using SQL. INSERT INTO "mycompany.myapp1::BOOK" VALUES ( 'Shakespeare', 'Hamlet', '1234567', 'Books Incorporated' ); 10. Save and activate the modifications to the entity. 11. Run a simply query using the standard CDS-compliant query notation. SELECT COUNT(*) FROM "mycompany.myapp1::BOOK" WHERE Author = 'Shakespeare' Related Information Creating Schemas [page 124] A schema defines the container that holds database objects such as tables, views, and stored procedures.
4.7.10 Tutorial: Importing 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.
172
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. Before you start this task, make sure that the following prerequisites are met: An SAP HANA database instance is available. The SAP HANA database client is installed and configured. You have a database user account set up with the roles containing sufficient privileges to perform actions in the repository, for example, add packages, add objects, and so on. The SAP HANA studio is installed and connected to the SAP HANA repository. You have a development environment including a repository workspace, a package structure for your application, and a shared project to enable you to synchronize changes to the project files in the local file system with the repository.
Note
The names used in the following task are for illustration purposes only; where necessary, replace the names of schema, tables, files, and so on shown in the following examples with your own names.
Procedure
1. Create a root package for your table-import application. In SAP HANA studio, open the SAP HANA Development perspective and perform the following steps: a) In the package hierarchy displayed in the SAP HANA Systems view, right-click the package where you want to create the new package for your table-import configuration and choose own namespace, for example mycompany.tests.TiTest New > Package... . b) Enter a name for your package, for example TiTest. You must create the new TiTest package in your
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. a) Choose OK to create the new package. 2. Create a set of table-import files. The following files are required for a table import scenario.
Note
For the purposes of this tutorial, the following files must all be created in the same package, for example, a package called TiTest. However, the table-import feature also allows you to use files distributed in different packages The table-import configuration file, for example, TiConfiguration.hdbti
PUBLIC
173
Specifies the source file containing the data values to import and the target table in SAP HANA into which the data must be inserted A CSV file, for example, myTiData.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. 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 TiTable.hdbdd, a design-time table defined using the CDS-compliant .hdbdd syntax. The schema named AMT Specifies the name of the schema in which the target import table resides When all the necessary files are available, you can import data from a source file, such as a CSV file, into the desired target table. 3. 4. If it does not already exist, create a schema named AMT in the catalog; the AMT schema is where the target table for the table-import operation resides. 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.
Note
In the CDS-compliant .hdbdd syntax, the namespace keyword denotes the path to the package containing the table-definition file. namespace mycompany.tests.TiTest; @Schema : 'AMT' @Catalog.tableType : #COLUMN entity inhabitants { key ID : Integer; surname : String(30); name : String(30); city : String(30); }; 5. 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
174
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. 6. Create or open the table-import configuration file (inhabitants.hdbti) and enter the following lines of text. import = [ {
]; 7.
table = "mycompany.tests.TiTest::inhabitants"; schema = "AMT"; file = "mycompany.tests.TiTest:inhabitants.csv"; header = false;
Deploy the table import. a) Select the package that you created in the first step, for example, mycompany.tests.TiTest. b) Click the alternate mouse button and choose Commit. c) Click the alternate mouse button and choose Activate. This activates all the repository objects. The data specified in the 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.
8.
In the SAP HANA studio, check the contents of the runtime table inhabitants in the catalog to ensure that the correct data was imported into the correct columns.
PUBLIC
175
Setting Up the Analytic Model
Modeling refers to an activity of refining or slicing data in database tables by creating views to depict a business scenario. The views can be used for reporting and decision-making. The modeling process involves the simulation of entities, such as CUSTOMER, PRODUCT, and SALES, and relationships between them. These related entities can be used in analytics applications such as SAP BusinessObjects Explorer and Microsoft Office. In SAP HANA, these views are known as information views. Information views use various combinations of content data (that is, non-metadata) to model a business use case. Content data can be classified as follows: Attribute: Descriptive data, such as customer ID, city, and country. Measure: Quantifiable data, such as revenue, quantity sold and counters.
You can model entities in SAP HANA using the Modeler perspective, which includes graphical data modeling tools that allow you to create and edit data models (content models) and stored procedures. With these tools, you can also create analytic privileges that govern the access to the models, and decision tables to model related business rules in a tabular format for decision automation. You can create the following types of information views: Attribute Views Analytic Views Calculation Views
Related Information SAP HANA Studio
5.1 5.1.1
Setting Up the Modeling Environment Setting Modeler Preferences
You can set modeling preferences to thedefault settings that the system uses when you log on.
Procedure
1. Choose Window Preferences Modeler .
Note
You can also set the preferences choosing 2. Quick Launch Manage Preferences
Identify the required preference and perform the corresponding steps:
176
PUBLIC
SAP HANA Developer Guide Setting Up the Analytic Model
Requirement
To specify the structure of content packages in the SAP HANA Systems view
Preference
Content Presentation
Substeps
Under Package Presentation select one of the following options: Hierarchical - to view the package structure in a hierarchical manner such that the child folder is inside the parent folder. Flat - to view all the packages at the same level, for example, sap, sap.ecc, sap.ecc.ui. Show Object Type Folders - to group together similar objects in a package such as attribute views in the Attribute View package. Show all objects in the SAP HANA Systems view - to view all the repository objects in the SAP HANA Systems view. If this option is unchecked, only modeler objects are available in the SAP HANA Systems view. Also, if the option is unchecked and the user package has no modeler object, but it contains other hidden repository objects, then the user package is marked with contains hidden objects . If the option is checked, all the repository objects are shown in the SAP HANA Systems view with their names suffixed with the object type such as, ABC.attributeview.
Note
Select the checkbox to make nonmodeler object types are visible. However, not all the operationsare supported. To set the preferences for loading data Data From Local File using flat file
1.
Browse the location to save error log files for data load using flat files. Enter the batch size for loading data. For example, if you specify 2000 and a file has records of 10000 rows the data load will happen in 5 batches.
2.
PUBLIC
177
Requirement
Preference
Substeps
3. Enter a decision maker count that will be used to propose data types based on the file. For example, enter 200 if you want the proposal to be made based on the 200 rows of file data.
To set the default value for the client that will be used while previewing model data To enforce various rules on objects
Default Model Parameters
Choose the client from Default Client.
Validation Rules
Select the required rules to be applied while performing object validation.
Note
Enforcing validation rules with severity Error are mandatory. To determine the numbers of rows to be displayed in a page To specify a location for job log files Data Preview Logs Select the maximum rows for data preview as required. Expand the Logs node and choose Job Log.Browse the location where you want to save the job log files. 1. 2. 3. Expand the Logs node and select Job Log. Choose True. Browse the location where you want to save the repository log files.
To enable logging for repository calls and specify a location for repository log files
Logs
To enable search for the attributes used in the views To allow lower case alphabets for attribute view, analytic view, calculation view, procedure and analytic privilege names
Search Options Case Restriction
Choose Enable Search Attributes. Deselect the Model name in upper case checkbox.
3.
Choose Apply and OK.
5.1.2
Setting Keyboard Shortcuts
You can enable keyboard shortcuts for modeling actions such as, activate and validate. The supported commands with the default keyboard shortcuts are as follows: Command Activate Activate Add Table/Model Binding Ctrl+Shift+A Ctrl+Shift+A Ctrl+Shift+= When Navigator In Windows In Windows Category Modeler Keys Modeler Keys Modeler Keys
178
Auto Arrange Data Preview Data Preview Display XML Find Fit to Window Move Element in Output Pane (Direction: Down) Move Element in Output Pane (Direction: Up) Open
Ctrl+L Ctlr+Shift+P Ctlr+Shift+P Alt+D Ctrl+F Ctrl+0 Ctrl+] Ctrl+[ Ctrl+O
In Windows Navigator In Windows In Windows Navigator In Windows In Windows In Windows Navigator In Windows In Windows In Windows In Windows Navigator In Windows In Windows In Windows Keys .
Modeler Keys Modeler Keys Modeler Keys Modeler Keys Modeler Navigator Modeler Keys Modeler Keys Modeler Keys Modeler Keys Views Views Views Modeler Keys Modeler Keys Modeler Keys Modeler Keys Modeler Keys
Show View (View: History) Alt+Shift+H Show View (View: Job Log) Show View (View: WhereUsed List) Validate Validate Zoom (Type: In) Zoom (Type: Out) Zoom (Type: Reset) 1. 2. 3. Choose Window Alt+Shift+L Alt+Shift+U Ctrl+Shift+V Ctrl+Shift+V Ctrl+= Ctrl+Alt+Shift+0 Preferences General
In the Keys panel, choose Modeler as a Scheme. If you only want to see the keyboard shortcuts for the Modeler , enter Modeler Keys in the text field.
Note
You cannot add new commands, but you can customize the commands as follows: Copy Command - to provide a different keyboard shortcut for an existing command. Unbind Command - to clear the key bindings with the command and provide a new keyboard shortcut for an existing command. Restore Command - to restore the default key bindings provided by the Modeler for an existing command.
4.
Choose Apply.
PUBLIC
179
5.2 5.2.1
Creating Views Attributes and Measures
Attributes and measures form the content data that is used for modeling. While attributes represent the descriptive data like city and country, measures represent quantifiable data like revenue and quantity sold.
Attributes
Attributes are the individual non-measurable analytical elements. Simple Attributes Simple attributes are individual non-measurable analytical elements that are derived from the data foundation. For example, PRODUCT_ID and PRODUCT_NAME are attributes of a PRODUCT subject area. Calculated Attributes Calculated attributes are derived from one or more existing attributes or constants. For example, deriving the full name of a customer (first and last name), assigning a constant value to an attribute that can be used for arithmetic calculations. Local Attributes Local attributes used in an analytic view allow you to customize the behavior of an attribute for only that view. For example, if an analytic view or a calculation view include an attribute view, it inherits the behavior of the attributes from the attribute view. If you set the parameter once, it is replicated in all views that are consuming it.
Note
If you create an analytic view for one specific use case in which you want a particular attribute to behave differently than it does in the attribute view to which it belongs, you can define it as a local attribute.
Measures
Measures are measurable analytical elements. Measures are derived from the analytic and calculation views. Simple Measures A simple measure is a measurable analytical element that is derived from the data foundation. For example, PROFIT. Calculated Measure Calculated measures are defined based on a combination of data from OLAP cubes, arithmetic operators, constants, and functions. For example, calculated measures can be used to calculate the total sales of a product across five regions, or to assign a constant value to a measure for a calculation. Restricted Measure
180
PUBLIC
Restricted measures are used to filter the value based on the user-defined rules for the attribute values. Counters Counters add a new measure to the calculation view definition to count the recurrence of an attribute. For example, to count how many times product appears.
Note
You can choose to hide the attributes and measures that are not required for client consumption. For example, for a complex calculation that is derived from a series of computations, you can hide the levels of computations that are not required for reporting purposes.
5.2.2
First Steps to View Creation
You create views to model various slices of the data stored in an SAP HANA database. In SAP HANA terminology they are known as Information Views.
Context
Information views use various combinations of content data (that is, non-metadata) to model a business use case. Content data can be classified as follows: Attribute - Represents the descriptive data like customer ID, city, country, and so on. Measure - Represents the quantifiable data such as revenue, quantity sold, counters, and so on. Information views are often used for analytical use cases such as operational data mart scenarios or multidimensional reporting on revenue, profitability, and so on. There are three types of information views: attribute view, analytic view, and calculation view. All three types of information views are non-materialized views. This creates agility through the rapid deployment of changes. Before you start modeling your data as information views, you perform the following subtasks:
Procedure
1. Create a development workspace. The workspace is the link between the SAP HANA repository and your local filesystem, where you work on project-related objects. 2. Create a project. Create a new project for a particular application or package; you can use the project to collect in a convenient place all your application-related artifacts. For information views, create a General project. 3. Share a project.
PUBLIC
181
Sharing a project enables you to ensure that changes you make to project-related files are visible to other team members and applications. Shared projects are available for import by other members of the application-development team. 4. 5. Select a project and in the context menu, choose In the pop-up wizard, select SAP HANA Modeler. a) Select the required view Attribute View, Analytic View, Calculation View or Analytic Privilege as required. b) Choose Next. 1. In the New Information View dialog, enter a name and description. New Other... .
Note
If the project is shared, the Package field specifies the package that is associated with the project. 2. In case of an attribute view, select the required oprion in the Subtype as follows: Scenario Create a view with table attributes. Create a view with time characteristics. Substeps In the Sub Type dropdown list, choose Standard.
1. 2.
In the Sub Type dropdown list, choose Time. Select the required calendar type as follows: a. b. If the calendar type is Fiscal, select a variant schema, and a fiscal variant. If the calendar type is Gregorian, select the granularity for the data.
3.
To use the system-generated time attribute view, select Auto Create.
Note
The system creates a time attribute view based on the default time tables, and defines the appropriate columns/attributes based on the granularity. It also creates the required filters.
Note
The tables used for time attribute creation with calendar type Gregorian are, M_TIME_DIMENSION, M_TIME_DIMENSION_ YEAR, M_TIME_DIMENSION_ MONTH, M_TIME_DIMENSION_WEEK and for calendar type Fiscal is M_FISCAL_CALENDAR. If you want to do a data preview for the created attribute view, you need to generate time data into the mentioned tables from the Quick Launch tab page. Derive a view from an existing view in this case, you cannot modify the derived view that acts 1. 2. In the Sub Type dropdown, choose Derived. Select the required attribute view.
182
Scenario as a reference to the base attribute view.
Substeps
Note
If the project is not shared, the auto-creation of time attribute view and creation of derived attribute vuew is not possible. 3. In case of a calculation view, perform the following: a. Select the required Subtype as described below: b. c. Graphical - to use to the graphical modeling features for creation of calculation view SQL Script - to write SQL statements for calculation view script
If the subtype is SQL Script, set the Parameter case sensitive to true or false as you want the calculation view output parameter naming convention. If the subtype is Graphical, select Enable Multidimensional Reporting option if you want to make the view available for reporting purposes.
Note
If you do not enable multidimensional reporting, you can create a calculation view without any measure. In this case it works like a attribute view and is not available for reporting. Also, when this property is disabled, the input to the Semantics node is via projection view. If the property is enabled, the input to the Semantics node is via aggregation view. You can also change the value of this property in the Properties panel. 4. Choose Finish.
Tip
For more information about projects, repository workspaces, and sharing of projects, see Using SAP HANA Projects [page 48]. The view editor opens. Based on the view the Scenario panel of the editor consist of the following nodes: In case of an attribute view - two nodes, Data Foundation and Semantics. The Data Foundation node represents the tables used for defining the output structure of the view. The Semantics node represents the output structure of the view, that is, the dimension. In the Details panel you define the relationship between data sources and output elements. In case of an analytic view - three nodes Data Foundation - represents the tables used for defining the fact table of the view. Logical Join - represents the relationship between the selected table fields (fact table) and attribute views that is, used to create the star schema. Semantics - represents the output structure of the view.
In case of a graphical calculation view - Semantics node with a default Aggregation or Projection node, based on the selection of Enable Multi Dimensional Reporting checkbox. In case of a Script based calculation view - Semantics node with the default SQL Script node.
PUBLIC
183
5.2.3
Attribute Views
Attribute views are used to model an entity based on the relationships between attribute data contained in multiple source tables. For example, customer ID is the attribute data that describes measures (that is, who purchased a product). However, customer ID has much more depth to it when joined with other attribute data that further describes the customer (customer address, customer relationship, customer status, customer hierarchy, and so on). You create an attribute view to locate the attribute data and to define the relationships between the various tables to model how customer attribute data, for example, will be used to address business needs. You can model the following elements within an attribute view: Columns Calculated Columns
Note
In the Semantics node, you can classify the columns as attributes and build calculated columns of attribute type. Hierarchies
Note
For more information about the attributes and hierarchies mentioned above, see sections Attributes and Measures, and Hierarchies. You can choose to further fine-tune the behavior of the attributes of an attribute view by setting the properties as follows: Filters to restrict values that are selected when using the attribute view. Attributes can be defined as Hidden so that they can be used in processes but are not visible to end users. Attributes can be defined as key attributes and used when joining multiple tables. The Drill Down Enabled property can be used to indicate if an attribute is available for further drill down when consumed.
Attribute views can later be joined to tables that contain measures within the definition of an analytic view or a calculation view to create virtual star schema on the SAP HANA data.
5.2.4
Creating Attribute Views
You can create a view that is used to model descriptive attribute data by using attributes, that is data that does not contain measures. Attribute views are used to define joins between tables and to select a subset or all of the table's columns and rows.
184
Prerequisites
You have imported T009 and T009B tables for creating an attribute view whose type is Time.
Procedure
1. Define Output Structure a) Add the tables that you want to use in any of the following ways: Drag the required tables present in the Catalog to the Data Foundation node. Select the Data Foundation node in the Scenario panel, and in the context menu of the Details panel, choose Add... and search for the object to add.
Note
You can choose to add the same table again in Data Foundation using table aliases in the editor. For example, consider a table containing supplier and buyer information with postal code, and another table containing the link from postal code to region and country. Now, you want to join this geography table two time to the buyer and the supplier.
Restriction
It is not allowed to add column views to the Data Foundation. b) If you want to query data from more than one table, in the Details panel context menu, choose Create Join, and enter the required details. You can also join two tables by dragging and dropping the join from the column of one table to a column in another table . After creating the join, you can edit its properties, such as join type and cardinality, in the Properties view. You can choose to create Text Join between table fields in order to get language-specific data You have a product table that contains product IDs without descriptions and you have a text table for products that contains language-specific descriptions for each product. You can create a text join between the two tables to get the language-specific details. In a text join, the right table should be the text table and it is mandatory to specify the Language Column.
Tip
You can set the cardinality of the join as required. By default, the cardinality of the join is empty. The empty cardinality can be specified if you are not sure about the right cardinality. If you specify the empty cardinality, the system will determine the the cardinality during the join evaluation phase.
Caution
Selecting the incorrect cardinality can lead to erroneous data and memory issues. c) Add the table columns to the output structure that is, the Semantics node that you want to use to define attribute data. You can define the attribute data by doing one of the following:
PUBLIC
185
Select the toggle button on the left of the table field Right-click the table field, and choose Add to Output.
d) If you want to specify a filter condition based on which system must display data for a table field in the output do the following: 1. 2. 2. Right-click the table field, and choose Apply Filter. Select the required operator, and enter filter values.
All the table fields that you have added to the output are automatically mapped as attributes. Define Key Attributes a) Select the Semantics node. b) In the Attributes tab page of the Column panel, select the required attribute and select the Type as Key Attribute.
Remember
If there is more than one key attribute, all key attributes of the attribute view must point to the same table in the data foundation. The central table of the attribute view is the one to which all the key attributes point.
Note
In case of auto-generated time attribute views, the attributes and key attributes are automatically assigned.
Tip
You can choose to hide the attributes that are not required for client consumption by assigning value true to the property Hidden in the Properties pane. The attributes marked as hidden are not available for consumers or higher level views that are build the on top of the attribute view. For existing models (before SPS06), if the hidden attribute is already used, you can either unhide the element or remove the references. 3. Optional Step: Create Calculated Columns a) In the Output of Data Foundation panel, right-click Calculated Columns. b) In the context menu, choose New. c) Enter a name and description (label) for the calculated column. d) Select a data type for the calculated column. e) Enter length and scale for the calculated column if required by the data type. f) In the Expression Editor enter the expression. For example, you can write a formula such as, if("PRODUCT" = 'ABC', "DISCOUNT" * 0.10, "DISCOUNT"). This means if attribute PRODUCT equals the string ABC then DISCOUNT equals to DISCOUNT multiplied by 0.10 should be returned. Otherwise the original value of attribute DISCOUNT should be used.
Note
The expression can also be assembled by dragging and dropping the expression elements from the menus below the editor window.
186
PUBLIC
g) Choose OK. 4. Optional Step: To filter and view the table data in the modeled view, which is relevant to a specific client as specified in the table fields, such as, MANDT or CLIENT, at run-time perform the following: 1. Select the Semantics node, in the Properties panel edit the Default Client property.
Note
The default value for the property is the one that is specified as a preference. At run-time, if the property is set to Dynamic then, the value set for the Session Client property is used to filter table data. The Session Client property is set while creating a user. 5. Activate the view using one of the following options: If you are in the Modeler perspective, do the following as required: Save and Activate - to activate the current view and redeploy the affected objects if an active version of the affected object exists. Otherwise only current view gets activated. Save and Activate All - to activate the current view along with the required and affected objects.
Note
You can also activate the current view by selecting the view in the SAP HANA Systems view and choosing Activate in the context menu. The activation triggers validation check for both the client side and the server side rules. If the object does not meet any validation check, the object activation fails. If you are in the SAP HANA Development perspective, do the following: 1. 2. In the Project Explorer view, select the required object. In the context menu, select Team Activate .
Note
The activation triggers the validation check only for the server side rules. Hence, if there are any errors on the client side, they are skipped and the object activation goes through if no error found at the server side.
Results
Restriction
The behavior of attribute views with the new editor is as follows: When an object (a table of an attribute view) is removed and added again in an attribute view in order to reflect the recently modified columns with its data type, it reflects the previous state of the columns. To overcome this issue, you can close and open the editor, and then add the modified object. For more information, see SAP Note 1783668.
Related Information Creating Level Hierarchies [page 219]
PUBLIC
187
You create hierarchies to arrange view attributes that enhances data analysis by displaying attributes according to their defined hierarchical relationships.A level hierarchy is rigid in nature, and the root and the child nodes can only be accessed in a defined order. Activating Objects [page 211] You activate objects available in your workspace to expose the objects for reporting and analysis. Generating Time Data [page 188] For modeling a business scenario that requires time dimension, you can populate time data in the default timerelated tables present in _SYS_BI schema, for example while creating time attribute views. You can choose to generate the time data for a given time span based on your requirements such as, calendar type and granularity. Description Mapping [page 214] Description mapping helps you to associate an attribute with another attribute, which describes it in detail. For example, when reporting via Label Column , you can associate Region_ID with Region_Text. Creating Parent-Child Hierarchies [page 221] A parent-child hierarchy is defined using a parent attribute that determines the relationship between the view attributes. A parent attribute describes a self-referencing relationship, or self-join, within the main table.
5.2.4.1
Generating Time Data
For modeling a business scenario that requires time dimension, you can populate time data in the default timerelated tables present in _SYS_BI schema, for example while creating time attribute views. You can choose to generate the time data for a given time span based on your requirements such as, calendar type and granularity.
Context
If you model a time attribute view without generating time data andyou use the data preview, then an empty view is shown. The time range for which you can generate the time data for the selected granularity is mentioned in the table below: Granularity
Seconds Minutes Hour Day Week Month Year
Range
<= 5 years <= 15 years <= 30 years <= 50 years <= 50 years <= 50 years <= 50 years
Note
If you populate the data before modeling time attribute views, you can use the Value Help from the respective time tables.
188
Procedure
1. 2. In the Quick Launch tab page, choose Generate Time Data. If your financial year is same as he calendar year,for example, January to December, chooseGregorianin the Calendar Type dropdown . a) Enter the period for which you want to generate time data. b) Select the required granularity
Note
If the selected granularity is Week or Month, specify the First day of the week. c) Choose Generate. The system populates the generated time data in M_TIME_DIMENSION_YEAR, M_TIME_DIMENSION_MONTH, M_TIME_DIMENSION_WEEK, M_TIME_DIMENSION tables in _SYS_BI schema. 3. If your financial year is not the same asthecalendar year, for example, March to April, select Fiscalin the Calendar Type dropdown . a) Enter the period for which you want to generate the time data. b) Select the Variant Schema where the tables that contain variant data are maintained.
Note
Tables T009 and T009B contain variant information. c) Select the required variant that specifies the number of periods, along with their start and end dates, according to your use case. d) Choose Generate. The system populates the generated time data in the M_FISCAL_CALENDAR table, which is located in the _SYS_BI schema.
5.2.5
Analytic Views
Analytic views are used to model data that includes measures. For example, an operational data mart representing sales order history would include measures for quantity, price, and so on. The data foundation of an analytic view can contain multiple tables. However, measures that are selected for inclusion in an analytic view must originate from only one of these tables (for business requirements that include measure sourced from multiple source tables, see calculation view ). Analytic views can be simply a combination of tables that contain both attribute data and measure data. For example, a report requiring the following: <Customer_ID Order_Number Product_ID Quantity_Ordered Quantity_Shipped>
PUBLIC
189
Optionally, attribute views can also be included in the analytic view definition. In this way, you can achieve additional depth of attribute data. The analytic view inherits the definitions of any attribute views that are included in the definition. For example: <Customer_ID/Customer_Name Order_Number Product_ID/Product_Name/Product_Hierarchy Quantity_Ordered Quantity_Shipped> You can model the following elements within an analytic view: Columns Calculated Columns Restricted Columns
Remember
In the Semantics node, you can classify columns and calculated columns as type attributes and measures. The attributes you define in an analytic view are Local to that view. However, attributes coming from attribute views in an analytic view are Shared attributes. For more information about the attributes and measures mentioned above, see section Attributes and Measures. Variables Input parameters
Note
For more information about the variables and input parameters mentioned above, see sections Assigning Variables and Creating Input Parameters. You can choose to further fine-tune the behavior of the attributes and measures of an analytic view by setting the properties as follows: Filters to restrict values that are selected when using the analytic view. Attributes can be defined as Hidden so that they are able to be used in processes but are not viewable to end users. Attributes can be defined as key attribute and used when joining multiple tables. The Drill Down Enabled property can be used to indicate if an attribute is available for further drill down when consumed. Aggregation type on measures Currency and Unit of Measure parameters (you can set the Measure Type property of a measure, and also in Calculated Column creation dialog, associate a measure with currency and unit of measure)
Tip
If there is a name conflict that is, more than one element having the same name among the local and shared attributes, calculated columns, restricted columns, and measures of an analytic view, the activation of the view does not go through. You can resolve such conflict using the aliases. Aliases must also have unique names. You can assign an alias to the required element in the Column view of the Semantics node by editing its name inline. Hereinafter, the element is referred by its alias. If two or more shared columns have a name conflict, during save the aliases for the conflicting name columns are proposed. You can choose to overwrite the proposed names. In case of old models, if you find any error while opening the object due to aliasing that was caused due to swapping of column names with the alias names, use the Quick Fix. To use the Quick Fix, select the error
190
message that is, the problem in the Problems view, and choose Quick Fix in the context menu. This resolves the swapping issue by assigning right names to the column and alias. You can choose to hide the attributes and measures that are not required for client consumption by assigning value true to the property Hidden in the Properties pane, or selecting the Hidden checkbox in the Column view. The attributes or measures marked as hidden are not available for input parameters, variables, consumers or higher level views that are build on top of the analytic view. For old models (before SPS06), if the hidden attribute is already used, you can either unhide the element or remove the references. For an analytic view, you can set the property MultiDimensional Reporting to true or false. If the MultiDimensional Reporting property of the analytic view is set to false, the view will not be available for multidimensional reporting purposes. If the value is set to true, an additional column Aggregation is available to specify the aggregation type for measures. You can enable relational optimization for your analytic view such as, Optimize stacked SQL for example, convert SELECT a, SUM(X) FROM ( SELECT * FROM AV) GROUP BY A to SELECT A, SUM(X) FROM AV GROUP BY A by setting the property Allow Relational Optimization. Setting this property would be effective only for analytic views having complex calculations such that deployment of analytic view generates catalog calculation view on top of the generated catalog OLAP view.
Caution
In this case, if this flag is set counters and SELECT COUNT may deliver wrong results
5.2.6
Creating Analytic Views
Analytic views are typically defined on a fact table that contains transactional data (as measures). You can define analytic views in a single or joined table, create a selection of measures, add attributes and join attribute views.
Context
Analytic views can contain two types of columns: attributes and measures. Measures are simple, calculated or restricted. If analytic views are used in SQL statements, then the measures have to be aggregated. For example, using the SQL functions SUM(<column name>), MIN(<column name>), or MAX(<column name>). Normal columns can be handled as regular attributes and do not need to be aggregated.
PUBLIC
191
Procedure
1. Define Output Structure a) Add the tables that you want to use in any of the following ways: Drag the required tables present in the Catalog to the Data Foundation node. Select the Data Foundation node in the Scenario panel, and in the context menu of the Details panel, choose Add ... and search for the required object.
Note
You can add the same table in the Data Foundation by using table aliases in the editor; for example, consider a table containing supplier and buyer information with postal code, and another table containing the link from postal code to region and country. Now, you want to join this geography table two time to the buyer and the supplier. If your analytic view has more than one table, you need to specify which table is the central table (fact table) from which the measures will be derived. You can specify the central table by selecting a value in the Central Entity property of the Data Foundation node.
Restriction
You cannot add column views to the Data Foundation of an analytic view. However, you can add column views to a calculation view. b) To query data from more than one table, go to the Details panel context menu, choose Create Join, and enter the required details. You can also join two tables by dragging and dropping the join from the column of one table to a column in another table . After creating the join, you can edit its properties, such as join type and cardinality, in the Properties view. You can choose to create Text Join between table fields in order to get language-specific data You have a product table that contains product IDs without descriptions and you have a text table for products that contains language-specific descriptions for each product. You can create a text join between the two tables to get the language-specific details. In a text join, the right table should be the text table and it is mandatory to specify the Language Column.
Tip
You can set the cardinality of the join as required. By default, the cardinality of the join is empty. The empty cardinality can be specified if you are not sure about the right cardinality. If you specify the empty cardinality, the system will determine the the cardinality during the join evaluation phase.
Caution
Selecting the incorrect cardinality can lead to erroneous data and memory issues. c) Perform one of following steps to add the table columns to the output structure (Semantics node) that you want to use to define the facts. Select the toggle button on the left of the table field. Right-click the table field, and choose Add to Output.
192
PUBLIC
d) To specify a filter condition based on which system must display data for a table field in the output,: Only display revenue for companies that fulfill the filter conditions you have specified. 1. 2. Right-click the table field, and choose Apply Filter. Select the required operator, and enter the filter values.
The table fields selected above form the fact table. e) To create a star schema, that is linking the fact table with the descriptive data (attribute views: 1. Perform one of following steps to add the required attribute views in the Logical Join node: 2. Drag the required attribute views present in the Content node to the Logical Join node. Select the Logical Join node in the Scenario panel, and choose Add to add the attribute views.
Create joins between the views and the fact table.
Note
In the Logical Join, you can create a temporal join between the date field of the fact table to an interval (to and from) field of the attribute view. The temporal join has to start from the fact table such that the single column must be in the fact table, and the to and from columns must be in the table that is directly joined to the fact table. The join type must be a referential join. The supported data types are timestamp, date, and integer.
Restriction
While creating joins, you must ensure that a table does not appear twice in any join path, that is r a self join is not supported. A join path is the set of joins that links the fact table to other tables. While creating joins between analytic view and attribute view:. . 2. The same table cannot be used in the join path of analytic view and attribute view The table of the attribute view which is linked to the fact table should not have an alias table
Create Calculated Column (Optional) a) In the Output of Logical Join panel, right-click on Calculated Columns and in the context menu, choose New. b) Enter a name and description (label) for the calculated column.Select a data type, and enter the length and scale for the calculated column. c) Select the Column Type to determine whether it is a calculated attribute or a calculated measure. d) If you select Calculate Before Aggregation, select the aggregation type.
Note
If you select Calculate Before Aggregation, the calculation happens as per the expression specified and then the results are aggregated as SUM, MIN, MAX or COUNT. If Calculate Before Aggregation is not selected, the data is not aggregated but it gets calculated as per calculation expression (formula), and the aggregation is shown as FORMULA. If the aggregation is not set, then it will be considered as an attribute. You should selecting Calculate Before Aggregation only when required as it may decrease the performance. e) In the Expression Editor enter the expression. if("PRODUCT" = 'ABC, "DISCOUNT" * 0.10, "DISCOUNT") which is equivalent to, if attribute PRODUCT equals the string ABC then DISCOUNT equals to DISCOUNT multiplied by 0.10 should be returned. Otherwise the original value of attribute DISCOUNT should be used.
PUBLIC
193
Note
The expression can also be assembled by dragging and dropping the expression elements from the menus below the editor window. f) To associate the calculated column with the currency and unit of measuring quantity, select the Advanced view and select the required Type. Choose OK.
Remember
Calculated Columns can be created only at the Logical Join level and not at the Data Foundation level.
Tip
You can also create a calculated column based on the existing one by copying it and making the required changes. The copy paste option is available from the context menu of the calculated column. You can also use the CTRL + C and CTRL + V keyboard shortcuts. The copy paste functionality works only in the same editor, that is, if you copy a calculated column in one view editor you cannot paste it in another view editor. Also, if you copy a calculated column in one editor and go to another view editor and again copy another object, the paste option in the previous editor is not available. The copy paste functionality for calculated columns only works in the Output panel. 3. Optional Step: Create Restricted Columns You can create restricted columns if you want to filter the value for an output field based on the user-defined rules. For example, you can choose to restrict the value for the Revenue column only for Region = APJ, and Year = 2012. a) In the Output panel of the Logical Join, right-click Restricted Columns, and choose New. b) Enter a name and description for the restricted column. c) From the Column dropdown list, select the column for which you want to apply a restriction.
Caution
The column for which you apply a restriction must be defined as measure in the semantics node otherwise the validation will fail. d) Choose Add Restriction. e) In the Parameter field, select the column that you want to create a restriction for, then select the operator and value. f) Choose OK.
Note
For a restricted column the aggregation type of the base column is applied.
Tip
You can also create a restricted column based on the existing one by copying it and making the required changes. The copy paste option is available from the context menu of the calculated column. You can also use the CTRL + C and CTRL + V keyboard shortcuts. The copy paste functionality works only in the same editor, that is, if you copy a restricted column in one view editor you cannot paste it in another view editor. Also, if you copy a restricted column in one editor and go to another view editor and again copy another
194
object, the paste option in the previous editor is not available. The copy paste functionality for restricted columns only works in the Output panel 4. Define Attributes and Measures a) Select the Semantics node. b) In the Column panel, select the Local tab page, and change the type as attributes and measures.
Note
The Shared tab page shows the attributes of the used attribute views. While generating the column views, the joined local attribute name is ignored and the shared attribute name is considered, therefore the joined local attribute is not shown on the Semantics node.
Note
You can change the type of a measure and perform currency conversion by selecting it in the Local tab page and changing the Measure Type property in the properties panel. 5. Optional Step: You can filter and view the table data in the modeled view for a specific client as specified in the table fields, such as MANDT or CLIENT, by doing the following: 1. Select the Semantics node, in the Properties panel, edit the Default Client property.
Note
The default value for the property is the one that is specified as a preference. If the property is set to Dynamic, at run-time the value set for the Session Client property is considered to filter table data. The Session Client property is set while creating a user. 6. Optional Step: Assign Variable You assign variables to an attribute of the view at design time to filter data based on the values you provide for the variable. The variable values are interpreted as WHERE clause of the SQL statement by the clients/ consumers like Data Preview, MDX, Advanced Analysis for Office or BO Explorer. At runtime, you can provide different values to the variable to view the corresponding set of attribute data. 7. 8. If you want to parametrize currency conversion, calculated columns and Data Foundation filters, create input parameters. Activate the view using one of the following options: If you are in the Modeler perspective, do the following as required: Save and Activate - to activate the current view and redeploy the affected objects if an active version of the affected object exists. Otherwise only current view gets activated. Save and Activate All - to activate the current view along with the required and affected objects.
Note
You can also activate the current view by selecting the view in the SAP HANA Systems view and choosing Activate in the context menu. The activation triggers validation check for both the client side and the server side rules. If the object does not meet any validation check, the object activation fails. If you are in the SAP HANA Development perspective, do the following: 1. In the Project Explorer view, select the required object.
PUBLIC
195
2.
In the context menu, select
Team
Activate .
Note
The activation triggers the validation check only for the server side rules. Hence, if there are any errors on the client side, they are skipped and the object activation goes through if no error found at the server side.
Note
If an active version of the affected objects exist, activating the current view redeploys the affected objects. In the Modeler perspective, even if the affected object redeployment fails, the current view activation might go through. However, in the SAP HANA Development perspective, if any of the affected objects redeployment fails, the current view activation also fails.
Note Restriction
The behavior of analytic views with the new editor is as follows: When an object (a table of an attribute view) is removed and added again in an attribute view in order to reflect the recently modified columns with its data type, it reflects the previous state of the columns. To overcome this issue, you can close and open the editor, and then add the modified object. For more information, see SAP Note 1783668.
Related Information Using Currency and Unit of Measure [page 228] Activating Objects [page 211] You activate objects available in your workspace to expose the objects for reporting and analysis. Creating Input Parameters [page 223] You use input parameters to define internal parameterization of the view. Input parameters used in the views enables you to obtain a desired functionality when the view is executed. Using Temporal Joins [page 197] A temporal join indicates the time interval mapping between the master data and the transaction data for which you want to fetch the records. Description Mapping [page 214] Description mapping helps you to associate an attribute with another attribute, which describes it in detail. For example, when reporting via Label Column , you can associate Region_ID with Region_Text. Display Folders [page 218] If your analytic view and calculation view has multiple measures and you want to organize them, for, example, segregate the planned measures with the actual measures, you can group the related measures in folders. These folders are called the display folders.
196
5.2.6.1
Using Temporal Joins
A temporal join indicates the time interval mapping between the master data and the transaction data for which you want to fetch the records.
Context
You create a temporal join using the temporal column that specifies the time interval with the start and the end date. The result set is fetched based on the time interval mapped using the temporal column. A record is only included in the results set if the time interval lies within the valid time interval. A time interval is assigned to each record in the results set. The records are valid for the duration of the interval to which they are assigned. You use temporal conditions to indicate whether to include or exclude the value of the FROM and TO date fields while executing the join condition. In the logical join, you can create a temporal join between the date field of the fact table to an interval (to and from) field of the attribute view. The temporal join must start from the fact table such that the single column must be in the fact table and, the to and from columns must be in the table that is directly joined to the fact table. The join type must be Referential. The supported data types are: timestamp, date, and integer.
Procedure
1. 2. Create a referential join between the attribute of the fact table and the attribute view. In the Properties panel, select: a) The Temporal Column that indicates the single time column in the fact table. b) The From Column and the To Column to specify the time interval from the attribute view. c) The Temporal Condition which would be considered while executing the join.
Example
Consider an attribute view Product that contains master data about Products with attributes like, ProductID, Validity_Date_From, Validity_Date_To, and so on. Similarly, consider an analytic view Sales that contains transactional data corresponding to the products sales with attributes, ProductID, Date, Revenue. Now, to analyze sales data for products you can create a join between the two views using ProductID. But to fetch data for a particular time period you need to assign temporal properties to the join. The temporal column in our example would be Date field in the Analytic view, and the From date and To date would come from the Validity_Date_From, and Validity_Date_To of the attribute view.
PUBLIC
197
5.2.7
Calculation Views
A calculation view is used to define more advanced slices on the data in SAP HANA database. Calculation views can be simple and mirror the functionality found in both attribute views and analytic views. However, they are typically used when the business use case requires advanced logic that is not covered in the previous types of information views. For example, calculation views can have layers of calculation logic, can include measures sourced from multiple source tables, can include advanced SQL logic, and so on. The data foundation of the calculation view can include any combination of tables, column views, attribute views and analytic views. You can create joins, unions, projections, and aggregation levels on the sources. You can model the following elements within a calculation view: Attributes Measures Calculated measures Counters Hierarchies (created outside of the attribute view)
Note
For more information about the attributes, measures, counters, and hierarchies mentioned above, see sections Attributes and Measures, and Hierarchies. Variables Input parameters
Note
For more information about the variables and input parameters mentioned above, see sections AssigningVariables and Creating Input Parameters. Calculation views can include measures and be used for multi-dimensional reporting or can contain no measures and used for list-type of reporting. Calculation views can either be created using a graphical editor or using a SQL Console . These various options provide maximum flexibility for the most complex and comprehensive business requirements.
5.2.8
Creating a Graphical Calculation View
You can create a calculation view to depict a complex business scenario that has layers of calculation logic and include measures sourced from multiple source tables using the graphical modeling features of the SAP HANA Modeler.
198
PUBLIC
Context
You can set the calculation view property Multidimensional Reporting to true or false based on the following requirement: Set to true - if you want to define a calculation view that is visible in the reporting tools. You just must define at least one measure and the default node is Aggregation. Set to false - if you want to define a simple SQL like calculation view, which, for example, is used to fill simple list user interfaces where recurring attribute values are not a problem, but are desired. To define this type of view, you do not define any measure. If you to define a view like this, its behaviour is as follows: The output node does not offer any measures (or hierarchies), just attributes which can be numerical data types The calculation view is not available for reporting The calculation view is only consumable via SQL The default node is Projection
For the Aggregation node, at runtime, the measures are automatically aggregated on the level defined by the group, by clause. In this case, the output node is deployed as an aggregation node into the run-time model that is created during deployment. Moreover, the model information is written into the BI metadata consumption tables that is, made available to the BI clients of SAP HANA for reporting. You can switch the execution of the calculation view to the SQL Engine rather that the Column Engine for better performance by selecting the SQL Engine value in the Execute In property. When this property is set to SQL Engine, the calculation engine generates SQL code for each node at runtime and combines them into one big SQL statement which is then passed to the SQL interface. This might be beneficial since the SQL interface also involves standard SQL optimizer which implements a lot more optimization rules than the Calculation Engine. For example, the most important rule is join ordering determination. This option is only efficient if every node is translated so that one big SQL statement can be generated. To gain optimal SQL generation, the following rules should be followed: The calculation view should onlycontain tables and a calculation view as data source. If a calculation view is added, the mentioned rules must be followed for it as well. Explicitly do not add any Analytic View, Attribute View, or Scripted Calculation View. This might break any optimization. Only use supported operations: projection, union, join, and aggregation. Do not use special column store functions in filter or calculated attribute expressions because they might not be convertible. For example, the functions date() and time() only work on the column store data types and cannot be converted. The NULL handling is different in the calculation and the SQL engine. In the calculation engine, the expression 2 + null results in 2, whereas in SQL engine it results in null. So if you switch on the SQL engine execution you might get different results than before. We suggest using the function sqladd instead. This behaves as the + in SQL. If a currency conversion or counter measure needs to be defined, it has to be defined at the output node of the main scenario. If a currency conversion or counter measure is modeled into an included scenario, SQL optimization would exclude that part because these measures can be handled more efficiently in the Calculation Engine.
You can further fine tune the behavior of the calculation view by: Creating variables, and bind them to attributes for filtering data. The values you provide for the variables at runtime determine which data records are selected for consumption. Creating input parameters to parameterize the view execution.
PUBLIC
199
Creating hierarchies to arrange view attributes that helps you to visualize and analyze the data in a hierarchical fashion. Grouping the related measures in display folders. Hiding attributes and measures that are not required for client consumption by assigning value true to the property Hidden in the Properties pane. The attributes or measures marked as hidden are not available for joins, input parameters, variables, consumers, and other views that are build on the top of this view. For existing models (before SPS06), if the hidden attribute is already used, you can either unhide the element or remove the references.
Setting the cardinality of a join as required from the join properties. By default, the cardinality of a join is empty. The empty cardinality can be specified in cases when you are not sure about the right cardinality. If you specify the empty cardinality, system during the join evaluation phase diagnose the best suited cardinality and execute the join. Wrong selection of cardinality can lead to erroneous data and out of memory issues.
Procedure
1. Choose one of the following options from the Tools Palette: View Node
Union
Description
Used to combine the result set of two or more data sources. For example, to show the names of all the employees of a store which has different branches each maintaining its own employee records table. Used to query data from two or more data sources, based on a specified condition. For example, to retrieve the customers details with location based on the postal code present in two tables Customer and Geography where, Customer table has columns - Customer ID, Customer Name,Postal Code, and Geography having columns Postal Code, Region, Country. Used to filter or create a subset of the required columns of a table or view for creating the model. For example, selecting the employee name and sales quantity from a table consisting of many more columns. Used to summarize data of a group of rows by calculating values in a column. For example, to retrieve total sales of a product in a month. The supported aggregation types are sum, min, and max.
Join
Projection
Aggregation
Note
The input for union, join, projection, and aggregation view nodes can consist of data sources, union, join, projection, or aggregation views. You can only have one source of input for aggregation and projection view nodes, and two inputs for a join. You can choose to create filters on projection and aggregation view node attributes.
200
2.
To add the data sources to the selected node like, join, select data source from the SAP HANA systems view to the join node. a) Map the input to the selected option. Mapping attributes
next to the join node or drag and drop the
To map attributes in a union view, drag and drop the required columns from Source to Target. You can also modify the attribute mapping. For more information, see Managing Column Mappings [page 205]
Tip
To create a system generated mapping, choose Auto Map By Name. In case of a join view, join the columns of the data sources in the Details view.
Note
The output of a union view node is the attributes that you added to the Target. The output of a join view node is the joined attributes. However, to add additional attributes to the view's output, from the context menu, choose Add to Output. To add attributes of projection or aggregation view node to its output, choose Add to Output from the context menu.
The output of the union, join, aggregation and projection view nodes is stored under the Column node in the Output panel.
Note
You can choose to rename the attributes, calculated attributes, measures, and calculated measures of the view using the Rename button in the Output panel toolbar. However, renaming a field can impact other objects that reuse the field as the new name is not reflected in the other objects. 3. To add attributes and measures to the calculation view output, perform the following substeps: a) In the Scenario panel, choose the Semantics node. b) In the Column panel of the Local tab page, select the columns and change the type as Attribute and Measure.
Note
If the MultiDimensional Reporting property of the calculation view is set to true, it is mandatory to specify at least one column as measure; otherwise, the view activation fails. Also, if the value is set to true, an additional column called Aggregation is available to specify the aggregation type for measures. You can change the type of a measure and perform a currency conversion by selecting it in the Local tab page and changing the Measure Type property in the properties panel. You can choose to rename the attributes, calculated attributes, measures, and calculated measures of the view using the Rename button in the Output panel toolbar. However, renaming a field can impact other objects that reuse the field as the new name is not reflected in the other objects.
4.
Create counters to obtain the number of distinct values of an attribute (optional)
PUBLIC
201
a) Select the default aggregation node. b) In the Output pane, right-click Calculated Columns. c) From the context menu, choose New Counter. Enter a name and description (label). d) To hide the counter during data preview, select the Hidden checkbox. e) To add attributes in the Counters panel, choose Add and choose OK.
Remember
You can only create counters on the default aggregation node. 5. Activate the view. If you are in the Modeler perspective, choose one of the following: Save and Activate - to activate the current view and redeploy the affected objects if an active version of the affected object exists. Otherwise, only the current view is activated. Save and Activate All - to activate the current view along with the required and affected objects.
Note
You can also activate the current view by selecting the view in the SAP HANA Systems view and choosing Activate in the context menu. The activation triggers validation check for both the client side and the server side rules. If the object does not meet any validation check, the object activation fails. If you are in the SAP HANA Development perspective, choose one of the following: 1. 2. In the Project Explorer view, select the required object. In the context menu, select Team Activate .
Note
The activation only triggers the validation check for the server side rules. If there are any errors on the client side, they are skipped, and the object activation goes through if no error is found on the server side.
Note Note
1. For an active calculation view, you can preview the data of an intermediate node in a calculation view, which helps to debug each level of a complex calculation scenario having join, union, aggregation, projection, and output nodes. The data you preview for a node is for the active version of the calculation view. If no active version for the object exists then you need to activate the object first. You can choose the Data Preview option from the context menu of a node. You can find the details of the functions available on content assist that is, by pressing Ctrl + Space in the SQL Console while writing procedures in the SAP HANA SQLScript Reference.
2.
Related Information Assigning Variables [page 226] You can assign variables to a filter at design time for obtaining data based on the values you provide for the variable. At runtime, you can provide different values to the variable to view the corresponding set of attribute data.
202
PUBLIC
Creating Input Parameters [page 223] You use input parameters to define internal parameterization of the view. Input parameters used in the views enables you to obtain a desired functionality when the view is executed. Display Folders [page 218] If your analytic view and calculation view has multiple measures and you want to organize them, for, example, segregate the planned measures with the actual measures, you can group the related measures in folders. These folders are called the display folders. Description Mapping [page 214] Description mapping helps you to associate an attribute with another attribute, which describes it in detail. For example, when reporting via Label Column , you can associate Region_ID with Region_Text. Creating Level Hierarchies [page 219] You create hierarchies to arrange view attributes that enhances data analysis by displaying attributes according to their defined hierarchical relationships.A level hierarchy is rigid in nature, and the root and the child nodes can only be accessed in a defined order. Creating Parent-Child Hierarchies [page 221] A parent-child hierarchy is defined using a parent attribute that determines the relationship between the view attributes. A parent attribute describes a self-referencing relationship, or self-join, within the main table. Applying Filter on Aggregation and Projection Node [page 208] Creating Calculated Columns [page 203] You can create calculated columns to perform some calculation based on the existing view columns. Mapping Input Parameters [page 204] You can map the input parameters in the underlying data sources (analytic views and calculation views) of the calculation view to the calculation view parameters. You can also map many data source parameters to one calculation view input parameter and perform a one-to-one mapping of the data source parameters to the calculation view parameters.
5.2.8.1
Creating Calculated Columns
You can create calculated columns to perform some calculation based on the existing view columns.
Procedure
1. 2. 3. 4. Right-click Calculated Columns node and choose New. Enter a name and description (label). Select a data type, and enter length and scale for the calculated column. Select the Column Type to determine whether it is a calculated attribute or a calculated measure. In the Expression Editor enter the expression. You can write a formula: if("PRODUCT" = 'ABC, "DISCOUNT" * 0.10, "DISCOUNT") which is equivalent to, if attribute PRODUCT equals the string ABC then DISCOUNT equals to DISCOUNT multiplied by 0.10 should be returned. Otherwise the original value of attribute DISCOUNT should be used.
PUBLIC
203
Note
The expression can also be assembled by dragging and dropping the expression elements from the menus below the editor window. 5. 6. Go to the Advanced tab page and select the required Type if you want to associate the calculated measure with currency and unit of measuring quantity. Choose OK.
5.2.8.2
Mapping Input Parameters
You can map the input parameters in the underlying data sources (analytic views and calculation views) of the calculation view to the calculation view parameters. You can also map many data source parameters to one calculation view input parameter and perform a one-to-one mapping of the data source parameters to the calculation view parameters.
Procedure
1. To invoke the dialog from the default aggregation or projection node: a) Select the default aggregation or projection node. b) Right-click Input Parameter in the Output view. c) In the context menu, choose Manage Mappings. 2. To invoke the dialog from the Semantics node: a) Select the Semantics node. b) In the Variables/Input Parameters view, choose 3. .
In the Map Input Parameters dialog, map the data source input parameters with the calculation view parameters.
Note
You can choose the Auto Map by Name option to automatically create the input parameters corresponding to the source and perform a 1:1 mapping. You can also select a source input parameter and use the following context menu options: 4. Copy and Map 1:1 - to create the same input parameter for the calculation view as for the source, and create a 1:1 mapping between them. Map By Name - to map the source input parameter with the calculation view input parameter having the same name. Remove Mapping - to delete the mapping between the source and calculation view input parameter.
Select Create Constant to create a constant at the target calculation view.
204
Note
You can change the constant name by double clicking it.
5.2.8.3
Managing Column Mappings
You can map the source columns to the target columns if there are a large number of attributes, or to assign a constant value to the target column in a union view.
Context
If there is no source column mapped to a target column, a datatype needs to be specified for that target column.
Note
In a union view, a constant column is created if there are any target columns or output attributes for which there are no mappings to the source columns. The default value for the constant column is NULL.
Procedure
1. 2. 3. 4. 5. Right-click the target column in the target list. From the context menu, choose Manage Mappings. Select the required column from the Source Column dropdown list that you want to map to the selected target column. To assign a default value to the target column, enter the value in the Constant Value field. Select the required data type. Enter the length and scale as required and choose OK.
Related Information Constant Column [page 205]
5.2.8.4
Constant Column
In a union view, a Constant Column is created if there are any target or output attributes for which there are no mappings to the source attributes. The default value for the constant column is NULL.
Note
The target attribute is mapped to all the sources.
PUBLIC
205
For example, you have two tables with similar structures, Actual Sales and Planned Sales, corresponding to the sales of products. You want to see the combined data in a single view, but differentiate between the data from the two tables for comparison. To do so, you can create a union view between the two tables and have a constant column indicating constant values like A & P, as shown below: Actual Sales Sales
5000 2000
Product
A1 B1
Planned Sales Sales

3000 6000
Product
A1 B1
The result of this query can be as follows: Actual Planned Indicator

A P A P
Sales
5000 3000 2000 6000
Product
A1 A1 B1 B1
5.2.8.5
Using Dynamic Joins
In a dynamic join, the elements of a join condition between two data sources are defined dynamically based on the fields requested by the client query. It is used to improve the performance by reducing the less number of records to be processed by the join node. For example, consider two tables: Table1 and Table 2. Each table has joins between two fields: Field 1 and Field 2. If a client requests only one of the two fields, then the tables are joined only on the requested field . In a dynamic join, at lteast one of the join elements must be requested by the client query; otherwise, it results in a query runtime error. This behavior of dynamic join is different from the standard (non-dynamic) join. In the standard join, the join condition is static, which means that the join-condition does not change depending on the client query. Whereas in the case of a dynamic join, the join-condition changes based on the query. The dynamic join is only applicable for multi-column join scenarios. Therefore, it is disabled for single column joins. The dynamic join enforces the aggregation before executing the join as opposed to a standard join where the aggregation happens after the join. This means, if a join field is not requested by the client query, its value is first aggregated and then the join condition is executed based on the requested fields.
206
Example
You want to evaluate the sales data to calculate the sales share for a product. The table shown below contains the product sales data at the region and country level. Region APJ APJ APJ APJ EUR EUR EUR EUR Country IND IND CHN CHN DE DE UK UK Product Prod1 Prod2 Prod1 Prod2 Prod1 Prod2 Prod1 Prod2 Sales 10 10 20 50 50 100 20 30
In the calculation view, the above table is joined via two aggregation nodes such that the aggregation node on the right does not contain the field Product as one of its column. Therefore, this node always delivers the total sales of a given region or country. The two aggregation nodes are joined dynamically on the fields REGION and COUNTRY. The output of the join node are REGION, COUNTRY, PRODUCT, SALES, TOT_SALES, and SALES_SHARE. When a client query on the view to evaluate the sales share at region level is submitted, the result from the dynamic join and standard join is as follows: Table 10: Dynamic Join Result REGION APJ APJ EUR EUR PRODUCT PROD1 PROD2 PROD1 PROD2 SUM(SALES) 30 60 70 130 SUM(TOT_SALES) 90 90 200 200 SUM(SALES_SHAR E) .33 .66 .35 .65
Table 11: Standard Join Result REGION APJ APJ EUR EUR PRODUCT PROD1 PROD2 PROD1 PROD2 SUM(SALES) 30 60 70 130 SUM(TOT_SALES) 90 90 200 200 SUM(SALES_SHAR E) .78 1.21 .73 1.26
The dynamic join delivers the sales share at the region level by aggregating the sales values before joining the data sets. The standard join model first calculates the sales share at the region level plus the country level
PUBLIC
207
(because the join condition contains both region and country), and then aggregates the resulting sales share after the join has been executed.
Note
You can specify if a join is dynamic by setting Dynamic Join to true or false.
5.2.8.6
Applying Filter on Aggregation and Projection Node
Context
You can apply filter on the aggregation and projection node attributes except the default aggregation and projection nodes. The filters applied on the columns are executed after the performing all the operations defined in a Projection or an Aggregation View. In particular after the aggregation. So a filter on an aggregated column has the same semantic as HAVING clause in SQL. You can use the Expression editor to define pattern-based filters in calculation views. Double-click on the expression icon match("ABC",'*abc*') the equivalent SQL is where ABC like %abc% . under the filter node of the Output panel. If you type
Procedure
1. 2. 3. 4. Right-click the required attribute. From the context menu, choose Apply Filter. Select the required operator. Enter a value and choose OK.
Note
You can edit a filter using filter expressions from the Output pane which provides more conditions that can be used in the filter including AND, OR, and NOT. For example, to retrieve the sales of a product where (revenue >= 100 AND region = India) OR (revenue >=50 AND region = Germany).
208
PUBLIC
5.2.9
Creating a Script-Based Calculation View
You can create a script-based calculation view to depict a complex calculation scenario using a sequence of SQL Script statements.
Context
You can further fine tune the behavior of the calculation view by: Creating variables, and bind them to attributes for filtering data. The values you provide for the variables at runtime determine which data records are selected for consumption. Creating input parameters and use them in the SQLScript. Creating hierarchies to arrange view attributes that helps you to visualize and analyze the data in a hierarchical fashion. Grouping the related measures in display folders.
For a calculation view you can set the MultiDimensional Reporting property to true or false as follows: Set to true - if you want to define a calculation view that is visible in the multidimensional reporting tools. Set to false - if you want to define a simple SQL like calculation view, which, for example, is used to fill simple list user interfaces where recurring attribute values are not a problem, but are desired. The view is not available for multidimensional reporting and is only consumable via SQL.
Procedure
1. In the Details panel of the Semantics node, select the required schema from the Default Schema property, for unqualified access in SQL Script.
Note
If you do not select a default schema while scripting, you need to provide fully qualified names of the objects used. 2. 3. Choose SQL Script node in the Semantics node. To define the output structure, choose Create Target from the Output panel and add the output parameters with the required data type and length.
Note
The order and data types of the output parameters should match the order and data types of the table columns, which is used in the select query. 4. 5. Write the script using SQL Script commands to fill the output structure. Activate the view using one of the following options: If you are in the Modeler perspective, choose one of the following:
PUBLIC
209
Save and Activate - to activate the current view and redeploy the affected objects if an active version of the affected object exists. Otherwise, only the current view is activated. Save and Activate All - to activate the current view along with the required and affected objects.
Note
You can also activate the current view by selecting the view in the SAP HANA Systems view and choosing Activate in the context menu. The activation triggers validation check for both the client side and the server side rules. If the object does not meet any validation check, the object activation fails. If you are in the SAP HANA Development perspective, choose one of the following: 1. 2. In the Project Explorer view, select the required object. In the context menu, select Team Activate .
Note
The activation only triggers the validation check for the server side rules. If there are any errors on the client side, they are skipped, and the object activation goes through if no error is found on the server side. You can find the details of the functions available on content assist that is, by pressing Ctrl + Space in the SQL Console while writing procedures in the SAP HANA SQLScript Reference Related Information Assigning Variables [page 226] You can assign variables to a filter at design time for obtaining data based on the values you provide for the variable. At runtime, you can provide different values to the variable to view the corresponding set of attribute data. Creating Input Parameters [page 223] You use input parameters to define internal parameterization of the view. Input parameters used in the views enables you to obtain a desired functionality when the view is executed. Display Folders [page 218] If your analytic view and calculation view has multiple measures and you want to organize them, for, example, segregate the planned measures with the actual measures, you can group the related measures in folders. These folders are called the display folders. Description Mapping [page 214] Description mapping helps you to associate an attribute with another attribute, which describes it in detail. For example, when reporting via Label Column , you can associate Region_ID with Region_Text. Creating Level Hierarchies [page 219] You create hierarchies to arrange view attributes that enhances data analysis by displaying attributes according to their defined hierarchical relationships.A level hierarchy is rigid in nature, and the root and the child nodes can only be accessed in a defined order. Creating Parent-Child Hierarchies [page 221] A parent-child hierarchy is defined using a parent attribute that determines the relationship between the view attributes. A parent attribute describes a self-referencing relationship, or self-join, within the main table.
210
PUBLIC
5.2.10 Activating Objects

You activate objects available in your workspace to expose the objects for reporting and analysis. Based on your requirements, you can do the following: Activate - Deploys the inactive objects. Redeploy - Deploys the active objects in one of the following scenarios: If your runtime object gets corrupted or deleted, and you want to create it again. In case of runtime problems during object activation, and the object status is still active.
The following activation modes are supported: Activate and ignore the inconsistencies in affected objects - To activate the selected objects even if it results in inconsistent affected objects. For example, if you choose to activate an object A that is used by B and C, and it causes inconsistencies in B and C but you can choose to go ahead with the activation of A. This is the default activation mode. Stop activation in case of inconsistencies in affected objects - To activate the selected objects only if there are no inconsistent affected objects.
Note
If even one of the selected objects fails (either during validation or during activation), the complete activation job fails and none of the selected objects is activated. Depending on where you invoke the activation, redeployment or cascade activation, the behavior is as follows: Context
Quick Launch tab page Package context menu Content context menu Editor
Activate
A dialog box appears with a preselected list of all your inactive objects. A dialog box appears with a preselected list of all your inactive objects. A dialog box appears with a preselected list of all your inactive objects. If you select Save and Activate, current object is activated and the affected objects are redeployed if an active version for the affected objects exist. If you select Save and Activate All, a dialog box appears with a preselected list of the selected object along with all the required and affected objects.
Redeploy
A dialog box appears with a list of active objects in your workspace. A dialog box appears with a list of active objects in your workspace. Not applicable Not applicable
Object context menu
A dialog box appears with a preselected list of the selected object along with all the required objects.
A redeployment job is submitted for the selected object.
Note
If an object is the only inactive object in the workspace, the activation dialog box is skipped and the activation job is submitted.
PUBLIC
211
If an object is inactive and you want to revert back to the active version, from the editor or object context menu, choose Revert To Active. In the Activate dialog, you can select the Bypass validation checkbox in order to skip validation before activation to improve the activation time. For example, if you have imported a number of objects and want to activate them without spending time on validation.
Note
During delivery unit import, full server side activation is enabled, activation of objects after import is done. In this case all the imported objects are activated (moved to active table), even if there are errors in activated or affected objects. But the objects for which activation results in error are considered as broken or inconsistent objects which means that the current runtime representation of these objects is not in sync with the active design time version. The broken objects are shown in the Navigator view with an x along side.
Note
The behavior of the activation job is as follows: The status (completed, completed with warnings, and completed with errors) of the activation job indicates whether the activation of the objects is successful or failed. In case of failure that is when the status is completed with errors, the process is rolled back. This means, even if there are individual objects successfully activated, since the activation job is rolled back, none of the objects are activated. When you open the job log, the summary list shows only those objects that are submitted for activation. It does not list all the affected objects. They are listed only in detail section.
Activation behavior in the view editor

The following table describes the availability and behavior of take over and activate options for an object from the view editor in the Modeler perspective. Scen ario Objec in Team Provider t in SAP HANA Systems view SAP HANA Systems view Description
User: User: User: U, U1,Workspa U2,Workspa Workspace: ce: WS1 ce: WS2 (default/ other workspace) 1 OBJ1 Inactive Inactive Inactive
Take Over
Activat e
Not Applic able
Allowe If an object has multiple inactive d versions, and the object version in Modeler is also inactive, for example, through delivery unit
212
Scen ario
Objec in Team Provider t
in SAP HANA Systems view
SAP HANA Systems view
Description
import or another workspace in Project Explorer, user can activate his own inactive object. After activation, the object is the scenario 2 as in the next row.
Note
If the logged-in user and the user to whom the object belongs are different, the activation is not allowed. For example, if the object is inactive in SYSTEM users workspace and MB user opens the object, the object opens in read-only mode, and the activation is not allowed. 2 OBJ1 Inactive Inactive Active Not Not If an object has multiple inactive Allowe Allowe versions in the Project Explorer d d and the object version in Modeler is active, neither activation nor take over option is enabled. Allowe Not If an object has single inactive d Allowe version in the Project Explorer, and d the object version in Modeler is active, only take over option is enabled. Not Applic able Allowe If an object has inactive versions in d the Project Explorer and Modeler, only activation option is enabled.
OBJ1
Inactive
Active
Active
OBJ1
Inactive
Active
Inactive
OBJ1
Active
Inactive
Active
Allowe Not If an object has multiple active d Allowe versions such as, one in the Project d Explorer and one in the Modeler, only take over option is enabled. Not Applic able Allowe If an object has single inactive d version, and the object version in Modeler is inactive, only activation option is enabled.
OBJ1
Active
Active
Inactive
OBJ1
Active
Inactive
Inactive
Not Allowe If an object has single active Allowe d version, and the object version in d
PUBLIC
213
Scen ario
Objec in Team Provider t
in SAP HANA Systems view
SAP HANA Systems view
Description
Modeler is inactive, only activation option is enabled. 8 OBJ1 Active Active Active Not Applic able (Rede ploy) If an object has multiple active versions, and the object version in Modeler is active, only take over activation (redeploy) option is enabled.
5.2.11
Description Mapping
Description mapping helps you to associate an attribute with another attribute, which describes it in detail. For example, when reporting via Label Column , you can associate Region_ID with Region_Text. For an attribute you can now maintain description mapping by selecting another attribute from the same model as Label Column in the Semantics node. The result is attribute description displaying as the label column in the data preview. The related columns appear side by side during data preview. You can rename a label column attribute as <attribute>.description but not as <label column attribute. description>. For example, if product_text is the Label Column for product then, you can rename product_text to product.description but not as product_text.description.
Note
On renaming a column as <attribute.description>, it is marked as Hidden and cannot be used in other places such as calculated columns, input parameters and so on. If you have created an object using the old editor (which supported the old style of description mapping) and try to open it using the new editor you will see a new column <attribute>.description (as an attribute) which is hidden and disabled. You can rename it maintain its properties and use it like other attributes.
5.2.12 Importing BW Objects

You can import SAP NetWeaver Business Warehouse (SAP NetWeaver BW) models that are SAP HANAoptimized InfoCubes, SAP HANA-optimized DataStore objects, Standard DataStore Objects, and Query Snapshot InfoProviders to the SAP HANA modeling environment.
Prerequisites
You have implemented SAP Notes 1703061, 1759172, 1752384, 1733519, 1769374, and 1790333.
214
You have upgraded your Modeler to SAP HANA 1.0 SPS06. You have added BW schema in the SQL privileges for the Modeler user to import BW models. _SYS_REPO user has SELECT with GRANT privileges on the schema that contains the BW tables.
Context
The BW imported objects are exposed as SAP HANA information models and can be consumed for reporting via SQL and using client tools such as, SAP BusinessObjects Explorer, SAP BusinessObjects BI 4.0 Suite (Web Intelligence via Universes, Dashboards, Crystal Reports), Microsoft Office and so on. The model properties are set based on the SAP NetWeaver BW models metadata.
Note
You can only import those Standard DataStore objects that have SID Generation set to During Activation. If you select a DataStore object, the resultant SAP HANA model is an analytic view with the same name as that of the DataStore object. If you select an InfoCube, two objects are created: analytic view and calculation view. In this case, the name of the calculation view and the analytic view is same as that of the InfoCube, and the name of the analytic view is suffixed with _INTERNAL. The analytic view generated in the case of an InfoCube is used internally for the generation of the respective calculation view and is not available for client consumption. If you select a QuerySnapshot InfoProvider, theSAP HANA model is an analytic view. Conversion of BW analysis authorizations to analytic privileges When you import the SAP NetWeaver BW InfoProviders, you can import the relevant BW analysis authorizations. The analysis authorizations are imported as analytic privileges in the SAP HANA Modeler. These analysis authorizations can be associated with the InfoProviders or roles. You can import the analysis authorizations in the following way: Only import InfoProvider-specific analysis authorizations. In this case, for all the authorization objects specific to the InfoProvider having 0CTAIPROV = <InfoProvider name>, the corresponding analytic privileges are generated. The name of the analytic privilege is the same as that of the BW analysis authorization object. You can choose to import analysis authorizations associated with the BW roles for the InfoProviders. In this case, all the analysis authorizations assigned to the selected roles are merged as one or more analytic privileges. The name of the generated analytic privilege is <InfoProvider name>_BWROLE_<number>, such as, MyCube_BWROLE_1.
These analysis authorizations set on the InfoProviders are applicable at runtime for reporting. For example, consider that a user has the following authorizations in BW: Table 12: AO1 0CUSTOMER 0PRODUCT Table 13: AO2 0CTAIPROV 0CUSTOMER CUBE1, CUBE2 3000 - 4000 1000 - 2000 ABC*
PUBLIC
215
0CTAACTVT
03 (display)
If only import InfoProvider specific authorizations,on the SAP HANA side, the user will only see 0CUSTOMER from 3000 to 4000. If import role based authorizations, on the SAP HANA side, the user will see 0CUSTOMER from 1000 to 4000, and 0PRODUCT = ABC*.
Note
In the case of Query Snapshot, all the BW Analysis Authorization objects that are applicable for the underlying InfoProvider of the query, will also be applicable for the Query Snapshot. These BW analysis authorization objects will be imported as analytic privileges when importing the query snapshot.
You can choose to place the generated models and analytic privileges in any of the user-defined packages in the import wizard any you can enhance the generated models. However, with the subsequent import of the same objects, the changes are overridden. Also, changes made to the models on the BW side are not automatically reflected in the generated models. This may lead to inconsistent generated models based on the changes made to the physical tables. To avoid this, you need to reimport the models.
Caution
The calculated key figures (CKFs) and restricted key figures (RKFs) defined on the SAP BW models are not created for the generated SAP HANA models. In this case, you can create an RKF as restricted measure in the generated analytic view. For CKF you can create calculated measures in the generated calculation view or analytic view. These CKFs and RKFs are retained during subsequent import. Additionally, the calculated attributes created on the generated analytic views (in case of InfoCubes and DSOs) are also retained during subsequent import. If a change is made to the characteristics or key figures based on which these restricted measures and calculated measures are created, this may lead to inconsistency in the generated models. In this case, you need to manually adjust these restricted measures and calculated measures. The restricted measures and calculated measures that you define for the analytic view that correspond to a query snapshot, is overwritten with the subsequent import. The BW analysis authorization objects are not always mapped 1:1 with the generated analytic privileges on the SAP HANA Modeler side. If the BW Analysis Authorization object does not include 0TCAIPROV, the authorization is not moved to SAP HANA. Also, restrictions created in the BW analysis authorization are skipped if they do not match with the restrictions supported by the SAP HANA Modeler. In such cases, the data available for reporting for a SAP HANA Modeler user differs from the SAP NetWeaver BW user with the assigned restrictions.
For reporting purposes, data that is visible to a user is: For a DSO generated analytic view, all the data in the active table is available for reporting. For an InfoCube generated calculation view, only successfully loaded requests are available for reporting (these are the green requests in Manage InfoCube section).
Restriction
The following features are not supported on the generated SAP HANA models: DSO without any key figure Currency and unit of measure conversion
216
PUBLIC
Note
Only currency mapping is supported and not the conversion. Time dependent text and attributes Non-cumulative key figures Conversion routines in the BW system Hierarchies Exclude operator Aggregated value operator : Variables, User exits Authorization on Key Figures Authorization on hierarchy node Exception aggregation such as, average, counter, first value, last value, no aggregation, standard deviation is not supported for generated measures.
The following features are not supported on generated analytic privileges:
The query name for the Query Snapshot should not be the same as the BW InfoProvider name (this results in conflict on the SAP HANA side). Query Snapshot InfoProvider for BOE supports only key figures with aggregation types MIN, MAX, SUM, and COUNT.
Procedure
1. 2. 3. 4. 5. Open the Modeler perspective. In the main menu, choose File Import .
Expand the SAP HANA Content node. Choose Import SAP NetWeaver BW Models, and choose Next. To establish a connection with the SAP NetWeaver BW system (underlying BW Application Server), in the Source System page, enter the SAP NetWeaver BW system credentials and choose Next.
Note
To add new connection details, select New Connection option from the Connection dropdown list. The connection details are saved and are available as dropdown options on subsequent logons. 6. 7. Select the target system (an SAP NetWeaver BW on SAP HANA) to which you want to import the models, and choose Next. Select the BW InfoProviders that you want to import and expose as SAP HANA information models.
Remember
In order to import the QuerySnapshot InfoProvider, make sure that the BW Query is unlocked in transaction RSDDB, and an index is created via the same transaction before it can be used as InfoProviders.
PUBLIC
217
8.
Select the target package where you want to place the generated models, and analytic privileges.
Note
Your package selection is saved during the subsequent import. Hence, the next time you visit the same wizard you get to view the package that was selected previous time. You can though change the package where you want to import objects. 9. If you want import the selected models along with the display attributes for IMO Cube and IMO DSO, select Include display attributes.
10. If you want to replace previously imported models in the target system with a new version, select Overwrite existing models. 11. If you do not want to import the analysis authorizations associated with the selected InfoProviders, deselect Generate InfoProvider based analytic privileges. 12. If you want to import the role based analysis authorizations as analytic privileges, select Generate Role based analytic privileges, and choose Next. 13. Select the roles to import the related analysis authorizations. 14. Choose Finish.
Results
The generated information models and analytic privileges are placed in the package selected above. In order to view the data of generated models, you need to assign the associated analytic privileges that are generated as part of the model import to the user. If these privileges are not assigned, user is not authorized to view the data.
5.2.13 Display Folders

If your analytic view and calculation view has multiple measures and you want to organize them, for, example, segregate the planned measures with the actual measures, you can group the related measures in folders. These folders are called the display folders. You can organize display folders in a hierarchical manner that is, by creating one display folder under the other. To create display folders, select the Display Folder toolbar option in the Column panel of the Semantics node. In the Display Folder dialog create a new folder using the context menu option or using the toolbar option. Drag the required measures to the relevant folder. Note that one measure can be part of multiple display folders. Alternatively, you can associate a measure with a new or existing display folder by entering the value in the Display Folder property of the measure. If you enter a new value for this property a new display folder with the specified name is created. Each measure is associated with the Display Folder property. The value for this property contains the fully qualified name of the display folder in which it appears. The fully qualified name of a display folder consists of the names of the display folders that represent the path to a given object. If the property contains the name of more than one display folder, indicating a hierarchy, each name is separated by a backslash character (\). If this property contains an empty string (""), the object is not associated with a display folder. The same measure can be part of multiple display folders. In such cases each folders should be separated by a semi colon (;). For
218
example, if for the measure Invoiced_amount the value for Display Folder property is Reported\Amount, it means, Reported\Amount is a hierarchical display folder of Invoiced_amount.
5.3 5.3.1
Additional Functionality for Views Creating Level Hierarchies
You create hierarchies to arrange view attributes that enhances data analysis by displaying attributes according to their defined hierarchical relationships.A level hierarchy is rigid in nature, and the root and the child nodes can only be accessed in a defined order.
Context
Level hierarchies consist of one or more levels of aggregation. Attributes roll up to the next higher level in a manyto-one relationship, and members at this higher level roll up into the next higher level, and so on, until they reach the highest level. An example of a level hierarchy is an address hierarchy comprised of region, country, state, and so on.
Note
The hierarchies belonging to an attribute view are available in an analytic view that reuses the attribute view in read-only mode. However, the hierarchies belonging to an attribute view are not available in a calculation view that reuses the attribute view.
Procedure
1. 2. 3. 4. Select the Semantics node. In the Hierarchies panel, choose Create option. Enter a name and description for the hierarchy. In the Hierarchy Type dropdown, select Level Hierarchy. In the Node tab page, do the following: a) Select the required value from the Node Style dropdown list.
Note
Node style determines the composition of a unique node ID. The different values for the node styles are: Level Name - the unique node ID is composed of the level name and node name; for example, "[Level 2].[B2]". Name Only - the unique node ID is composed of level name; for example, "B2".
PUBLIC
219
Name Path - the unique node ID is composed of the result node name and the names of all ancestors apart from the (single physical) root node; for example, "[A1].[B2].[C3]".
b) Add the required columns as levels from the drop-down list. You can select columns from the required table fields in the drop-down list to add to the view. c) Select the required Level Type. The level type is used to specify the semantics for the level attributes. A level of the type LEVEL_TYPE_TIME_MONTHS indicates that the attributes of the level contain month such as "January", and LEVEL_TYPE_REGULAR indicates that a level does not require any special formatting. d) To control how the members of the hierarchy are ordered, select the required column in the OrderBy drop-down list.
Note
In the MDX client tools, the members will be sorted on by attribute. e) To sort the display of the hierarchy members in the ascending or descending order, select the required option from the Sort Direction drop-down list. 5. In the Advanced tab page, do the following: a) Select the required value in the Aggregate All Nodes. This option indicates that data is posted on aggregate nodes and should be shown in the user interface. If you have the members A with value 100, A1 with value 10, and A2 with value 20 where A1 and A2 are children of A. By default the value is set to false, and you will see a value of 30 for A. With the value set to true, you will count the posted value 100 for A as well and see a result of 130. If you are sure that there is no data posted on aggregate nodes you should set the option to false. The engine will then calculate the hierarchy faster as when the option is set.
Note
Note that this flag is only interpreted by the SAP HANA MDX engine. In the BW OLAP engine the node values are always counted. b) Enter a value for the default member. c) To specify how to handle the orphan nodes in the hierarchy, select the required option from the dropdown list. In a parent-child hierarchy, if you have a row with parent = V1, child = V2, and there is no other row with child = V1, then V1 is treated as an orphan node. Option Root Node Error Ignore Step Parent Description Treat them as root nodes Stop processing and show an error Ignore them Put them under a step-parent node
220
PUBLIC
Option
Description
Note
The stepparent node must already exist in the hierarchy and it must be at the root level. Enter the node ID for the stepparent node. This enables you to assign all the orphaned nodes under this node. The node ID should be entered according to the node style selected. For example if the node style selected is level name, the stepparent node ID can be [Level2].[B2].
Note
If you have selected Step Parent in the Orphan Nodes dropdown, enter a value to create the stepparent node. d) Select Add a Root Node checkbox if a hierarchy does not have a root node, but needs one for reporting purposes. This will create a root node with the technical name ALL . e) Select the Mulitple Parent checkbox if a hierarchy needs to support multiple parents for its elements. for example, , The country, Turkey needs be assigned to two regions, Europe and Asia.
Restriction
Multiple parents and compound parent-child definition is currently not supported by MDX. 6. Choose OK.
5.3.2
Creating Parent-Child Hierarchies
A parent-child hierarchy is defined using a parent attribute that determines the relationship between the view attributes. A parent attribute describes a self-referencing relationship, or self-join, within the main table.
Context
Parent-child hierarchies are constructed from a single parent attribute. You can define multiple parent child pairs to support the compound node IDs. For example, two parent child pairs, CostCenter-ParentCostCenter and ControllingArea-ParentControllingArea, constitutes a compound parent child definition to uniquely identify cost centers . An example of a parent-child hierarchy is a bill of materials hierarchy (parent and child) or an employee master (employee and manager) hierarchy.
PUBLIC
221
Note
The hierarchies belonging to an attribute view are available in an analytic view that reuses the attribute viewin read-only mode. However, the hierarchies belonging to an attribute view are not available in a calculation view that reuses the attribute view.
Procedure
1. 2. 3. 4. Select the Semantics node. In the Hierarchies panel, choose the Create option . Enter a name and description for the hierarchy. In the Hierarchy Type dropdown, choose Parent Child Hierarchy. In the Node tab page, add the parent and child nodes by selecting Parent Node and Child Node from the dropdown list.
Note
If you decide to place the orphaned parent-child pair under a node called Step Parent from the Advanced tab page, you can specify its value in the Step Parent column. You can specify different stepparent values for all the parent-child pairs. These values appear as a comma separated list in the Advance tab page Step Parent field. In case of a single parent-child node, you can also specify the value for the stepparent node in the Advanced tab page. The same value appears in the Node tab page. 5. In the Advanced tab page, do the following: a) Select the required value in the Aggregate All Nodes and enter a value for the default member. This option indicates that data is posted on aggregate nodes and should be shown in the user interface. If you have the members A with value 100, A1 with value 10, and A2 with value 20, where A1 and A2 are children of A, then, by default, the value is set to false, and you will see a value of 30 for A. With the value set to true, you will count the posted value 100 for A as well and see a result of 130. If you are sure that there is no data posted on the aggregate nodes, then you should set the option to false. The engine will then calculate the hierarchy faster as when the option is set.
Note
This flag is only interpreted by the SAP HANA MDX engine. In the BW OLAP engine, the node values are always counted. b) To specify how to handle the orphan nodes in the hierarchy, select the required option from the dropdown list. In a parent-child hierarchy, if you have a row with parent = V1; child = V2, and there is no other row with child = V1, then V1 is treated as an orphan node. Option Root Node Description Treat them as root nodes
222
Option Error Ignore Step Parent
Description Stop processing and show an error Ignore them Put them under a stepparent node
Note
The stepparent node must already exist in the hierarchy and it must be at the root level. Enter the node ID for the stepparent node. This enables you to assign all the orphaned nodes under this node. For example, if the cost center 001 does not have parent cost center, then you can assign it to some other cost center 010 as a child.
Note
If you have selected Step Parent in the Orphan Nodes dropdown, enter a value to create the stepparent node. c) Select Add Root Node checkbox if a hierarchy does not have a root node, but needs one for reporting purposes. Set the option to True and it will create a root node.
Note
If a hierarchy does not have a root node but needs one for reporting use case, d) Select the Mulitple Parent checkbox if a hierarchy needs to support multiple parents for its elements. for example, The country, Turkey needs be assigned to two regions, Europe and Asia.
Restriction
Multiple parents and compound parent-child definition is currently not supported by MDX. 6. Choose OK.
5.3.3
Creating Input Parameters
You use input parameters to define internal parameterization of the view. Input parameters used in the views enables you to obtain a desired functionality when the view is executed. This means the engine needs to know and use the parameter value during the view execution for example, to calculate a formula for a calculated measure. The parameter value is passed to the engine via the PLACEHOLDER clause of the SQL statement. Normally a parameter can only have a single value, for example, for currency conversion. However, when working with the in() function in filter expressions of the calculation views you can pass several values as an IN List. The quoting must be followed as shown below:
PUBLIC
223
For numerical type parameters The filter expression of a calculation view CV1 is defined as: in("attr", $$param$$) Then you need to pass several values as: select ... from CV1( 'PLACEHOLDER' = ('$$var$$' = 'VAL1,VAL2,VAL3') For string type parameters The filter expression of a calculation view CV1 is defined as: in("attr", $$param$$) Then you need to pass several values (with double quotes) as: select ... from CV1( 'PLACEHOLDER' = ('$$var$$' = '''VAL1'',''VAL2'',''VAL3''') You use input parameters as placeholders during currency conversion and formulas like calculated columns in an analytic view and a calculation view. When used in formulas, the calculation of the formula is based on the input that you provide at runtime during data preview. In calculation view, you can additionally use these input parameters in the script node. You can apply input parameters in analytic and calculation views. If a calculation view is created using an analytic view with input parameters, those input parameters are also available in the calculation view. The following types of input parameters are supported: Type
Column Static List Derived From Table
Description
Use this when the value of a parameter comes from an attribute or table column. Use this when the value of a parameter comes from a userdefined list of values. Use this when the value of a parameter comes from a table column based on some filter conditions and you do not need to provide any input at runtime. Use this to specify an input parameter as currency and date during currency conversion.
Direct
Each type of input parameter is either mandatory or non-mandatory. Mandatory in the view model means semantically mandatory that is, the data might be inconsistent if the parameter value is not provided because for instance data is then aggregated across clients. From the engine point of view the parameter is technically mandatory that is, if no default value is provided (which means a value has to be provided by the caller). Therefore, irrespective of the parameter being set as mandatory or not, if a default value is not set for the parameter, and it is mandatory to provide a value at runtime. The expected behavior of the input parameter when a value at runtime is not provided is as follows: Default Value Yes No Expected Behavior Calculates the formula based on the default value Results in error
224
Note
The table above implies that it is mandatory to provide a value for the input parameter either at runtime or assign a default value while creation, otherwise, it leads to errors.
Note
You can also check whether an input parameter is mandatory or not from the properties of the input parameter in the Properties pane.
Example
If you want to preview a sales report with data for various countries in their respective currency for a particular date for correct currency conversion, you can use Currency and Date as input parameters.
Procedure
1. 2. In the Scenario panel, select a node. In the Output panel right-click Input Parameters node.
Note
You can also create input parameters at the Semantics node level, using the Create Input Parameter option in the Variables/Input Parameters panel. 3. From the context menu, choose New. a. b. Enter a name and description (Label). Select the type of input parameter from the Parameter Type dropdown list.
Note
For the Column type of input parameter, you need to select an attribute from the Reference Column dropdown list. At runtime the value for the input parameter is fetched from the selected attribute data selected in the Reference Column dropdown list. For an input parameter of type Derived from Table, you need to select a table and one of its columns as Return Column whose value is then used as input for the formula calculation. You can also define conditions to filter the values of Return Column in the Filters panel. For example, to calculate a discount for specific clients, you can create an input parameter based on the Sales table and return column Revenue with filter set on the Client_ID. For a Direct Type input parameter, specify the Semantic Type that describes the use parameter as a currency or date, for example, to specify the target currency during currency conversion. For a Static List input parameter, specify a list of values along with the data types, length and scale that you would use for the input parameter.
c.
To provide the default value for the input parameter that is considered in case a value at runtime is not provided, choose the option Constant or Expression as required.
PUBLIC
225
Note
You can use expressions for default value when you want to calculate the default value based on some formula like, date(Now()) to perform calculation based on the current date. d. e. f. If required, select a data type. Enter length and scale for the input parameter. Choose OK.
Note
You can also copy an input parameter and modify it as required to make a new one. The copy-paste option is available from the context menu of the calculated column. You can also use the CTRL + C and CTRL + V keyboard shortcuts. The copy-paste functionality only works in the same editor, that is, if you copy an input parameter in one view editor, you cannot paste it in another view editor. The copy-paste functionality for input parameters only works in the Output panel and the Data Foundation .
5.3.4
Assigning Variables
You can assign variables to a filter at design time for obtaining data based on the values you provide for the variable. At runtime, you can provide different values to the variable to view the corresponding set of attribute data. You provide values to the variables either by entering the values manually, or by selecting them from the Value Help dialog.
Note
You can apply variables to attributes of analytic and calculation views. The following types of variables are supported: Type
Single Value
Description
Use this to filter and view data based on a single attribute value. For example, to view the sales of a product where the month is equal to January. Use this to filter and view a specific set of data. For example, to view the expenditure of a company from March to April. Use this to filter and view data based on the conditions that involve operators such as "="(equal to), ">" (greater than), "<" (less than), ">=" (greater than or equal to), and "<=" (less than or equal to). For example, to view the sales of all products in a month where the quantity sold is >= 100..
Interval Range
Each type of variable can be either mandatory or non-mandatory. For a mandatory variable, you need to provide a value at runtime. For a non-mandatory variable, if you have not specified a value at runtime, you view unfiltered data.
226
PUBLIC
Note
You can check if a variable is mandatory from the properties of the variable in the Properties pane.
Procedure
1. In the Semantics node Variables/Input Parameter panel, choose the Create Variable option.
Note
Alternatively, you can invoke the variable dialog by selecting the attribute from the Column panel, and choosing . If you create variable using this option, the Attribute and Assign variable filter to fields are auto-filled with the selected attribute. 2. 3. Enter a name and description for the variable. Select the required attribute from the dropdown list.
Note
At runtime, the value for the variable is fetched from the selected attribute's data. Also, the attribute you select for the first time from the dropdown list is automatically added to the Apply variable filter to panel. If you make change to the Attribute dropdown selection this value still prevails in the Apply variable filter to, and the newly selected attribute is not added to the list of Apply variable filter to. 4. 5. 6. Choose the required Selection Type from the dropdown list. Select Multiple Entries if you want to provide different values at runtime to filter data. For example, to view the revenue from a period of 2000 to 2005 and 2012. To specify the variable as mandatory, select the Is Mandatory checkbox.
Note
Each type of variable can be either mandatory or non-mandatory. For a mandatory variable, it is necessary to provide a value at runtime. However, for a non-mandatory variable, if you do not specify a value at runtime, you see the unfiltered data. 7. To provide the default value for the variable that is considered in case a value at runtime is not provided, choose the option Constant or Expression as required.
Note
You can use expressions for default value when you want to calculate the default value based on some formula like, date(Now()) to perform calculation based on the current date. 8. 9. To assign the variable to attribute(s), in the Apply variable filter to panel, choose Add. Select the attribute(s) from the dropdown list to which you want to assign this variable.
PUBLIC
227
Note
You can also assign a variable to an attribute later in the Column panel of the Semantics node Details panel. To assign a variable to an attribute, select a variable from the variable dropdown list in the Variable column.
Remember
Once you assign a attribute to the variable, you can delete that variable only after removing the attribute from the Apply variable filter to in the Variable dialog. 10. Choose OK.
5.3.5
Using Currency and Unit of Measure
You can define a measure as an amount or quantity in the analytical space, and perform currency conversion. Measures used in analytic views and calculation views can be defined as amount or weight in the analytical space using currency and unit of measure. You can also perform currency conversion and unit of measure conversion. For example, you need to generate a sales report for a region in a particular currency, and you have sales data in database tables in a different currency. You can create an analytic view by selecting the table column containing the sales data in this other currency as a measure, and perform currency conversion. Once you activate the view, you can use it to generate reports. Similarly, if you need to convert the unit of a measure from cubic meters to barrels to perform some volume calculation and generate reports, you can convert quantity with unit of measure. To simplify the process of currency conversion, the system provides a list of currencies, and exchange rates based on the tables imported for currency. Currency conversion is performed based on source currency, target currency, exchange rate, and date of conversion. You can also select currency from the attribute data used in the view. To simplify the process of conversion, system provides the following: For currency conversion - a list of currencies, and exchange rates based on the tables imported for currency. For quantity unit conversion - a list of quanity units based on the tables imported for units.
Currency conversion is performed based on the source currency, target currency, exchange rate, and date of conversion. You can also select currency from the attribute data used in the view. Similarly, quantity unit conversion is performed based on the source unit and target unit. You can also select the target currency or unit of measure at query runtime using input parameters. If you use this approach then, you have to first create an input parameter with the desired currency/unit specified, and use the same input parameter as target in the conversion dialog.
Note
Currency conversion is enabled for analytic views and base measures of calculation views.
228
Prerequisites
You have imported tables T006, T006D, and T006A for Unit of Measure. You have imported TCURC, TCURF, TCURN, TCURR, TCURT, TCURV, TCURW, and TCURX for currency.
Procedure
1. 2. 3. Select a measure. In the Properties pane, select Measure Type. If you want to associate the measure with a currency, perform the following substeps: a. b. In the Measure Type dropdown list, select the value Amount with Currency. In the Currency Dialog, select the required Type as follows: Type
Fixed Attribute
Purpose
To select currency from the currency table TCURC. To select currency from one of the attributes used in the view.
c. d.
Select the required value, and choose OK. If you want to convert the value to another currency, choose Enable for Conversion. a. b. To select the source currency, choose Currency. Select the target currency.
Note
For currency conversion, in addition to the types Fixed and Attribute, you can select Input Parameter to provide target currency at runtime. If you select an input parameter for specifying target currency and deselect Enable for Conversion checkbox, the target currency field gets clear because input parameters can be used only for currency conversion. c. To specify exchange rate type, in the Exchange Rate Types dialog, select the Type as follows: Type
Fixed Input Parameter
Purpose
To select exchange rate from the currency table TCURW. To provide exchange rate input at runtime as input parameter.
d.
To specify the date for currency conversion, in the Conversion Date dialog, select the Type as follows: Type
Fixed Attribute Input Parameter
Purpose
To select conversion date from the calendar. To select conversion date from one of the attributes used in the view. To provide conversion date input at runtime as input parameter.
PUBLIC
229
e. f. e.
To specify the schema where currency tables are located for conversion, in the Schema for currency conversion, select the required schema. To specify the client for which the conversion rates to be looked for, in the Client for currency conversion, select the required option.
From the dropdown list, select the required value that is used populate data if the conversion fails: Option
Fail Set to NULL Ignore
Result
In data preview, the system displays an error for conversion failure. In data preview, the value for the corresponding records is set to NULL. In data preview, you view the unconverted value for the corresponding records.
4.
If you want to associate a measure with a unit of measure other than currency, perform the following substeps: a. b. Select the value Quantity with Unit of Measure in the Measure Type drop-down list. In the Quantity Units dialog , select the required Type as follows: Type
Fixed Attribute
Purpose
To select a unit of measure from the unit tables T006 and T006A. To select a unit of measure from one of the attributes used in the view.
c. 5.
Select the required value, and choose OK.
Choose OK.
Note
You can associate Currency or Unit of Measure with a calculated measure, and perform currency conversion for a calculated measure by editing it. Related Information Creating Input Parameters [page 223] You use input parameters to define internal parameterization of the view. Input parameters used in the views enables you to obtain a desired functionality when the view is executed.
5.3.6
Working with Broken Objects
You use this functionality to work with the broken models caused due to missing objects. Earlier opening of broken models was not possible and the model was corrected either by editing its XML file, or by adding the missing objects. In both the cases you had to remember the details of the missing objects to fix the problems. Now, you can work with the broken objects using proxies. With proxies, you can open the broken objects and fix the inconsistencies. After fixing the inconsistencies, you can activate and use the object like before. At present the proxies are supported for attribute view, analytic view and calculation view.
230
PUBLIC
The missing required objects are shown with red decorator. The inconsistencies in the objects due to missing required objects are shown with the red error markers. You can resolve inconsistencies by performing one of the following: Deleting the missing required objects which clears off all the references for the same Adjusting the mappings of the inconsistent objects Deleting the inconsistent objects
Note
The inconsistencies found in the model will be logged in the problems view (only in SAP HANA Development perspective).
Note
If the connection to the SAP HANA system is not available, proxies for all the required objects are injected and thus it is still possible to view the model. But since the model is not broken actually, the red decorators and the error markers are not shown. The editor opens in read-only mode.
Example
An attribute view ATV1 is defined on table T1 (C1, C2, C3). Attributes A1, A2, A3 are defined on columns C1, C2, C3 respectively. If the column C3 is removed from the table T1 then the attribute A3 becomes inconsistent. In such cases a proxy is injected for C3. When you open the editor, a red LED decorator will be shown for C3 and an error marker for A3 to indicate that it is inconsistent. The inconsistency can be resolved by any of the three methods mentioned above.
PUBLIC
231
5.4 5.4.1
Working with Views Managing Layout
You use this procedure to adjust the data foundation and logical view layout comprising user interface controls like, tables and attribute views in a more readable manner. This functionality is supported for attribute views and analytic views. The options available are as follows: Option
Auto Arrange Show outline
Purpose
Use this option to arrange the user interface elements automatically. Use this option to view an outline of the elements arranged so that , you do not have to navigate in the editor using horizontal and vertical scrollbars. Use this option if you want to view only those tables that are related to a table selected in the editor.
Substeps
In the editor tool bar, choose In the editor tool bar, choose . .
Highlight related tables
1. 2.
In the editor, right-click the selected table. From the context menu, choose Highlight related tables. In the editor, right-click the relevant table. From the context menu, choose Display. If you want to view only the table name, choose Collapsed. If you want to view all the columns of the table, choose Expanded. If you want to view only the joined columns of the table, choose Joins only.
Display
Use this option if you have a table with a large number of columns in the editor, and you want to view them in a way that meets your needs: for example, only the table name, or only joined columns, or the expanded form with all the columns.
1. 2. 3. 4. 5.
5.4.2
Validating Models
You can check if there are any errors in an information object and if the object is based on the rules that you specified as part of preferences. For example, the "Check join: SQL" rule checks that the join is correctly formed. For more information about setting preferences, see Setting Preferences for Modeler .
232
Procedure
1. 2. 3. On the Quick Launch page, choose Validate. From the Available list, select the required models that system must validate, and choose Add. Choose Validate.
5.4.3
Maintaining Search Attributes
You use this procedure to enable an attribute search for an attribute used in a view. Various properties related to attribute search are as follows: Freestyle Search: Set to True if you want to enable the freestyle search for an attribute. You can exclude attributes from freestyle search by setting the property to False. Weights for Ranking: To influence the relevancy of items in the search results list, you can vary the weighting of the attribute. You can assign a higher or lower weighting (range 0.0 to 1.0). The higher the weighting of the attribute, the more influence it has in the calculation of the relevance of an item. Items with a higher relevance are located higher up the search results list. Default value: 0.5.
Note
To use this setting the property Freestyle Search must be set to True. Fuzzy Search: This parameter enables the fault-tolerant search. Default: False. Fuzziness Threshold: If you have set the parameter Fuzzy Search to True you can fine-tune the threshold for the fault-tolerant search between 0 and 1. Default: 0.8
Note
We recommend using the default values for Weights for Ranking and Fuzziness Threshold to start with. Later on, you can fine-tune the search settings based on your experiences with the search. You can also fine-tune the search using feedback collected from your users.
5.4.4
Previewing Data of Content Objects
You use this procedure to preview the content of content models for analysis purposes. 1. 2. 3. In the Modeler perspective, expand the Content node of the required system. Select the object from a package for which you want to view the content. From the context menu, choose Data Preview. The system displays the content in different formats as shown in the table below. Tab Page
Raw Data Distinct values
Displays
All attributes along with data in a table format. All attributes along with data in a graphical format.
PUBLIC
233
Tab Page
Analysis
Displays
All attributes and measures in a graphical format.
Tip
If there are inconsistencies in runtime information (that is, calculation views in catalog or in tables related to runtime) of a view, you might get invalidated view error. In such cases, you need to redeploy the view in order to correct the inconsistencies with runtime information.
Note
If you refresh the Analysis view, the behavior is as follows: The selection of the columns in Lables Axis and Values Axis panel of the Analysis view gets cleared. The data in the Raw Data view gets cleared and you need to perform refresh in the Raw Data view to fetch the latest data.
4.
Navigate to the required tab page and view the content.
5.4.5
Functions used in Expressions
This topic covers the functions that you can use while creating expressions like, calculated attributes and calculated measures. Conversion Functions Function
int float
Syntax
int int(arg) float float(arg)
Purpose
convert arg to int type convert arg to float type
Example
int(2) float(3.0)
double sdfloat decfloat fixed
double double (arg) sdfloat sdfloat (arg) decfloat decfloat (arg) fixed fixed (arg, int, int)
convert arg to double type convert arg to sdfloat type convert arg to decfloat type arg2 and arg3 are the intDigits and fractdigits parameters, respectively. Convert arg to a fixed type of either 8, 12, or 16 byte length, depending on intDigits and fractDigits convert arg to string type convert arg to raw type
double(3)
fixed(3.2, 8, 2) + fixed(2.3, 8, 3)
string raw
string string (arg) raw raw (arg)
234
Function
date
Syntax
date date(stringarg) date date(fixedarg) date date(int, int) date date(int, int, int) date date(int, int, int, int) date date(int, int, int, int, int) date date(int, int, int, int, int, int)
Purpose
convert arg to date type. The first version parses a string in the format "yyyy-mm-dd hh:mi:ss" where trailing components except for the year may be omitted. The version with one fixed number arg strips digits behind the comma and tries to make a date from the rest. The other versions accept the individual components to be set. convert arg to longdate type, similar to date function above.
Example
date(2009) -> date('2009') date(2009, 1, 2) -> date('2009-01-02') date(fixed(20000203135026 .1234567, 10, 4)) -> date('2000-02-03 13:50:26')
longdate
longdate longdate(stringarg) longdate longdate(fixedarg) longdate longdate(int, int, int) longdate longdate(int, int, int, int, int) longdate longdate(int, int, int, int, int, int) longdate longdate(int, int, int, int, int, int, int)
longdate(fixed(2000020313 5026.1234567, 10, 5)) -> longdate('2000-02-03 13:50:26.1234500') longdate(2011, 3, 16, 9, 48, 12, 1234567) -> longdate('2011-03-16 09:48:12.1234567')
time
time time(stringarg) time time(fixedarg) time time(int, int) time time(int, int, int)
convert arg to time type, similar to date function above
String Functions Function

strlen midstr
Syntax
int strlen(string) string midstr(string, int, int)
Purpose
returns the length of a string in bytes, as an integer number. returns a part of the string starting at arg2, arg3 bytes long. arg2 is counted from 1 (not 0)
leftstr
string leftstr(string, int)
returns arg2 bytes from the left of the arg1. If arg1 is shorter than the value of arg2, the complete string will be returned.
PUBLIC
235
Function
rightstr
Syntax
string rightstr(string, int)
Purpose
returns arg2 bytes from the right of the arg1. If arg1 is shorter than the value of arg2, the complete string will be returned.
instr
int instr(string, string)
returns the position of the first occurrence of the second string within the first string (>= 1) or 0, if the second string is not contained in the first.
hextoraw
string hextoraw(string)
convert a hexadecimal representation of bytes to a string of bytes. The hexadecimal string may contain 0-9, upper or lowercase a-f and no spaces between the two digits of a byte; spaces between bytes are allowed.
rawtohex
string rawtohex(string)
convert a string of bytes to its hexadecimal representation. The output will contain only 0-9 and (upper case) A-F, no spaces and is twice as many bytes as the original string.
ltrim
string ltrim(string) string ltrim(string, string)
removes a whitespace prefix from a string. The Whitespace characters may be specified in an optional argument. This functions operates on raw bytes of the UTF8-string and has no knowledge of multi byte codes (you may not specify multi byte whitespace characters). removes trailing whitespace from a string. The Whitespace characters may be specified in an optional argument. This functions operates on raw bytes of the UTF8-string and has no knowledge of multi byte codes (you may not specify multi byte whitespace characters). removes whitespace from the beginning and end of a string.
rtrim
string rtrim(string) string rtrim(string, string)
trim
string trim(string) string trim(string, string)
lpad
string lpad(string, int) string lpad(string, int, string)
add whitespace to the left of a string. A second string argument specifies the whitespace which will be added
236
PUBLIC
Function
Syntax
Purpose
repeatedly until the string has reached the intended length. If no second string argument is specified, chr(32) (' ') will be added. This function operated on UTF-8 bytes and has no knowledge of unicode characters (neither for the whitespace string nor for length computation).
rpad
string rpad(string, int) string rpad(string, int, string)
add whitespace to the end of a string. A second string argument specifies the whitespace which will be added repeatedly until the string has reached the intended length. If no second string argument is specified, chr(32) (' ') will be added. This function operated on UTF-8 bytes and has no knowledge of unicode characters (neither for the whitespace string nor for length computation).
replace
string replace(string, string, string)
replace every occurrence of arg2 in arg1 with arg3 and return the resulting string
Mathematical Functions Function

sign
Syntax
int sign(double) int sign(time) int sign(date)
Purpose
Sign returns -1, 0 or 1 depending on the sign of its argument. Sign is implemented for all numeric types, date and time. Abs returns arg, if arg is positive or zero, -arg else. Abs is implemented for all numeric types and time.
Example
abs
double abs(double) decfloat abs(decfloat) decfloat abs(decfloat) time abs(time)
round .
double round(double, int)
round does rounding of absolute values toward zer while the sign is retained
round(123.456, 0) = 123 round(123.456, 1) = 123.5 round(-123.456, 1) = -123.5 round(123.456, -1) = 120
rounddown
double rounddown(double, int)
rounddown rounds toward negative infinity making rounddown(-1.1, 0) = -2
rounddown(123.456, -1) = 120 rounddown(-123.456, -1) = -130
PUBLIC
237
Date Functions Function

utctolocal
Syntax
utctolocal(datearg, timezonearg)
Purpose
interprets datearg (a date, without timezone) as utc and convert it to the timezone named by timezonearg (a string)
localtoutc
localtoutc(datearg, timezonearg)
converts the local datetime datearg to the timezone specified by the string timezonearg, return as a date returns the weekday as an integer in the range 0..6, 0 is monday. returns the current date and time (localtime of the server timezone) as date returns the number of days (integer) between date1 and date2. The first version is an alternative to date2 - date1. Instead of rounding or checking for exactly 24 hours distance, this will truncate both date values today precision and subtract the resulting day numbers, meaning that if arg2 is not the calendar day following arg1, daysbetween will return 1 regardless of the time components of arg1 and arg2.
weekday now
weekday(date) now()
daysbetween
daysbetween(date1, date2) daysbetween(daydate1, daydate2) daysbetween(seconddate1, seconddate2) daysbetween(longdate1, longdate2)
secondsbetween
secondsbetween(seconddate1, seconddate2) secondsbetween(longdate1, longdate2)
returns the number of seconds the first to the second arg, as a fixed point number. The returned value is positive if the first argument is less than the second. The return values are fixed18.0 in both cases (note that it may prove more useful to use fixed11.7 in case of longdate arguments).
component
component(date, int)
the int argument may be int the range 1..6, the values mean year, day, month, hour, minute, second, respectively. If a component is not set in the date, the component function will return a default value, 1 for the month or the day, 0 for other components. The component function may also be applied to longdate and time types. Return a date plus a number of seconds. Fractional seconds will also be used in case of longdate. Null handling is (in opposition to the default done with
addseconds
addseconds(date, int) addseconds(seconddate, decfloat)
238
Function
Syntax
addseconds(longdate, decfloat)
Purpose
adds) to return null if any argument is null. Return a date plus a number of days. Null handling is (in opposition to the default done with adds) to return null if any argument is null.
adddays
adddays(date, int) adddays(daydate, int) adddays(seconddate, int) adddays(longdate, int)
Misc Functions Function

if
Syntax
if(intarg, arg2, arg3)
Purpose
Example
return arg2 if intarg is if("NETWR"<=500000,'A', considered true (not equal to if("NETWR"<=1000000,'B','C ') ) zero), else return arg3. Currently, no shortcut evaluation is implemented, meaning that both arg2 and arg3 are evaluated in any case. This means you cannot use if to avoid a divide by zero error which has the side effect of terminating expression evaluation when it occurs. return 1 (= true) if arg1 is equal to any of the remaining args, return 0 else case("CATEGORY", 'A', 'LV', 'B', 'MV', 'HV')
in
in(arg1, ...)
case
case(arg1, default) case(arg1, return value1 if arg1 == cmp1, cmp1, value1, cmp2, value2 if arg1 == cmp2 etc, value2, ..., default) default if there no match isnull(arg1) return 1 (= true), if arg1 is set to null and null checking is on during Evaluator run (EVALUATOR_MAY_RETURN _NULL)
isnull
5.4.6
Resolving Conflicts in Modeler Objects
You can resolve the conflicts between three different versions of a model by merging them with the help of 3-way merge feature. You can also compare two files for finding their differences with this feature.The common scenarios and the available options for the use of this feature are:
PUBLIC
239
S.No. 1.
Requirement To compare two models in the Project Explorer to view their differences.
Option Compare With > Each Other
2. 3.
To compare the inactive version of a Compare With > Active Version model with the active version. To resolve conflicts between the Team > Merge Tool model versions encountered during Or activation in the following scenarios: Team > Resolve With You modify a model in two SAP HANA studio instances and you commit and activate the model (one or several times) in the first instance. In the second instance when you try to activate the model you get an error message. You modify a model in one of the SAP HANA studio instance, and commit and activate the model. If you modify the model in the other SAP HANA studio instance without updating it, you get an error while activating the model. In a SAP HANA studio instance if you have an inactive model in the Project Explorer and an inactive version in the Modeler perspective. If you activate the model in the Modeler perspective, you get an error while activating the model from Project Explorer.
240
The merge editor components are depicted below:
PUBLIC
241
1. 2. 3. 4.
Overview of the differences detected between the given two (or three) models. First version of the compared models. Second version of the compared models. This button will only be visible in the case of three-way comparisons (for example, comparing with a remote repository). It will make a third version of the compared model (the common ancestor of the two others) visible in the interface. This button will allow you to group differences together in the structural view. For example, grouping all "Additions" or "Deletions" together. This button will allow you to filter some differences out of the view according to a set predicate. For example, filtering out all "Additions" or "Moves". Allows you to merge all non-conflicting differences (left to right, or right to left) at once. Allows you to merge the single, currently selected difference in a given direction (left to right, or right to left). Allows you to navigate through the detected differences.
5. 6. 7. 8. 9.
5.5
Creating Decision Tables
You use this procedure to create a decision table to model related business rules in a tabular format for decision automation. Using decision tables you can manage business rules, data validation, data quality rules without any IT knowledge on technical languages like, SQL Script, MDX. A data architect or a developer creates the decision table and activates it. The active version of the decision table can be used in applications.
242
Procedure 1. Set Parameters

1. 2. 3. 4. In the Modeler perspective, expand <System Name> New Content <Package Name> . .
In the context menu of the package, choose
Decision Table
In the New Decision Table dialog box, enter a name and description for the decision table. To create data foundation for the decision table, perform substeps of the required scenario given in the table below: Scenario
Create a decision table from scratch.
Substeps
1. 2. Choose Create New. Choose Next.
Note
If you launch the New Decision Table dialog from the Quick Launch tab page, specify the package where you want to save the decision table. 3. Add the required tables, table type or an information view to the Selected list.
Note
You can choose to add the required data sources to the decision table later by dragging them from the Catalog node in the Navigator view to the Data Foundation panel. 4. Create a decision table from an existing decision table. 1. Choose Finish. Choose Copy From.
Note
If you launch the New Decision Table dialog from the Quick Launch page, specify the package where you want to save the decision table. 2. 3. Select the required decision table. Choose Finish.
Note
Only an active version of an information view can be used. Any changes made to the information view are not reflected in the decision table. You can create a decision table using an analytic view only if it has a calculated attribute. If you choose to create a decision table based on a table type or an information view, you cannot add any other data source. This implies that a decision table can be based on multiple tables or a table type or an information view. You can add only one table type or information view to the data foundation.
PUBLIC
243
You can mark table type columns and information view columns only as conditions. While designing decision table using information view, you can only use view's attributes as conditions and not the other attributes. In addition, you can use only parameters as actions.
Remember
You can set the decison table property Multually Exclusive to true or false. By default, the value of this property is set to true. If set to true, as soon as any condition row is matched in decision table the search is stopped even though there might be other rows that could have been matched. This required additional effort to model the decision table in specific way such that the more specific rules appear on top of the decision table and general rules appear at the end. If the value is set to false, all the condition rows are checked and based on the best suited match, the action value is updated. For example, consider a scenario where you would like to give the Discount as 5 % on all the Cold Drinks in the Summer Season for Country India. If the decision table has been modeled as below: Country India India India Season Summer Any Summer Drinks Any Any Cold Drink Discount 7 2 5
If Mutually Exclusive is set to true, the first row would be matched and it would lead to Discount as 7%. If it is set to false, the third row would be considered providing discount as 5%.
2. Create Joins
1. If you want to define a relationship between tables to query data from two or more tables, do the following: a. b. c. In the editor pane, from the context menu, choose Create Join. In the Create Join dialog, select the required tables, columns, join type, and cardinality. Choose Create Join.
Note
You can also create a join between table columns by dragging it from one table column to another table column. The supported join types are inner, left outer and right outer.
3. Add Conditions and Actions

1. In the Data Foundation view, select the required column, and perform substeps of the required scenario given in the table below:
244
PUBLIC
Scenario
Include table field in the output structure.
Substeps
From the context menu, choose Add as Attribute.
Note
Attributes contains a subset of columns that you use to derive conditions and actions. Add conditions based on which you want to derive actions.
1. 2.
In the Output view, select the required attributes . From the context menu, choose Add as Conditions. In the Output view, select the required attributes . From the context menu, choose Add as Actions.
Add actions for the selected conditions.
1. 2.
2.
To add condition values, do the following: a. In the Decision Table view, right-click a condition, and choose Add Conditions Values.
Note
The supported data types for an operator are: Operator Not Equal To In Not In Like Not Like Greater Than Greater Than or Equals Less Than Less Than or Equals Between Before Date Number Dates Number & CHAR-based Supported Data Types Number & CHAR-based Number & Char-based Number & Char-based CHAR-based CHAR-based Number & CHAR-based Syntax != ABC In ABC;CDA Not In A;B;C Like Abc* Not Like Abc* >20 >=20 <10 <=10 Between 20 and 30 Before 2012-12-12 Or < 2012-12-12 After Date Dates After 2012-12-12 Or > 2012-12-12
PUBLIC
245
Operator Between Date
Supported Data Types Dates
Syntax Between 2012-12-12 and 2012-12-25
Remember
If the support data type is CHAR-based, you must put IN and the associated value under quotes. This ensures that IN is not considered as an operator. For example, IN PROCESS is a value, whereas IN PROCESS without quotes reflects IN as an operator and PROCESS as a value. b. Enter a value, and choose OK.
Note
If a database table column is used as condition, you can use the value help dialog to select the condition values. You can select multiple values at one time. You can edit a condition value by selecting the condition, and entering a value. You can enter a pattern for the condition values having data type as VARCHAR. The pattern must be prefixed with the LIKE and NOT LIKE operators. For example, LIKE a*b or NOT LIKE a?b. If the LIKE or NOT LIKE operator is not present the pattern is treated as a string
3. 4.
To set action values, right-click an action cell, and enter value. If you want to write a complex expression as action or condition value, do the following: a. b. c. d. Right-click the action field. From the context menu, choose Set Dynamic Value. Write the expression for example, PRICE-(PRICE*0.1). To edit a value you need to select that value.
Note
You can use parameters and table columns of the same data type as that of the action or condition in expressions. 5. To assign a value to a condition or an action based on the table data, choose Open Value Help Dialog, and do the following: a. In the Value Help for Column dialog, enter the search string, and choose Find.
Note
If you do not provide a value for search and choose Find, all the data corresponding to the selected column is shown. b. Select a value, and choose OK.
Remember
You can provide an alias name to a condition or an action by editing the value of Alias name property. You can choose to create parameters and use them as conditions or actions. The values you provide to the parameters at the runtime determine which data records are selected for consumption. For more information regarding how to use parameters, Using Parameters in a Decision Table [page 250].
246
You can export decision table data to an excel sheet using context menu option Export Data to Excel in the Decision Table view. You can also import decision table data from an excel using context menu option Import Data from Excel in the Decision Table view. You can arrange the condition and action columns of the decision table depending on how you want them to appear. For more information, see Changing the Layout of a Decision Table [page 249].
6. Optional Step: Validate Decision Table

1. To set the rules that you want to use for validation do the following: a. b. c. d. e. 2. Choose Window Preferences . Modeler Validation Rules .
In the Preferences dialog box, expand
In the Validation Rules view, select Decision Table checkbox to check for all the rules during validation. If you want to check for individual rules, select the required rules. Choose OK. .
In the decision table editor, choose Validate in the editor toolbar
Note
In the Job Log section, you can see the validation status and detailed report of the decision table
7. Activate Decision Table

1. 2. Choose File Save .
From the context menu of the decision table, choose Activate.
Note
You can choose to save and activate the view from the editor using .
Result: On successful activation, a procedure corresponding to the decision table is created in _SYS_BIC schema. The name of the procedure is in the format, <package name>/<decision table name>. In addition, if a parameter is used as an action in the decision table, the corresponding table type is created in _SYS_BIC schema. The name of the table type is in the format, <package name>/<decision table name>/TT.
Remember
If in a decision table, parameters are used as conditions then corresponding IN parameters are generated. Also, if the parameters are used as actions then an OUT parameter is generated.
PUBLIC
247
8. Execute Decision Table Procedure

1. To execute the decision table procedure perform the following steps as required: Data Source Physical tables Physical tables Condition Physical table column Parameters Action Physical table column Physical table column Parameters Parameters Script call "<schema name>"."<procedure name>"; call "<schema name>"."<procedure name>"(<IN parameter>,,<IN parameter>); call "<schema name>"."<procedure name>"(?); call "<schema name>"."<procedure name>"(<IN parameter>,,<IN parameter>,?); call "<schema name>"."<procedure name>"(?); call "<schema name>"."<procedure name>"(<IN parameter>,,<IN parameter>,?); call "<schema name>"."<procedure name>"(?); call "<schema name>"."<procedure name>"(<IN parameter>,,<IN parameter>,?);
Physical tables Physical tables
Physical table column Parameters
Information View Information View Table Type Table Type
View attributes Parameters
Parameters Parameters
Table Type column Parameters
Parameters Parameters
Remember
The order of the parameter while executing the procedure must be same as in the Output panel, and not as used in the Decision Table.
Tip
You can view the procedure name using the Open Definition context menu option on the selected procedure. Result: On execution of the procedure, the physical table data is updated (if no parameters are used) based on the data that you enter in the form of condition values and action values.
Remember
If parameters are being used as actions in a decision table, the physical table is not updated.
248
9. Data Preview
To preview the populated data in the decision table, in the Decision Table editor, from the toolbar, choose Open Data Preview.
Note
Data preview displays: All attributes irrespective of whether they are added as condition or action in the decision table. Parameters only if they are added as condition or action in the decision table. Calculated attributes only if they are added as condition in the decision table.
Restriction
Data preview is supported only if: A decision table is based on physical tables and has at least one parameter as action. A decision table is based on information views and parameter(s) as action.
5.5.1
Changing the Layout of a Decision Table
Use this procedure to change the decision table layout by arranging the condition and action columns. By default, all the conditions appear as vertical columns in the decision table. You can choose to mark a condition as a horizontal condition, and view the corresponding values in a row. The evaluation order of the conditions is such that first the horizontal condition is evaluated and then the vertical ones.
Note
You can only change the layout of a decision table if it has more than one condition. You can select only one condition as horizontal condition.
Procedure
1. 2. In the context menu of the Decision Table editor, choose Change Layout. If you want to view a condition as a horizontal condition, in the Change Decision Table Layout dialog, select Table has Horizontal Condition (HC) checkbox.
Note
By default the first condition in the list of conditions is marked as horizontal. 3. In the Conditions and Actions sections, choose options on the right-hand side of the dialog box to arrange the conditions and actions in the desired sequence.
PUBLIC
249
Note
The available options to arrange the conditions in a sequence are: 4. 5. Move Condition to Top Move Condition Up Move Condition Down Move Condition to Bottom
Choose OK. Save the changes.
Note
You can also set a condition as horizontal from the context menu of the condition in the Output view. You can also arrange the conditions and actions in the desired sequence in the Output view using the respective buttons.
5.5.2
Using Parameters in a Decision Table
You use this procedure to create a parameter that can be used to simulate a business scenario. You can use parameters as conditions and actions in the decision table at design time. Parameters used as conditions, determine the set of physical table rows to be updated based on the condition value that you provide at runtime during procedure call. Parameters used as actions, simulate the physical table without updating to it. The following parameter types are supported: Type
Static List Empty
Description
Use this when the value of a parameter comes from a userdefined list of values. Use this when the value of a parameter could be anything of the selected data type.
Example
Consider a sales order physical table with column headers as follows:
ID Name Supplier Model Price Quantity
If you want to evaluate Discount based on the Quantity and Order Amount, you can create two parameters, Order Amount and Discount. Use Quantity and Order Amount as the condition, and Discount as the action. The sample decision table could be:
Quantity >5 >=10 Order Amount 50000 100000 Discount 10 15
250
Procedure 1. Create a Parameter

1. 2. In the Output pane, right-click the Parameters node. From the context menu, choose New and do the following: a. b. c. d. Enter a name and description. Select the required data type from the dropdown list. Enter the length and scale as required. Choose the required Type from the dropdown list.
Note
If you have selectedStatic List for Type, choose Add in the List of Values section to add values. You can also provide an alias for the enumeration value. e. Choose OK.
2. Use Parameter as Condition or Action

1. 2. In the Output pane, expand the Parameters node. Right-click a parameter, choose Add As Conditions/ Add as Actions.
5.5.3
Using Calculated Attribute in Decision Tables
Context
You use this procedure to create calculated attributes that can be used as conditions in a decision table. You can create a calculated attribute to perform some calculation using the existing attributes, calculated attributes, parameters, and SQL functions.
Procedure
1. 2. In the Output pane, select the Calculated Attributes node. From the context menu, choose New and do the following: a) Enter a name and description.
PUBLIC
251
b) Select the required data type, length, and scale. c) In the expression editor, enter the expression. For example, you can write a formula such as, (NAME = FIRST_NAME + LAST_NAME). This expression is the example of string concatenation function using for deriving the name of a person using the first name and last name values present in the table fields.
Note
You can also assemble the expression by dragging and dropping the expression elements from the editor options below. Only arithmetic operators and SQL functions are supported for expression creation. 3. 4. Choose OK. Add the required calculated attribute as condition.
5.6
Generating Object Documentation
Use this procedure to capture the details of an information model or a package in a single document. This helps you view the necessary details from the document, instead of referring to multiple tables. The following table specifies the details that you can view from the document. Type
Attribute View
Description
General object properties, attributes, calculated attributes (that is, calculated columns of type attribute), data foundation joins, cross references, and where-used General object properties, private attributes, calculated attributes (that is, calculated columns of type attribute), attribute views, measures, calculated measures (that is, calculated columns of type measure), restricted measures (that is, restricted columns), variables, input parameters, data foundation joins, logical view joins, cross references, and where-used General object properties, attributes, calculated attributes, measures, calculated measures, counters, variables, input parameters, calculation view SQL script, cross references, and where-used Sub-packages, general package properties, and list of content objects
Analytic View
Calculation View
Package
Procedure
1. 2. From the Quick Launch page, choose Auto Documentation. In the Select Content Type field, select one of the following options as required:
252
PUBLIC
Option
Model Details Model List
Description
To generate documentation for models such as attribute, analytic, and calculation views. To generate documentation for packages.
3. 4. 5.
Add the required objects to the Target list. Browse the location where you want to save the file. Choose Finish.
PUBLIC
253
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 is 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.
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; END; CALL: Calls a procedure. For example: CALL getOutput (1000, 'EUR', NULL, NULL);
254
SAP HANA Developer Guide Developing Procedures
Tools for Writing Procedures

Use the SQLScript editor, which includes debugging capabilities, to build SQLScript procedures. You can also use the Navigator view in the Modeler perspective to build procedures, but there are no debugging capabilities. You should only use this method: If you need to develop a procedure using a local table type as an input or output parameter. A local table type is created within the SAP HANA Systems procedure tool and for only the current procedure. If you can use a global table type, then use the SQLScript Editor. If you need to edit a procedure previously created in the Navigator view that contains table type parameters.
Related Information SAP HANA SQL and System Views Reference SAP HANA SQLScript Reference SAP HANA R Integration Guide SAP HANA Business Function Library (BFL) Reference SAP HANA Predictive Analysis Library (PAL) Reference Creating and Editing Procedures [page 255] The SAP HANA SQLScript editor allows you to create, edit, and activate procedures.
6.1
Creating and Editing Procedures
The SAP HANA SQLScript editor allows you to create, edit, and activate procedures.
Prerequisites
You have created a development workspace. For more information, see Creating a Repository Workspace [page 50]. You have checked out a package. For more information, see Working with the Repository.
Note
After checking out a package that contains active procedures, you can modify and debug the procedures. You have created and shared a project. For more information, see Using SAP HANA Projects [page 48].
Note
You can also share your project after you create your procedure.
PUBLIC
255
Procedure
1. 2. Go to the Project Explorer view in the SAP HANA Development perspective, right-click on the file name, choose New Other . The New wizard appears. Enter or select the parent folder, enter the file name (the suffix, .procedure, is added automatically), and choose Finish. The icon shows that your procedure is created locally.
Your procedure opens containing the default Create Procedure template. In the Properties view, you see the properties of your procedure, such as Access Mode, Name, and Language. You can also change the default schema that this procedure uses.
Note
You can also create a folder first and add a file. Right-click the project name, choose New Folder . The New Folder wizard appears. Enter or select the project, enter the folder name, and choose Finish. 3. To share your project, right-click the project name, choose wizard appears. Choose Finish. The 4. Team Share Project . The Share Project
icon shows that your procedure is not committed and not activated.
You can begin writing your code inside your new procedure and save it locally. The syntax is checked simultaneously and is highlighted. Auto-completion of the syntax appears as you type. Press Ctrl + Spacebar to get a list of relevant SQLScript statements.
Note
You can only write one stored procedure per file. The file name and the procedure name must be the same. 5. To commit your new procedure or make changes to an existing one, save it, right-click on the procedure, select Team, and select Commit. Your procedure is now synchronized to the repository as a design time object and the icon shows that your procedure is committed.
Caution
The design time presentation of the procedure is currently in XML format that you must not edit. 6. When you have finished writing your procedure and you are ready to activate it, right-click the procedure, choose Team Activate . Your procedure is created in the catalog as a runtime object and the icon shows that your procedure is activated. This allows you and other users to call the procedure and debug it. If an error is detected during activation, an error message appears in the Problems view.
Tip
You can also activate your procedure at the project and folder levels. Related Information The SAP HANA Development Perspective [page 21] SAP HANA Repository Packages and Namespaces [page 56] 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).
256
About SAP HANA SQLScript Defining Local Table Types in Procedures [page 257] You can use table types to define parameters for a procedure, which represent tabular results. These parameters have a type and are either based on a global table (with a reference to a catalog table) or a local table type. SAP HANA SQL and System Views Reference
6.1.1
Defining Local Table Types in Procedures
You can use table types to define parameters for a procedure, which represent tabular results. These parameters have a type and are either based on a global table (with a reference to a catalog table) or a local table type.
Prerequisites
You created or opened a procedure. For more information, see Editing SQLScript.
Procedure
1. 2. Choose the Local Table Types tab. Define your local table type structure using a standard SQL CREATE statement. The local table type is specified using a list of attribute names and primitive data types. For example: CREATE TYPE <type_name> AS TABLE (<column_definition>[{,<column_definition>}...])
Note
You can create multiple CREATE TYPE statements.
Caution
You can only use this local table type in the procedure in which you defined them. 3. Use the local table table type as input and output parameters of the procedure. For example: CREATE PROCEDURE <procedure_name> ( IN|OUT|INOUT <param_name> <type_name>, ... )
Caution
You can only use this tab to define local table types and not for other SQL statements. 4. Choose Save. Commit and activate your procedure to create local table types in the catalog. For more information about committing and activating a procedure, see Editing SQLScript.
PUBLIC
257
Note
The local table types are bound to the procedure artifact, so if the procedure is committed, activated, or deleted, then the same applies to the local table type. For example, if you delete a procedure, the local table type is automatically deleted from the catalog (similar to a drop statement). Related Information CREATE TYPE Table Types
6.2
Creating Procedure Templates
A procedure template is an artifact containing a base script with predefined placeholders for objects such as tables, views and columns. The procedure template enables you to create procedures that contain the same script, but with different values.
Prerequisites
You have created a development workspace. For more information, see Creating a Repository Workspace [page 50]. You have checked out a package. For more information, see Working with the Repository.
Note
After checking out a package that contains active procedures, you can modify and debug the procedures. You have created and shared a project. For more information, see Using SAP HANA Projects [page 48].
Note
You can also share your project after you create your procedure template.
Procedure
1. 2. After you have created your workspace and your project, go to the Project Explorer view in the SAP HANA Development perspective, right-click the file name, choose New File . The New File wizard appears. Enter or select the parent folder and enter the file name using the following naming convention <filename>.proceduretemplate. Choose Finish and choose Save. The Template Script editor opens.
258
PUBLIC
3.
Click the icon from the toolbar in the Template Parameters table to add a parameter to the table. You can rename the parameter and give it a meaningful name. Add the parameters to the table and to the script where they are used as a placeholder for the following objects: Schema name Table name and table column name View name and view column name Procedure name
The parameters can only be used in the procedure body, between the BEGIN and END, and not as part of the procedure header. The parameters must follow the SQL identifier semantics.
Caution
You cannot add a parameter as a placeholder for other objects or syntactic statements. 4. Each parameter should be wrapped using the less than (<) and greater than (>) symbols. For example: SELECT <My_Column> FROM <My_Table>; 5. Commit and activate your procedure template.
Caution
To avoid errors during activation, you must make sure your procedure template is consistent. For example: A parameter that is a placeholder for a table must be in a valid position that is syntactically correct. A parameter name must be identical in the Template Parameters table and the Template Script.
Related Information Creating and Editing Procedures [page 255] The SAP HANA SQLScript editor allows you to create, edit, and activate procedures.
6.2.1
Creating Procedure Template Instances
A procedure template instance is an artifact that is created from a procedure template. It contains the same procedure script and uses specific values for the predefined placeholders in the script. Procedure template instances are coupled with the procedure template, which means any changes that are made to the template are also applied to the template instances. During activation, a template instance is generated as a procedure in the catalog.
Prerequisites
You have created a procedure template or checked out an existing one. For more information, see Creating Procedure Templates [page 258].
PUBLIC
259
Procedure
1. Go to the Project Explorer view in the SAP HANA Development perspective, right-click the file name, choose New Other . The New wizard appears.
Note
The latest version of the procedure template must be checked out to your local workstation before you can select it. 2. 3. Expand the SAP HANA Development folder and select SQLScript Procedure. The New Procedure wizard appears. Enter or select the parent folder and enter the file name (the suffix, .procedure, is added automatically). Choose Advanced, select the Create from procedure template checkbox , and choose Browse. Select the relevant template, choose OK, and choose Finish. 4. In the Procedure Template Instance editor, add a value in the Value column for each parameter, and choose Save.
Note
The value is the string that replaces the parameter in the template script. 5. Commit and activate your procedure template instance.
Note
During activation: The procedure is created in the catalog using the values specified in the instance with the active template in the repository. A reference between the instance and its template is created to link them together.
Related Information Creating and Editing Procedures [page 255] The SAP HANA SQLScript editor allows you to create, edit, and activate procedures. Updating Procedure Templates and Instances [page 260] The procedure template script and its parameters can be modified, which also modifies the template instances that refer to it. Only the template parameter values can be changed in the procedure template instances. Deleting Procedure Templates and Instances [page 261] A procedure template can be deleted if there are no instances linked to it. If there are instances linked to the procedure template, they must be deleted before you can delete the procedure template.
6.2.2
Updating Procedure Templates and Instances
The procedure template script and its parameters can be modified, which also modifies the template instances that refer to it. Only the template parameter values can be changed in the procedure template instances.
260
Procedure
1. 2. 3. To update a procedure template and its instances, double-click the relevant file in the Project Explorer view. The file appears in the Template Script editor. You can change the list of template parameters or the template script. Choose Save. Commit and activate your procedure template.
Note
During activation, the corresponding instances are reactivated and the changes are applied accordingly.
Caution
If an incompatible change is made in the template, the instances are invalid. You have to adjust the instances manually and reactivate them. For example, if a new parameter is added to the template, a value for the new parameter must be specified in all of the existing instances. Related Information Creating and Editing Procedures [page 255] The SAP HANA SQLScript editor allows you to create, edit, and activate procedures.
6.2.3
Deleting Procedure Templates and Instances
A procedure template can be deleted if there are no instances linked to it. If there are instances linked to the procedure template, they must be deleted before you can delete the procedure template.
Procedure
1. 2. To delete a procedure template or a procedure instance, right-click the relevant file in the Project Explorer view, choose Delete, and choose OK. Commit and activate the package.
Note
If an error occurs during activation because there are instances linked to the procedure template that you are trying to delete, then right-click the project name and choose Related Information Creating and Editing Procedures [page 255] The SAP HANA SQLScript editor allows you to create, edit, and activate procedures. Team Resolve .
PUBLIC
261
6.3
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). This allows you to test the correctness of the procedure logic and is not intended for evaluating the performance.
Prerequisites
You have activated your procedures and they must belong to a project on your local workstation. For more information, see Creating and Editing Procedures [page 255]. You have granted debugger privileges to your user: 1. 2. 3. 4. 5. Go to the Navigator view in the SAP HANA Development perspective and open Security Users .
Double-click your user ID. Your system privileges' information will appear. Choose the Object Privileges tab. Select the _SYS_BIC schema and select all of the privileges. Select the DEBUG (SYS) procedure and select the EXECUTE privilege. Choose the Deploy button ( F8 ).
Note
Contact your System Administrator if you are not authorized to modify your user privileges.
Procedure
1. 2. Open the Debug perspective in the SAP HANA studio and select the procedure you want to debug by choosing the relevant tab in the Editor view. Double-click the left vertical ruler to add breakpoints to your procedure. You can see a list of all of the breakpoints in the Breakpoints view.
From the Breakpoints view, you can:
262
PUBLIC
Deselect specific breakpoints or skip all of them. Delete a specific breakpoint or delete all of them. Double-click a breakpoint to see which line it belongs to in the Editor view. See the status of the breakpoint: Pending Valid Invalid and Debug
3.
To start a new debug session, you must first create a debug configuration. Choose Configurations.... The Debug Configurations wizard appears.
Note
You can also go to the Project Explorer view, right-click your procedure, choose SQLScript . 4. In the General tab, select the Procedure to debug radio button, and choose Browse. Select a procedure to debug and choose OK. a) In the Input parameters tab, a list of the parameters and types is displayed for your procedure. You must add values for each parameter in the Value column. Debug As Debug
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.
Note
To debug a procedure that does not require you to define values for input parameters, double-click SQLScript Procedure, enter a name, choose Apply, and choose Debug. b) If you want to control the way your procedures are compiled in debug mode, go to the Advanced tab, and select one of the following radio buttons: All procedures in the call stack to compile all of the nested procedures that are referenced from the procedure stack in debug mode Procedures with breakpoints to compile procedures with breakpoints in debug mode
If you want to save the debug configuration you created and debug your procedure later, choose Apply and Close.
Caution
Selecting Procedures with breakpoints will make the compilation and the procedure execution faster. However, it may prevent you from breaking in a procedure that was compiled in an optimized way. 5. To start your debug session, choose Debug. The debug session will begin and you will see the status of the session in the Debug view. The debugger will stop at the first breakpoint and the session will be suspended until you resume it.
PUBLIC
263
After the server has validated your breakpoints, the status and position of them may change. The position of the breakpoints will be the next valid line where the debugger can stop.If your breakpoint is successfully set, the valid status appears next to it in the Breakpoints view.
Note
You must set breakpoints in the lines you want to break at and resume the session again. You can evaluate your local scalar and table variables in the Variable view. The view shows the values of the scalar variables and the number of rows in each table. 6. To view the content of the tables listed in the Variable view, right-click the table name and choose Open Data Preview. The results will appear in the Preview view. This view will automatically close when you resume your debug session.
Results
The debug session is terminated when the procedure run has finished.
6.4
Debugging an External Session
The SAP HANA SQLScript debugger allows you to debug and analyze procedures that are executed by an external application.
Prerequisites
You know the connection ID, the HANA user, or the HANA user and the application user that your external application uses to connect to the SAP HANA database and to call procedures. You have activated your stored procedures. You have granted debugger privileges to your user: 1. 2. 3. 4. 5. Go to the Navigator view in the SAP HANA Development perspective and open Select the _SYS_BIC schema and select all of the privileges. Select the DEBUG (SYS) procedure and select the EXECUTE privilege. Choose the Deploy button ( F8 ). Security Users .
Double-click your user ID. Your system privileges' information will appear. Choose the SQL Privileges tab.
Note
Contact your System Administrator if you are not authorized to modify your user privileges.
264
Caution
Granting debugger privileges to your user enables you to connect to other user's sessions, and therefore debug procedures that you are not allowed to run and view data that you are not allowed to examine.
Procedure
1. 2. To start a new debug session, you must first create a debug configuration. Choose Configurations.... The Debug Configurations wizard appears. and Debug
In the General tab, select the Debug an external session radio button, and choose SAP HANA System. a) Select the Set filter attributes radio button if you know the connection attributes that your external application uses to connect to the SAP HANA database. Enter HANA User, which is the SAP HANA database user, and optionally enter Application User if your external application sets this attribute for the connection. To start your debug session, choose Debug and trigger the call to the SAP HANA procedure from your external application.
Note
It is not mandatory for the connection to be established before you start the debug session. b) Select the Select a connection after initiating the debugger radio button if you know the connection ID that your external application uses to connect to the SAP HANA database. This option enables you to choose a specific connection after the debugger session has started. If you want to save the debug configuration you created and debug your procedure later, choose Apply and Close. To start your debug session, choose Debug. The Select Connection wizard appears. Choose a connection ID and choose OK. Trigger the call to the SAP HANA procedure from your external application,.
Note
It is mandatory for the connection to be established before you start the debug session. 3. The debug session will begin and you will see the status of the session in the Debug view. The debugger will wait until your procedure is executed on the connection ID that your external application uses. Once your procedure is executed, the debugger will stop at the first breakpoint, and the session will be suspended until you resume it. You will also see the your procedure name in the third and fourth level of the Debug view. After the server has validated your breakpoints, the status and position of them may change. The position of the breakpoints will be the next valid line where the debugger can stop.If your breakpoint is successfully set, the valid status appears next to it in the Breakpoints view.
PUBLIC
265
Caution
If more than one user tries to debug a procedure in the same connection that was either selected or identified by a user name, only the first user that chooses Debug will be able to stop at a breakpoint and debug the procedure.
Note
You must set breakpoints in the lines you want to break at and resume the session again. You can evaluate your local scalar and table variables in the Variable view. The view shows the values of the scalar variables and the number of rows in each table.
6.5
Developing Procedures in the Modeler Editor
Context
To create procedures, use the SQLScript Editor, as described in Creating and Editing Procedures [page 255]. If you need to create procedures with local table types, that is, table types created only for the procedure, perform the steps described in this section.
Procedure
1. On the Quick Launch tab page, choose Procedure. If the Quick Launch page is not open, go to 2. 3. Help Quick Launch .
Enter a name and description for the procedure. For unqualified access in SQL, select the required schema from the Default Schema dropdown list.
Note
If you do not select a default schema, while scripting you need to provide fully qualified names of the catalog objects that include the schema. If you specify a default schema, and write SQL such as select * from myTable, the specified default schema is used at runtime to refer to the table. 4. 5. Select the package in which you want to save the procedure. Select the required option from the Run With dropdown list to select which privileges are to be considered while executing the procedure.
266
Note
There are two types of rights, as follows: Definer's right: If you want the system to use the rights of the definer while executing the procedure for any user. Invoker's right: If you want the system to use the rights of the current user while executing the procedure. 6. Select the required access mode as follows: Access Mode
Read Only Read Write
Purpose
Use this mode to create procedures for fetching table data. Use this mode to create procedures for fetching and updating table data.
7.
Select the language in which you are writing the procedure.
Note
You can choose to create procedures in Read Write mode and make use of L- Lang and R-lang languages only if you have done the repository configuration for the field sqlscript_mode . Two values for sqlscript_mode field exist, DEFAULT, and UNSECURE. By default DEFAULT is assigned which means Read Only mode with non-modifiable access mode and SQLScript as language. To change the configuration, go to administration console -> Configuration tab -> indexserver.ini -> repository -> sqlscript_mode, and assign the required value. 8. 9. Choose Finish. In the function editor pane, write a script for the function using the following data types: Table or scalar data types for input parameters. Table data types for output parameters.
Note
You can only write one function in the function body. However, you can refer to other functions. 10. Choose File Save .
11. Activate the procedure using one of the following options in the toolbar: Save and Activate: Activate the current procedure and redeploy the affected objects if an active version of the affected object exists. Otherwise only the current procedure gets activated. Save and Activate All: Activate the current procedure along with the required and affected objects.
Note
You can also activate the current procedure by selecting the procedure in the Navigator view and choosing Activate in the context menu. For more information about activation, see Activating Objects [page 211].
PUBLIC
267
6.6
Developing Procedures Using Application Functions
To create a procedure, use the SQLScript Editor, as described in Creating and Editing Procedures [page 255]. If you need to develop a procedure using application functions in the Predictive Analysis Library (PAL) or Business Function Library (BFL), you can use the SAP HANA Application Function Modeler.
Note
You need the AFL__SYS_AFLPAL_EXECUTE and AFL__SYS_AFL_AFLBFL_EXECUTE roles to work with PAL and BFL libraries, respectively. These roles should be granted to you by the SYSTEM user.
6.6.1
SAP HANA Application Function Modeler (AFM)
SAP HANA provides commonly used application functions, categorized in PAL and BFL libraries, for use in applications that run on SAP HANA. The SAP HANA Application Function Modeler (AFM) is a graphical editor in SAP HANA Studio that allows you to create procedures using PAL or BFL application functions. With the Application Function Modeler, you can easily add a PAL or BFL function to your AFM file, specify its parameters and input/output table types, and generate the procedure, all without writing any SQLScript code. You can also call the procedure to get the output result of the function, and save the auto-generated SQLScript code for future use.
268
PUBLIC
The SAP HANA Application Function Modeler is embedded in the SAP HANA Development perspective. It contains the following main areas: Editing area: includes two views as follows. Overview view: a graphical editing area for adding and connecting application functions for your procedures. You can drag and drop elements in this view and connect them in a logic way. SQL view: a text area that automatically generates SQLScript code according to the application function settings you make. You can copy or save the code to reuse it in other programs.
Functions view: lists SAP HANA application functions in two categories: BFL and PAL. Generally, you select a function from the list, drag it to the Overview view, and configure its data types and parameters.
PUBLIC
269
6.6.2
Creating an AFM File
You can use the SAP HANA Application Function Modeler to create procedures using PAL or BFL application functions. The first step is to create an AFM (.aflpmml) file.
Procedure
1. 2. In the SAP HANA Development perspective, open your existing SAP HANA project. In the Project Explorer view, right-click on the project name, and choose The New wizard will appear. 3. 4. From the Wizard list, expand SAP HANA Development, select AFL Connector File, and choose Next. Enter or select the parent folder, and enter the file name. New Other .
Note
You only need to enter the base name. The system automatically adds the extension .aflpmml to it. 5. Choose Finish. The new .aflpmml file will appear in the Project Explorer view with the icon.
Note
If your workspace was created in SAP HANA SPS05 or earlier, you will also see a .diagram file and a .aflmodel file. Opening these two files may cause errors. To avoid it, you need to manually activate the Diagram-aflmodel filter as follows: 1. In the Project Explorer view, click the drop-down arrow (View Menu) in the upper-right corner and choose Customize View. 2. In the Available Customizations dialog box, select Diagram-aflmodel filter and choose OK. 6. If your project has not yet been shared, right-click on the project name, select Make settings in the Share Project wizard and choose Finish. Team Share Project .
6.6.3
Adding Application Functions
After creating the AFM file, you can start adding SAP HANA application functions to it.
Context
An application function in PAL or BFL is represented by input data, parameters, and output data. You can add application functions to an AFM file, and define function parameters and input/output table types.
270
PUBLIC
Note
In this release of SAP HANA, each AFM file can only contain one application function.
Tip
For detailed specification on each function's inputs, outputs, and parameters, see SAP HANA Predictive Analysis Library (PAL) and SAP HANA Business Function Library (BFL).
Procedure
1. In the Project Explorer view, double-click the AFM (.aflpmml) file. The SAP HANA Application Function Modeler will appear. 2. 3. In the Properties view, specify the procedure name and the target schema. From the Functions view, select the function you want to add and drag it to the Overview view. The function will appear in the editing area as a graphical element. 4. Move your mouse over the element and choose (Expand).
The function will be expanded to display its input and output elements, as shown below. The plus sign in the element indicates you have not specified data types for it.
5.
Specify the input table types for the function, using one of the following methods. In the Overview view, select the input element. Then in the Properties view, click edit Column Name, SQL Data Type, and Length (optional) for the input table. (Add) to add and
From the SAP HANA Systems view, drag an existing table and drop it onto the input element in the Overview view. The data types of the table are copied to the input element. From the SAP HANA Systems view, drag an existing table to the empty space in the Overview view. Move mouse over the table element and choose (Connection) to connect it to the input element. The table then becomes the input table of the function, and its data types are copied.
Note
It is not necessary to connect input tables to the function in this step. You can specify input tables later before calling a procedure. If the data types match the PAL or BFL specification, the input element changes to a table with a green checkmark:
PUBLIC
271
If the data types are incorrect, the element shows a table with a red exclamation mark:
If you have connected an input table to the function, the input element changes to a graphic shown below, indicating the table has some content in it.
6.
Specify output table types by selecting an output element in the Overview view and adding data type information in the Properties view. When you finish, your output element should look like the following:
Tip
If your graphical elements are not placed in a tidy way, or you want to switch the view from the default horizontal layout to a vertical layout, right-click in the Overview view and choose Auto Layout. Related Information SAP HANA Predictive Analysis Library (PAL) SAP HANA Business Function Library (BFL)
6.6.4
Generating Procedures
After creating the AFM file and adding application functions to it, you can now generate procedures by activating the AFM file.
Procedure
In the Project Explorer view, right-click the AFM file, and choose Team Activate .
272
Results
The AFM file icon changes to , indicating that the file was successfully activated.
In the mean time, a procedure is created for each application function you added in the AFM file. To view these procedures and related table types, go to the Catalog folder in the SAP HANA Systems view.
6.6.5
Calling a Procedure
After activating an AFM file to generate procedures, you can call a generated procedure to get the output result of the PAL or BFL function, and save the auto-generated SQLScript code for future use.
Procedure
1. 2. In the Project Explorer view, double-click the activated AFM file to open it in the SAP HANA Application Function Modeler. If you have not yet specified the input tables for a function, do the following: a) From the SAP HANA Systems view, drag an existing table to the empty space in the Overview view. b) In the Overview view, move mouse over the table element and choose the input element of the function. (Connection) to connect it to
c) If the function requires more than one input table, repeat the above two steps. 3. In the upper right corner of the Application Function Modeler, choose the (Call) icon.
The system runs the procedure and outputs the result. The output element(s) will change to the following, indicating the table now has output data in it.
4.
To view the output data in a table, move your mouse over the output table element and choose the Data Preview) icon. You can also find the tables from the Catalog folder in the Project Explorer view.
(Open
5.
If you want to copy or save the auto-generated SQL code for future use, go to the SQL view and choose the (Copy/Copy All) or (Save As) icon.
PUBLIC
273
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.
7.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.
274
SAP HANA Developer Guide Defining Web-based Data Access
7.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, businessintelligence 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.
7.1.2
Defining 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.
PUBLIC
275
Context
To define the data to expose using an OData service, you must perform at least the following tasks:
Procedure
1. 2. 3. Create a database schema. Create a simple database table to expose with an OData service. 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. 4. 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 SAP HANA studio's Modeler perspective, you must grant the user the required SELECT privilege. call _SYS_REPO.GRANT_SCHEMA_PRIVILEGE_ON_ACTIVATED_CONTENT('select','<SCHEMANAME>','<u sername>');
7.1.3
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:
276
PUBLIC
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. 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 designtime 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
PUBLIC
277
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
It is not possible to use a sequence to create an entry in a table or view exposed by an OData service.
7.1.3.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 [page 303] 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. OData Service Definitions [page 276] 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.
278
7.1.3.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. 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 283] The OData service definition describes how data exposed in an end point can be accessed by clients using the OData protocol.
PUBLIC
279
7.1.4
Creating 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.
Context
An OData service for SAP HANA XS is defined in a text file with the file suffix .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. Prerequisites for the creation of an OData service definition: SAP HANA studio (and client) is installed and configured An SAP HANA database user is available with repository privileges (for example, to add packages) An SAP HANA development system is added to (and available in) SAP HANA studio, for example, in either the SAP HANA Systems view or the SAP HANA Repositories view A working development environment is available including: a repository workspace, a package structure for your OData application, and a shared project to enable you to synchronize changes to the OData project files in the local file system with the repository You have defined the data to expose with the OData application, for example, at least the following: A database schema A database table
Procedure
1. In the shared project you are using for your OData application, use the Project Explorer view to locate the package where you want to create the new OData service definition.
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. 2. Create the file that will contain your OData service definition. In the Project Explorer view, right-click the folder where you want to create the new OData service-definition file and choose 3. New File in the context-sensitive popup menu. 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.
280
PUBLIC
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. 5. Place the valid OData service definition in the root package of the OData application to which it applies. Save, commit, and activate the OData service definition in the SAP HANA repository.
Related Information OData Service Definitions [page 276] 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.
7.1.5
Tutorial: Using the SAP HANA OData Interface
The package you put together to test the SAP HANA OData interface includes all the artifacts you need to use SAP HANA Extended Application Services (SAP HANA XS) to expose an OData collection for analysis and display by client applications.
Prerequisites
Since the artifacts required to get a simple OData application up and running are stored in the repository, it is assumed that you have already performed the following tasks: Create a development workspace in the SAP HANA repository Create a project in the workspace Share the new project
Context
To create a simple OData application, perform the following steps:
Procedure
1. Create a root package for your OData application, for example, helloodata and save and activate it in the repository.
PUBLIC
281
Note
The namespace sap is restricted. Place the new package in your own namespace, which you can create alongside the sap namespace. 2. 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 that you save in the repository and which you must activate. Enter the following code in the HELLO_ODATA.hdbschema file: schema_name="HELLO_ODATA"; 3. Create the database table that contains the data to be exposed by your OData service definition, for example, otable.hdbtable. The database table is a flat file with the file extension .hdbtable that you save in the repository and which you must activate. 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"]; 4. Grant SELECT privileges to the owner of the new schema. After activation in the repository, the 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 in the SAP HANA studio's Modeler perspective, you must grant the user the required SELECT privilege. a) In the SAP HANA studio SAP HANA Systems view, right-click the SAP HANA system hosting the repository where the schema was activated and choose SQL Console in the context-sensitive popup menu. b) In the SQL Console, execute the statement illustrated in the following example, where <SCHEMANAME> is the name of the newly activated schema, and <username> is the database user ID of the schema owner: call _SYS_REPO.GRANT_SCHEMA_PRIVILEGE_ON_ACTIVATED_CONTENT('select','<SCHEMANAME>', '<username>'); 5. Create an application descriptor for your new OData application in your root OData package helloodata. The application descriptor (.xsapp) is the core file that you use to define an application's availability within SAP HANA application. The .xsapp file sets the point in the application-package structure from which content will be served to the requesting clients.
282
Note
The application-descriptor file has no content and no name; it only has the extension .xsapp. 6. 7. Save, commit, and activate the application-descriptor file in the repository. Create an application-access file for your new OData application and place it in your root OData package helloodata. The application-access file enables you to specify who or what is authorized to access the content exposed by the application.
Note
The application-access file has no name; it only has the extension .xsaccess. Enter the following content in the .xsaccess file for your new OData application: { } 8. 9. "exposed" : true
Save, commit, and activate the application-access file in the repository. Create an OData service-definition file and place it in your root OData package helloodata. 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: Enter the following content in the hello.xsodata OData service-definition file: service { "helloodata::otable"; }
10. Save, commit, and activate the OData service-definition file in the repository. 11. Open a browser and enter the following URL. http://<hana.server.name>:80<HANA_instance_number>/helloodata/hello.xsodata
7.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
PUBLIC
283
Aggregation Parameter Entity Sets
7.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: http://localhost:8002/sample/odata/empty.xsodata
http://localhost:8002/sample/odata/empty.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".
7.1.6.2
OData Namespace Definition
By default, as shown in the metadata file of an empty OData service, the namespace of the generated Schema is created by concatenating the package name of the .xsodata file with the file name, and separating the concatenated names with a dot. You can specify your own namespace by using the namespace keyword:
284
Service definition sample.odata:namespace.xsodata service namespace "my.namespace" {} The resulting service metadata document has the specified schema namespace: http://localhost:8002/sample/odata/namespace.xsodata/$metadata
7.1.6.3
OData Object Exposure
There are two ways of exposing SAP HANA objects. You can either specify the repository design-time name or the database-object runtime name (with database schema). Although both variants are supported, the preferred method is the exposure via the repository design-time name. It has the advantage that the OData service is automatically updated, if the underlying repository object changes. The support for database objects is mainly intended for existing or replicated objects that do not have a related repository design-time object. In the examples provided to illustrate object exposure, the following definition of a table applies: Table definition sample.odata:table.hdbtable table.schemaName = "ODATASAMPLES"; table.tableType = COLUMNSTORE; table.columns = [ {name = "ID"; sqlType = INTEGER;}, {name = "Text"; sqlType = NVARCHAR; length=1000;}, {name = "Time"; sqlType = TIMESTAMP;} ]; table.primaryKey.pkcolumns = ["ID"];
Repository Objects
If the object to expose via an OData service is created during an activation in the repository, then it has a repository design-time representation. Examples for those objects are tables, SQL views and calculation views. An example for exposing the table above is shown in the next service defintion.
PUBLIC
285
Service definition sample.odata:repo.xsodata service { "sample.odata::table" as "MyTable"; } This service definition exposes a table defined in the .hdbtable 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, here "table". http://localhost:8002/sample/odata/repo.xsodata
http://localhost:8002/sample/odata/repo.xsodata/$metadata
286
PUBLIC
All information about the table, for example, the properties, the data types, and the primary key, is gathered from the database catalog.
Database Objects
Caution
Do not use catalog objects if a repository design-time object is available, as changes in the catalog object are not automatically reflected in the OData service. 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 { "ODATASAMPLES"."sample.odata::table" as "MyTable"; } 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. The collection in the service catalog and the EntityType that is created in the metadata document is exactly the same as for repository objects.
7.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: http://localhost:8002/sample/odata/with.xsodata/$metadata
PUBLIC
287
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: 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://localhost:8002/sample/odata/without.xsodata/$metadata
7.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 by denoting a set of existing columns or by generating a key. 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 { "name": "view", "schema": "ODATASAMPLES", "query": "SELECT * FROM \"ODATASAMPLES\".\"sample.odata::table\""
288
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"); } The created 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: http://localhost:8002/sample/odata/explicitkeys.xsodata/$metadata
Caution
The OData infrastructure cannot check whether your specified keys are unique. So be careful when choosing keys.
PUBLIC
289
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. Service definition sample.odata:generatedkeys.xsodata service { "sample.odata::view" as "MyView" key generate local "GenID"; } http://localhost:8002/sample/odata/generatedkeys.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.
7.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 table.schemaName = "ODATASAMPLES"; table.tableType = COLUMNSTORE; table.columns = [ {name = "ID"; sqlType = INTEGER; nullable = false;},
290
{name = "RecruitID"; sqlType = VARCHAR; nullable = true;} ]; table.primaryKey.pkcolumns = ["ID"]; Table definition: sample.odata:order.hdbtable table.schemaName = "ODATASAMPLES"; table.tableType = COLUMNSTORE; table.columns = [ {name = "ID"; sqlType = INTEGER; nullable = false;}, {name = "CustomerID"; sqlType = INTEGER; nullable = false;} ]; table.primaryKey.pkcolumns = ["ID"]; There is one relationship order.CustomerID to customer.ID and one relationship customer.RecruitID 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" 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 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://localhost:8002/sample/odata/assocsimple.xsodata/$metadata
PUBLIC
291
The second association is similar to the first one and is shown in the following listing: association "Customer_Recruit" 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 table.schemaName = "ODATASAMPLES"; table.tableType = COLUMNSTORE; table.columns = [ {name = "KnowingCustomerID"; sqlType = INTEGER; nullable = false;}, {name = "KnownCustomerID"; sqlType = INTEGER; nullable = false;}
292
PUBLIC
]; table.primaryKey.pkcolumns = ["KnowingCustomerID","KnownCustomerID"]; 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: tp://localhost:8002/sample/odata/assoccomplex.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 "*"; }
PUBLIC
293
The example above says that it is possible to navigate from Customers over the association Customer_Order via the NavigationProperty named "HisOrders". 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://localhost:8002/sample/odata/assocnavself.xsodata/$metadata
7.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 nonaggregated properties. Furthermore, aggregated columns cannot be used in $filter, and aggregation is only possible with generated keys.
294
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 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 table.schemaName = "ODATASAMPLES"; table.tableType = COLUMNSTORE; table.columns = [ {name = "Month"; sqlType = INTEGER; nullable = false;}, {name = "Year"; sqlType = INTEGER; nullable = false;}, {name = "Amount"; sqlType = INTEGER; nullable = true;} ]; table.primaryKey.pkcolumns = ["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.
7.1.6.8
OData Parameter Entity Sets
SAP HANA calculation views and analytic 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 both calculation views and analytic views by adding parameters via entity to the entity, as illustrated in the following service-definition example: service { "sample.odata::calc" as "CalcView"
PUBLIC
295
keys generate local "ID" parameters via entity;
During activation, the 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. 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.
7.1.6.9
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. There 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 to be executed before or after the operation, or before or after the commit. You can therefore specify a maximum of four validation exits per operation. They are registered for events with the respective keywords before, after, precommit and 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: Table 14: Execution Order of Exit Validation/Modification Scripts OData Insert Type Single Insert Batch Insert Script Execution Order before, using, after, precommit, postcommit 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:
296
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. Table 15: Entity Write Operations Script Type before, after, precommit, using postcommit Create IN new EntityType, OUT error ErrorType IN new EntityType Update IN new EntityType, IN old EntityType, OUT error ErrorType IN new EntityType, IN old EntityType Delete IN old EntityType, OUT error ErrorType IN old EntityType
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. Table 16: Link Write Operations Script Type before, after, precommit, using postcommit Create, Update, Delete IN principal PrincipalEntityType, IN dependent DependentEntityType, OUT error ErrorType 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 remains empty. Although the structure of the table type ErrorType is not restricted, any columns with special names are mapped to common information in the OData error response. Table 17: Error Message Content Column Name HTTP_STATUS_CODE ERROR_MESSAGE Type INTEGER NVARCHAR Value Range 400-417 (default: 400) Error Response Information The HTTP response status code The error message (<message>)
PUBLIC
297
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 .hdbstructure file suffix, for example error.hdbstructure: table.schemaName = "ODATASAMPLES"; table.columns = [ {name = "HTTP_STATUS_CODE"; sqlType = INTEGER;}, {name = "ERROR_MESSAGE"; sqlType = NVARCHAR; length = 100;}, {name = "DETAIL"; sqlType = NVARCHAR; length = 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 "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;
7.1.6.10
Tutorial: Creating a Validation Exit
Use a custom validation exit to run 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.hdbstructure
298
PUBLIC
Context
You can use a custom validation exit to run server-side verification and data-consistency checks for an OData modification operation. In this tutorial, you see how to register a script for the 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, 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. 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 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. 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: create procedure "ODATA_TEST"."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;
PUBLIC
299
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); }
7.1.6.11
Tutorial: Creating a Modification Exit
Register 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 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"];
300
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. 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: create 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; }
7.1.7
OData Service Definition Language Syntax
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 namespace quotedstring :=service [annotations] :='service' [namespace] body :='namespace' quotedstring :=quote string quote
PUBLIC
301
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 :='key' ( 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' 'entity' [parameterentitysetname] [parametersresultsprop] 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 principalend dependentend [( assoctable | storage )] associationdef :='association' assocname 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] )
302
PUBLIC
nostorage storageend annotations annotationsbody annotationscontent annotationconfig annotation
:='no' 'storage' :='storage' 'on' ( 'principal' | 'dependent' ) :='annotations' annotationsbody :='{' annotationscontent '}' :=annotationconfig [annotationscontent] :='enable' annotation :='OData4SAP'
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. 3. 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. 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. 4. 5. 6. The fromend in a naventry must be specified if the endtype is the same for both the principalend and the dependentend of an association. The number of joinproperties in the principalend must be the same as in the dependentend. 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. 9. aggregates can only be applied in combination with keygenerated. 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".
7.1.8
OData Service Definition: SQL-EDM Type Mapping
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.
PUBLIC
303
Note
The OData implementation in SAP HANA XS supports only those SQL types listed in the following table. Table 18: SAP HANA SQL to OData EDM Type Mapping SAP HANA SQL Type Time Date SecondDate LongDate Timestamp TinyInt SmallInt Integer BigInt SmallDecimal Decimal Real Float Double Varchar NVarchar Char NChar Binary Varbinary OData EDM Type Edm.Time Edm.DateTime Edm.DateTime Edm.DateTime Edm.DateTime Edm.Byte Edm.Int16 Edm.Int32 Edm.Int64 Edm.Decimal Edm.Decimal Edm.Single Edm.Single Edm.Double Edm.String Edm.String Edm.String Edm.String Edm.Binary 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;}
304
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"/>
7.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
7.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.
PUBLIC
305
7.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 applicationprogramming 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 mult-idimensional 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.
7.2.2
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.
306
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 {*}
7.2.3
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 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)
7.2.4
Multidimensional Expressions (MDX)
Multidimensional Expressions (MDX) is a language you can use to query multidimensional data 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.
PUBLIC
307
Note
MDX is an open standard. However, SAP has developed extensions to MDX that are designed to enable faster and more efficient access to multidimensional data, for example, to serve specific SAP HANA application requirements and to optimize the resultset 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 key attributes of attribute views are linked to private attributes in an analytical 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 levelbased 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 [MINI_C1_VAR] Where [Measures].[M2_1_M3_CONV] SAP VARIABLES [VAR_VAT] including 10, [VAR_K2] including 112, [VAR_TARGET_CURRENCY] including 'EUR',
7.2.5
MDX Functions
MDX in SAP HANA supports a variety of standard MDX functions. Table 19: Supported MDX Functions Function Aggregate Ancestor Description Returns a calculated value using the appropriate aggregate function, based on the aggregation type of the member. Returns the ancestor of a member at a specified level or at a specific distance away in the hierarchy.
308
PUBLIC
Function 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
Description Returns a set of all ancestors of a member at a specified level or at a specific distance away in the hierarchy. Returns the set of the ascendants of the member. Returns the average value of a numeric expression evaluated over a set. Returns a specified number of items from the bottom of a set, optionally sorting the set first. Returns the children of a member. Returns the last sibling among the descendants of a member at a specified level. Counts the number of members in the tuple. Returns the child member with the same relative position under a parent member as the specified child member. Returns the cross product of two sets. Returns the current member along a hierarchy. Returns the default member of a hierarchy. Returns the set of descendants of a member at a specified level or at a specific distance away in the hierarchy. Returns the hierarchy that contains a specified member or level. Returns a hierarchy specified by a numeric or string expression. Returns a set, removing duplicate tuples from a specified set. Returns the number of distinct tuples in a set. Drills down the members of a set one level below the lowest level represented in the set, or to one level below an optional level of a member represented in the set. Drills down the members of a specified count of bottom members of a set, at a specified level, to one level below. Drills down a specified count of top members of a set, at a specified level, to one level below. Drills down the members in a specified set that are present in a second specified set. Drills down the members in a specified set that are present in a second specified set, limiting the result set to a specified number of bottommost members. Drills down the members in a specified set that are present in a second specified set, limiting the result set to a specified number of topmost members. Drills up the members of a set that are below a specified level. Drills up the members in a specified set that are present in a second specified set. Finds the difference between two sets, optionally retaining duplicates. Returns the set resulting from filtering a set based on a search condition.
PUBLIC
309
Function FirstChild FirstSibling Generate
Description Returns the first child of a specified member. Returns the first child of the parent of a specified member. Applies a set to each member of another set, and then joins the resulting sets by union. Alternatively, this function returns a concatenated string created by evaluating a string expression over a set. Returns the first specified number of elements in a set. Orders the members of a specified set in a hierarchy in natural or, optionally, postnatural order.
Head Hierarchize Hierarchy Instr Intersect IsAncestor IsGeneration IsLeaf IsSibling Item IIF Lag LastChild LastPeriods LastSibling Lead Leaves
The InStr function finds the starting location of a substring within a specified string. Returns the intersection of two sets, optionally retaining duplicates. Returns true if the first member specified is an ancestor of the second member specified, else returns false. Returns true if the member specified is a leaf, else returns false. Returns true if the first member specified is an ancestor of the second member specified, else returns false. Returns true if the first member specified is an sibling of the second member specified, else returns false. If an integer is specified, the Item function returns the tuple that is in the zerobased position specified by Index. Returns one of values determined by a logical test. Returns the member that is a specified number of positions prior to a specified member along the dimension of the member. Returns the last child of a specified member. Returns a set of members prior to and including a specified member. Returns the last child of the parent of a specified member. Returns the member that is a specified number of positions following a specified member along the dimension of the member. If a dimension name is specified, returns a set that contains the leaf members of the key attribute for the specified dimension.If a dimension name is not specified, the function returns a set that contains the leaf members of the entire cube. The Left function returns a string of a specified number of characters from the left side (beginning) of a specified string. Returns the level of a member. Returns the level whose zero-based position in a dimension is specified by a numeric expression. Returns the maximum value of a numeric expression evaluated over a set.
Left Level Levels Max
310
PUBLIC
Function Member_caption Members MembersAscendantsDesc endants Mid Min MTD Name NextMember NOT OpeningPeriod OR Ordinal ParallelPeriod Parent PeriodsToDate PrevMember Properties QTD Range
Description Returns the caption of a member Returns the set of all members in a specified hierarchy. Returns the set of specified members in a given hierarchy. The Mid function returns a substring of a string argument. Returns the minimum value of a numeric expression evaluated over a set Returns a set of members from the Month level in a Time dimension starting with the first period and ending with a specified member. Returns the name of a specified hierarchy or member. Returns the next member in the level that contains a specified member. Performs a logical negation on a numeric expression. Returns the first sibling among the descendants of a specified level, optionally at a specified member. Performs a logical disjunction on two numeric expressions. Returns the zero-based ordinal value associated with a specified level. Returns a member from a prior period in the same relative position as a specified member. Returns the parent of a specified member. Returns a set of members (periods) from a specified level starting with the first member and ending with a specified member. Returns the previous member in the level that contains a specified member. Returns a string containing the value of the specified member property. Returns a set of members from the Quarter level in a Time dimension starting with the first period and ending with a specified member. Performs a set operation that returns a naturally ordered set, with the two specified members as endpoints, and all members between the two specified members included as members of the set The Right function returns a string of a specified number of characters from the right side (end) of a specified string. Returns the set of siblings of a specified member, including the member itself. Returns a member from a string expression in MDX format. Constructs a set from a specified string expression in MDX format. Constructs a tuple from a specified string expression in MDX format. Returns a value from a string expression Returns a subset of tuples from a specified set.
Right Siblings StrToMember StrToSet StrToTuple StrToValue Subset
PUBLIC
311
Function Sum Tail TopCount Union UniqueName WTD YTD
Description Returns the sum of a numeric expression evaluated over a specified set. Returns the last specified number of elements in a set. Returns a specified number of items from the topmost members of a specified set, optionally ordering the set first. Performs a set operation that returns a union of two sets, removing duplicate members. Returns the unique name of a specified hierarchy. Returns a set of members from the Week level in a Time dimension starting with the first period and ending with a specified member. Returns a set of members from the Year level in a Time dimension starting with the first period and ending with a specified member.
7.2.6
MDX Extensions
SAP HANA supports several extensions to the MDX language, for example, additional predefined functions and support for variables.
7.2.6.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 ( [MDX_TEST_10_DISTRIBUTION_CHANNEL].[MDX_TEST_10_DISTRIBUTION_CHANNEL].[All]. [(all)], 1, SELF_AND_BEFORE ) DIMENSION PROPERTIES SIBLING_ORDINAL ON ROWS FROM MDX_TEST_10_ITELO_SALES_DATA
312
7.2.6.2
MembersAscendantsDescendants Function
SAP HANA includes a new function called MembersAscendantsDescendants 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([JUICE_TIME].[TimeHier].[QUARTER].[3]: [JUICE_TIME].[TimeHier].[QUARTER].[4], MEMBERS_AND_ASCENDANTS_AND_DESCENDANTS )) } ON ROWS FROM [JUICE]
Example
SELECT { [Measures].[SALES] } ON COLUMNS, NON EMPTY { Hierarchize( MembersAscendantsDescendants([JUICE_TIME].[TimeHier].[QUARTER].[3]: [JUICE_TIME].[TimeHier].[QUARTER].[4], ONLY_ASCENDANTS )) } ON ROWS FROM [JUICE]
7.2.6.3
Variables
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.
PUBLIC
313
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 specifies a single value for variables VAR_KAT, VAR_K2, and VAR_TARGET_CURRENCY. SELECT FROM [MINI_C1_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 [MINI_C1_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 BIMC_VARIABLE_ODBO (virtual table)
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.
314
7.2.7
Defining 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. 2. 3. 4. Create a simple database schema. Create a simple database table to expose with an XMLA service. If required, create a simple database view to expose with an XMLA service. Grant select privileges to the tables and views to be exposed with the XMLA service.
7.2.8
Creating 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.
Context
An XMLA service for SAP HANA XS is defined in a text file with the file suffix .xsxmla, for example, XMLASrvDef.xsxmla. The file resides in the package hierarchy of the XMLA application and must contain the entry service {*}, which generates an operational XMLA service. Prerequisities for the creation of an XMLA service definition: SAP HANA studio and client is installed and configured An SAP HANA database user is available with repository privileges (for example, to add packages) An SAP HANA development system is added to (and available in) SAP HANA studio, for example, in either the SAP HANA Systems view or the SAP HANA Repositories view A working development environment is available that includes: a repository workspace, a package structure for your XMLA application, and a shared project to enable you to synchronize changes to the XMLA project files in the local file system with the repository Data is available to expose using the XMLA interface.
PUBLIC
315
Procedure
1. In the shared project you are using for your XMLA application, use the Project Explorer view to locate the package where you want to create the new XMLA service definition.
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. 2. Create the file that will contain your XMLA service definition. In the Project Explorer view, right-click the folder where you want to create the new XMLA service-definition file and choose 3. New File in the context-sensitive popup menu displayed. 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{*} 4. 5. Place the valid XMLA service definition in the root package of the XMLA application. Save, commit, and activate the XMLA service definition in the SAP HANA repository.
7.2.9
Tutorial: Using 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
Since the artifacts required to get a simple XMLA service up and running are stored in the repository, make sure that you read through and comply with the following prerequisites: You have a development workspace in the SAP HANA repository You have created a dedicated project in the repository workspace You have shared the new project 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
316
PUBLIC
Context
To send an XMLA query to SAP using the XMLA interface provided by SAP HANA XS, perform the following steps:
Procedure
1. Create a root package for your XMLA interface test, for example, helloxmla and save and activate it in the repository.
Note
The namespace sap is restricted. Place the new package in your own namespace, which you can create alongside the sap namespace. 2. Create an application descriptor for your new XMLA test in your root XMLA package helloxmla. The application descriptor (.xsapp) is the core file that you use to define an application's availability within SAP HANA. The .xsapp file sets the point in the application-package structure from which content will be served to the requesting clients.
Note
The application-descriptor file has no content and no name; it only has the extension .xsapp. 3. 4. Save, commit, and activate the application-descriptor file in the repository. Create an application-access file for your new XMLA test and place it in your root XMLA package helloxmla. The application-access file enables you to specify who or what is authorized to access the content exposed by the application.
Note
The application-access file has no name; it only has the extension .xsaccess. Ensure the application content is exposed to HTTP requests by entering the following command in the .xsaccess file for your new XMLA test: { } 5. 6. "exposed" : true
Save, commit, and activate the application-access file in the repository. Create an XMLA service-definition file and place it in your root XMLA package helloxmla. The XMLA service-definition file has the file extension .xsxmla, for example, hello.xsxmla and must be located in the root package of the XMLA application: Enter the following content in the hello.xsxmla XMLA service-definition file: service {*}
7.
Save, commit, and activate the XMLA service-definition file in the repository.
PUBLIC
317
8.
Test the connection to the SAP HANA XS Web server. 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. 9. 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. 10. Configure your client to send an XMLA query to SAP HANA.
318
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.
8.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.
8.2
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 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
SAP HANA Developer Guide Writing Server-Side JavaScript Code
PUBLIC
319
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 httpserver section of the Configuration tab and set it to true. xsengine.ini
8.2.1
JavaScript Editor
You can write server-side JavaScript using the SAP HANA studio JavaScript editor, which provides syntax validation, code highlighting and code completion. The SAP HANA studio's JavaScript editor includes the JSLint open-source library, which helps to validate JavaScript code. The editor highlights any code that does not conform to the JSLint standards. To configure the JSLint library and determine which validations are performed, go to: Windows Preferences
JSLint . In the preferences window, each JSLint setting is followed by the corresponding JSLint command name, which you can use to lookup more information on the JSLint Web site.
Tip
To disable all JSLint validations for files in a specific project, right-click the project and choose Disable JSLint. Related Information http://www.jslint.com/lint.html
8.2.2
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)
320
PUBLIC
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
Related Information SAP HANA Security Guide SAP HANA SQL and System Views Reference SSL/HTTPS [page 322] 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). Injection flaws [page 323] 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. Cross-site scripting (XSS) [page 324] 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 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. Broken authentication and session management [page 324] 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. Insecure direct object references [page 325] 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. Cross-site request forgery (XSRF) [page 326]
PUBLIC
321
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. Incorrect security configuration [page 327] 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 cryptographic storage [page 328] 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. Missing restrictions on URL Access [page 328] 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. Insufficient transport layer protection [page 329] 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. XML processing issues [page 330] 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.
8.2.2.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).
322
Related Information SAP HANA Security Guide
8.2.2.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.
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=?' ); pstmt.setInt(1, $.request.parameters.get("id"), 10); var rs = pstmt.executeQuery();
PUBLIC
323
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. Related Information SAP HANA Security Guide SAP HANA SQL and System Views Reference
8.2.2.3
Server-Side JavaScript: Cross-Site Scripting
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 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
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. Related Information SAP HANA Security Guide
8.2.2.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.
324
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. Related Information SAP HANA Security Guide
8.2.2.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.
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. Related Information SAP HANA Security Guide
PUBLIC
325
8.2.2.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 serverside. 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
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"
326
PUBLIC
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> Related Information SAP HANA Security Guide
8.2.2.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.
PUBLIC
327
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. Related Information SAP HANA Security Guide
8.2.2.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.
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. Related Information SAP HANA Security Guide
8.2.2.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.
328
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. Related Information SAP HANA Security Guide
8.2.2.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. Related Information SAP HANA Security Guide
8.2.2.11
Server-Side JavaScript: Invalid Redirection
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) 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.
PUBLIC
329
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 whitelist. Related Information SAP HANA Security Guide
8.2.2.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 coming form 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. 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.
Related Information SAP HANA Security Guide
330
PUBLIC
8.2.3 Code
Tutorial: Writing Server-Side JavaScript Application
SAP HANA Extended Application Services (SAP HANA XS) 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 including SAPUI5 applications and mobile clients.
Context
Since JavaScript programs are stored in the SAP HANA repository, the steps in this task description assume that you have already created a workspace and a project (of type XS Project), and that you have shared the project with other members of the development team. To write a server-side JavaScript application, you must perform the following high-level steps.
Procedure
1. 2. Create a root package for your application, for example, helloxsjs. Create an application descriptor for your application and place it in the root package you created in the previous step. The application descriptor is the core file that you use to describe an application's availability within SAP HANA Extended Application Services. The application-descriptor file has no contents and no name; it only has the file extension .xsapp.
Note
For backward compatibility, content is allowed in the .xsapp file but ignored. 3. Create an application-access file and place it in the package to which you want to grant access. The application-access file does not have a name; it only has the file extension .xsaccess. The contents of the .xsaccess file must be formatted according to JavaScript Object Notation (JSON) rules and associated with the package the file belongs to. The rules defined in the .xsaccess file apply to the package it resides in as well as any subpackages lower in the package hierarchy. 4. 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. 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.
PUBLIC
331
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. 5. Create the server-side JavaScript files that contain the application logic. You can use the available JavaScript APIs (for example, the database or request-processing API) to expose authorized data to client requests. 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. $.response.contentType = "text/plain"; $.response.setBody( "Hello, World!"); 6. Check the layout workspace. Your application package structure should have a structure that looks like the following example: .
helloxsjs
.xsapp .xsaccess hello.xsjs
7. 8.
Save and activate your changes and additions. View the results. The SAP HANA XS Web server enables you to view the results immediately after activation in the repository, for example: http://dbhost:80<DB_Instance_Number>/helloxsjs/hello.xsjs
8.3
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 serverside 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);
332
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
8.3.1
Writing 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. In SAP HANA XS, server-side JavaScript libraries have the file extension .xsjslib, for example greetLib.xsjslib. The following 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. It is important to remember where the JavaScript library is located; you have to reference the package path when you import the library. 3. Activate your new library in the repository so that it is available for import by other JavaScript applications.
PUBLIC
333
8.3.2
Importing 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. Use the $.import function, as follows: $.import("<package_your_library_was_deployed>","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
334
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.
8.4
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: Database API 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 API Enables outbound access to a defined HTTP destination that provides services which an application can use. For example, you can read the connection details for an HTTP destination, request data, and set details of the response body. Request-Processing API 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.
Database API
The following example shows how to use the database API to prepare and execute an SQL statement. The response to the SQL query is then prepared and displayed in a Web browser. var conn = $.db.getConnection(); var pstmt = conn.prepareStatement( "select * from DUMMY" ); var rs = pstmt.executeQuery(); $.response.contentType = "text/plain"; if (!rs.next()) { $.response.setBody( "Failed to retreive data" );
PUBLIC
335
$.response.status = $.net.http.INTERNAL_SERVER_ERROR; } else { $.response.setBody("Response: " + rs.getString(1)); } rs.close(); pstmt.close(); conn.close(); 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 that contains the information requested in the specified query (HOST, system ID, instance number...) in the order specified. After returning the requested information, the connection is closed. If it not possible to establish a connection with SAP HANA, then display the error message "Unable to retrieve system." and close the connection. var conn; try { conn = $.db.getConnection(); var query = 'SELECT SYSTEM_ID, HOST, SID, INSTANCE, PORT, USER, PASSWORD, COMMENT FROM ' + 'ACME_XSTC.com.acme.adm.xstc.db::SYSTEM WHERE SYSTEM_ID = ?'; var pstmt = conn.prepareStatement(query); pstmt.setInteger(1, id); var rs = pstmt.executeQuery(); if (rs.next()) { return { id : rs.getInteger(1), host : rs.getNString(2), sid : rs.getString(3), instance : rs.getDecimal(4), port : rs.getDecimal(5), user : rs.getNString(6), password : rs.getNString(7), comment : rs.getNString(8) }; } } catch (ex) { $.trace.error("Unable to retrieve system. " + ex.toString()); ex.source = fileName; throw ex; } finally { if (conn) { conn.close(); } }
Outbound API
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);
336
PUBLIC
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 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 !"); 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;
PUBLIC
337
} else { // unsupported method $.response.status = $.net.http.INTERNAL_SERVER_ERROR; } Related Information SAP HANA XS JavaScript Reference Maintaining HTTP Destinations [page 88] 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.
8.4.1
Tutorial: Using the XSJS Outbound API
The application package you put together in this tutorial includes all the artifacts you need to enable your serverside JavaScript application to use the Outbound Connectivity API to request and obtain data via HTTP from a service running on a remote host.
Prerequisites
Since the artifacts required to get the JavaScript application up and running are stored in the repository, it is assumed that you have already performed the following tasks: Create a development workspace in the SAP HANA repository Create a project in the workspace Share the new project The HTTPDestViewer SAP HANA 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. Create a package for the SAP HANA XS application that will use the HTTP destination you define in this tutorial. For example, create a package called testApp. Make sure you can write to the schema where you create the new application.
338
a) Start the SAP HANA studio and open the SAP HANA Development perspective. b) In the SAP HANA Systems view, right-click the node in the package hierarchy where you want to create the new package and, in the pop-up menu that displays, choose Packages... c) In the New Package dialog that displays, enter the details of the new package (testApp) that you want to add and click OK. 2. 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
Place the HTTP destination configuration in the same package as the application that uses it. An application cannot reference an HTTP destination configuration that is located in another application package. a) Create a plain-text file called yahoo.xshttpdest and open it in a text editor. b) 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; useProxy = false; proxyHost = ""; proxyPort = 0; timeout = 0; c) Save, commit, and activate the file. 3. View the activated HTTP destination. You can use the SAP HANA XS Administration Tool to check the contents of an HTTP destination configuration.
Note
Note
PUBLIC
339
c) In the XS Applications tab, expand the nodes in the application tree to locate the application testApp. d) Choose yahoo.xshttpdest to display details of the HTTP destination . 4. Create an 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) Create a plain-text file called sapStock.xsjs and open it in a text editor. b) 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
340
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) { 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"; var res = parseInt(response.body.asString()) * amount; $.response.setBody(amount + " of your " + stock + " are worth: " + res);
c) Save, commit, and activate the file. 5. Call the service provided by the application sapStock.xsjs. a) Open a Web browser. b) Enter the URL that calls your sapStock.xsjs application. http://<XS_Webserver>:80<SAPHANA_InstanceNr>/testApp/sapStock.xsjs? &amount=100&stock=SAP.DE <XS_Webserver> Name of the system hosting the Web server for the SAP HANA XS instance where your sapStock.xsjs application is located. <SAPHANA_InstanceNr> Number of the SAP HANA instance where the SAP HANA XS Web server is running, for example, 00
PUBLIC
341
6.
Change the details specified in the URL used to run the application. You can enter different values for the parameters &amount and &stock in the URL: &amount=250 Change the number of stocks to check from 100 to 250 &stock=SAP.DE Change the name of stock to check from SAP.DE to MCRO.L
Related Information Maintaining HTTP Destinations [page 88] 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.
8.5
The SQL Connection Configuration File
In SAP HANA Extended Application Services (SAP HANA XS), you use the SQL-connection configuration file to enable the execution of SQL statements from inside your 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 JavaScript application with credentials that are different to the credentials of the requesting user, SAP HANA XS enables you to define the 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.
342
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. You can activate repository files at any point in time.
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. sap.hana.sqlcon:AdminConn.xssqlcc { } "description" : "Admin SQL connection"
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.
Example
Calling the SAP HANA XS SQL-Connection Configuration File 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"); 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 database user. To maintain this user mapping, SAP HANA XS provides a dedicated application (the SQL Connection Configuration Application), which is pre-installed and accessible under the URL http://
PUBLIC
343
<host>:<port>/sap/hana/xs/sqlcc/. You can grant one of the following roles for users who want to use the SQL Connection Configuration Application to view or maintain the available SQL connection configurations: sap.hana.xs.sqlcc::Viewer Required to display the available SQL Connections and the current user mapping sap.hana.xs.sqlcc::Administrator Required to change the user mapping
Troubleshooting Tips
If you are having problems implementing the SQL connection feature using an .xssqlcc configuration, check the following: Make sure that you grant the necessary user the activated role (for example, sap.hana.xs.sqlcc::Administrator). You grant roles (or privileges) in the SAP HANA studio Administration Console perspective. In the SAP HANA Systems view, choose Security Users The granting user must have the object privilege EXECUTE on the procedure GRANT_ACTIVATED_ROLE. Make sure that the SQL-role configuration file (.xssqlcc) you create is located in the same package as the application that references it. 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 ( application_container Administration Configuration Tab xsengine.ini 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.
8.6
Connection-language Settings 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';
344
PUBLIC
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 AcceptLanguage 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" 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>
PUBLIC
345
The called XSJS page replaces the $UI5_LANGUAGE$ parameter with the value stored in $.session.language when loading the static HTML page, as illustrated in the following example: var objectId = $.repo.createObjectId("","sap.package_name","StaticPage","html"); var indexHtmlObject = $.repo.readObject(activeSession,objectId,activeVersion); var respTxt = indexHtmlObject.cdata.replace("$UI5_LANGUAGE$", $.session.language); $.response.setBody(respTxt);
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") } </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("");
8.7
Server-Side JavaScript Tracing
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
346
For example, to enable debug-level tracing for your JavaScript application: $.trace.debug("request path: " + $.request.path);
Note
You can view the xsengine*.trace files in the Diagnosis Files tab page in the Administration perspective of the SAP HANA studio.
8.7.1
Tracing Server-Side JavaScript Applications
The server-side JavaScript API for SAP HANA XS enables you to activate the writing of trace messages into an application-specific trace file; the following trace levels are available: debug, error, fatal, info, and warning.
Context
By default, applications write messages of severity level error to the xsengine*.trc trace files; you can increase the trace level manually, for example, to fatal. In SAP HANA XS, the following steps are required to enable trace output for your server-side JavaScript application:
Procedure
1. 2. 3. 4. Open the SAP HANA studio. In the SAP HANA Systems view, double-click the SAP HANA instance to open the Administration view for the repository where your server-side JavaScript source files are located. Choose the Trace Configuration view. In the Global Database Trace screen area, choose Edit Configuration. The Edit Configuration icon is only visible if you have the required privileges on the selected SAP HANA system.
PUBLIC
347
Note
If the Global Database Trace screen area is not displayed, check that you are using a version of SAP HANA studio that is compatible (the same as) with the SAP HANA server where you want to set up tracing. 5. 6. 7. 8. Select the Show All Components checkbox. Enter the partial or full name of your application into the search box. Expand the GLOBAL node, if necessary, to view registered traces for the application name returned by the search operation. Find the trace matching your application name and select the trace level you want to use to generate output. The application name is the location (package) of the .xsapp file associated with the application you are tracing. The trace topic is named xsa: <appName>. 9. Choose Finish to activate the trace level changes.
8.7.2
Viewing Server-Side JavaScript Application Trace Files
The server-side JavaScript API for SAP HANA XS enables you to instruct your JavaScript applications to write application-specific trace messages in the xsengine*.trc trace files, which you can view in the Diagnosis Files tab page of the Administration perspective in the SAP HANA studio. The following trace levels are available: debug, error, fatal, info, and warning.
Context
To view trace output for your server-side JavaScript application, perform the following steps:
348
Procedure
1. 2. 3. 4. Open the SAP HANA studio. In the SAP HANA Systems view, double-click the SAP HANA instance to open the Administration view for the repository where your server-side JavaScript source files are located. Choose the Diagnosis Files tab page. In the Filter box, enter a string to filter the list of search files displayed, for example, xsengine*.trc. The timestamp displayed in the Modified column does not always reflect the precise time at which the trace file was written or most recently modified. 5. Locate the trace file for your SAP HANA XS application and doubleclick the entry to display the contents of the selected trace-file in a separate tab page.
8.8
Debugging Server-Side JavaScript
SAP HANA studio enables you to debug XS JavaScript files, including setting breakpoints and inspecting variables.
Context
SAP HANA Extended Application Services (SAP HANA XS) includes a dedicated role, which you must assign to any developer who wants to debug server-side JavaScript code.
Note
You must also enable debugging on the SAP HANA server. Start SAP HANA studio and in the Configuration tab of the Administration perspective, check that the xsengine.ini debugger node has the enabled parameter set to true. If necessary, create the parameter and set it. In addition, 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.
To start a debugging session for your server-side JavaScript, perform the following tasks:
Procedure
1. Enable debugging on the SAP HANA server.
PUBLIC
349
a) Start SAP HANA studio and open the Administration perspective. b) In the Configuration tab, add a section called set) the following parameter: 2. enabled = true xsengine.ini debugger (if it does not exist) and add (or
Ensure that you assign the debugger role to the user who wants to start a debug session.
a) Start SAP HANA studio and open the Administration perspective. b) In the SAP HANA Systems view, expand the Security node and double-click the user to whom you want to assign the debugger role. c) In the Granted Roles view, choose the [+] icon and, in the Select Role dialog, enter debugger to search for the debugger role and choose OK. 3. 4. In a Web browser, run the XS JavaScript source file that you want to debug. Create a debug configuration for debug sessions for a specific SAP HANA installation. a) Open the Debug perspective. b) Choose and select Debug Configurations.
c) Create a new XS JavaScript configuration by double-clicking XS JavaScript. d) Enter a name for the new debug configuration. e) Enter the host and debug port for your SAP HANA system. By default, the port number is 80<SAP_HANA_instance_no>. If the number of the SAP HANA instance is 01, then the port number to enter in the Debug Configurations dialog is 8001.
Note
You can change the default port setting, but it is not recommended. Any change to the default port setting must be made by modifying the HTTP(S) port(s) in the SAP Web Dispatcher configuration file, and this would affect the SAP HANA XS Web server and, by extension, all applications using it.
350
f) 5.
Choose Apply.
g) Choose Close. Set breakpoints in the JavaScript code by double-clicking the left vertical ruler.
6. 7.
Run the new debug configuration for your server by choosing
and selecting your debug configuration.
In the Select Session window, select the SAP HANA XS session ID you are debugging, and then click Select. The session ID is the value of the xsSessionId cookie in your browser session.
8.
Refresh the Web browser page. The XS JavaScript is now running in debug mode. Your client is now attached to the session, and execution is suspended at the first breakpoint.
PUBLIC
351
8.8.1
The Debug Perspective
SAP HANA studio includes a dedicated debug perspective, which provides the tools needed by a developer who wants to debug server-side JavaScript code. Application developers can use the SAP HANA studio's Debug perspective to perform standard debugging tasks, for example: starting and resuming code execution, stepping through code execution, adding breakpoints to the code. Developers can also inspect variables and check the validity of expressions. The following views are available as part of the standard Debug perspective: Debug Displays the stack frame for the suspended or terminated threads for each target you are debugging. Each thread in your program appears as a node in the tree. You can also see which process is associated with each target. Breakpoints Displays a list of the breakpoints set in the source file you are currently debugging Variables Displays a list of the variables used in the source file you are currently debugging Expressions, Displays global variables, such as $.request and other SAP HANA XS JavaScript API objects Outline Displays a structural view of the source file you are currently debugging. You can double-click an element to expand and collapse the contents. Source-code editor SAP HANA studio uses the file extension (for example, .js or .xsjs) of the source file you want to debug and opens the selected file in the appropriate editor. For example, files with the .js or .xsjs file extension are displayed in the built-in JavaScript editor.
352
PUBLIC
8.8.2
The 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) includes a debug perspective, a debug view, 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 (or a role) either with the standard roleassignment feature included in SAP HANA studio (the Application Privileges tab in the Security area of the SAP HANA Systems view) or in a design-time, role-configuration file (.hdbrole). Since a developer primarily needs to debug his own HTTP calls, the following limitations apply to a debug session: Only authenticated users can start a debug session, for example, by providing a user name and password when logging in to a debug session A user can debug his own sessions. A user can debug any session to which access has been explicitly granted, for example, by the owner of the session.
PUBLIC
353
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. SAP HANA studio includes a graphical user interface (GUI) which you can use to grant access to debug sessions at both the session level and the user level. Related Information Custom Development Role [page 531] A role enables you to assign one or more privileges to a user according to the area in which the user works; the role defines the privileges the user is granted.
8.8.3
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: You can grant a user global access to any of your debug sessions. The user you grant access to must already be registered and authenticated in the SAP HANA database.
354
You can grant access to a debug session that is flagged with a specific token:
Note
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.
Related Information The XSJS Debugger Role [page 353] 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. XSJS-Debugging Security Considerations [page 355] User authentication and a dedicated debugging role are just two aspects of security to be considered by anyone who wants to debug server-side JavaScript on SAP HANA Extended Application Services(SAP HANA XS). XSJS-Debugging Security Considerations [page 355] User authentication and a dedicated debugging role are just two aspects of security to be considered by anyone who wants to debug server-side JavaScript on SAP HANA Extended Application Services(SAP HANA XS). Troubleshooting Server-Side JavaScript Debugging [page 356] When debugging your JavaScript code, you sometimes need to solve problems, not only with the code itself, but the configuration of the sessions and the tools you use to perform the debugging.
8.8.4
XSJS-Debugging Security Considerations
User authentication and a dedicated debugging role are just two aspects of security to be considered by anyone who wants to debug server-side JavaScript on SAP HANA Extended Application Services(SAP HANA XS). Users who want to debug a server-side Javascript (XSJS) session must provide authentication. However, anyone wanting to debug server-side JavaScript on SAP HANA XS must also bear in mind the following security considerations: Debugging tools You must enable the <debugger> variable in the xsenging.ini and set the variable to true Authentication User authentication is required to open the debugging session:
Note
It is not recommended to run a debugging session without using the Secure Sockets Layer (SSL) protocol. The debugging session uses standard HTTP(S) The session either leverages an existing session or requests basic (HTTP) authentication on the connection request. The debugging session upgrades the HTTP connection to a WebSocket.
PUBLIC
355
Debugging role SAP HANA XS provides a dedicated debugger user role; the role must be assigned to any user who wants to start a debugging session for server-side JavaScript in SAP HANA XS. Multi-user debugging By default, other users do not have the permissions required to access your XSJS debugging sessions. However, SAP HANA XS provides a tool that enables you to grant access to your debug sessions to other users, too. The XS Debugging tool is available at the following URL on the SAP HANA XS Web server: <WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/debugger/.
Note
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. Related Information The XSJS Debugger Role [page 353] 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. Debug Session Access [page 354] You can grant other developers access to the debug sessions you use for debugging server-side JavaScript on SAP HANA XS. Troubleshooting Server-Side JavaScript Debugging [page 356] When debugging your JavaScript code, you sometimes need to solve problems, not only with the code itself, but the configuration of the sessions and the tools you use to perform the debugging.
8.8.5
Troubleshooting Server-Side JavaScript Debugging
When debugging your JavaScript code, you sometimes need to solve problems, not only with the code itself, but the configuration of the sessions and the tools you use to perform the debugging.
Context
If you are having problems debugging your server-side XSJS (JavaScript) code, check the following solutions:
Procedure
1. Check that you have enabled debugging on the SAP HANA server. a) Start SAP HANA studio and open the Administration perspective. b) In the Configuration tab, add a section called set) the following parameter: xsengine.ini debugger (if it does not exist) and add (or
356
2.
enabled = true
If the execution of your XS JavaScript code is not stopping at a breakpoint, consider the following solutions. a) Make sure you open a session with the server by calling an XS JavaScript file from your Web browser before starting the debug operation. When starting to debug, select the session whose ID is specified in the xsSessionId cookie in your open Web-browser session. b) Restart the SAP HANA studio with the -clean option, for example: hdbstudio.exe -clean To determine if a clean restart of SAP HANA studio is required, check if the Breakpoints view in SAP HANA studio's Debug perspective displays the breakpoints as type SAP HANA XSE Script, as follows: In the Breakpoints view, choose the View Menu. Choose Group By Breakpoint Types
c) Try removing all the existing breakpoints from the session and recreating them. d) As a last resort, for example, if the -clean option does not solve the problem of unrecognized breakpoints, it might be necessary to create a new Eclipse (not repository) Workspace. 3. If a connection cannot be established for a debug session, check the following: a) The debugger variable in xsengine.ini is enabled
b) The user starting the debug session has the debugger role assigned
c) The SAP HANA XS Web server is running, and HTTP access to the URL http:<SAPHANA_HOSTNAME>:<PortNumber>:/ works.
PUBLIC
357
d) Check if the delivery unit (DU) HANA_XS_BASE.tgz is deployed; HANA_XS_BASE.tgz contains the XSJS debugging tools. If necessary, redeploy the HANA_XS_BASE.tgz delivery unit. In SAP HANA studio, choose the option New Import Delivery Unit .
358
PUBLIC
4.
Check that the SAP Web Dispatcher configuration includes settings for WebSocket ports. The SAP Web Dispatcher configuration file <$DIR_INSTANCE>/<HOSTNAME>/wdisp/sapwebdisp.pfl must include the following lines: icm/server_port_2 = PORT=0, PROT=WEBSOCKET, TIMEOUT=-1 icm/server_port_3 = PORT=0, PROT=WEBSOCKETS, TIMEOUT=-1
Note
A user with administrator privileges must make or modify these settings. Related Information
PUBLIC
359
Debugging Server-Side JavaScript [page 349] SAP HANA studio enables you to debug XS JavaScript files, including setting breakpoints and inspecting variables.
360
9
9.1
Building UIs
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. SAPUI5 runtime is a client-side HTML5 rendering library with a rich set of standard and extension controls and a lightweight programming model. To support you in developing applications, SAPUI5 application development tools comes with a set of eclipse-based wizards and editors. SAPUI5 application development tools provides wizards to create application projects and views according to the model-view-controller concept and other features like JavaScript code completion, templates and snippets, and in-place application preview. SAPUI5 provides many features to enable you to easily create and extend state-of-the-art user interfaces. SAPUI5 supports the following features: RIA-like client-side features based on JavaScript CSS3, which allows you to adapt themes to your company's branding in an effective manner Extensibility concept regarding custom controls, meaning that you can extend existing SAPUI5 controls as well as develop your own controls Open source jQuery library used as foundation Full support of the SAP product standard Compliance to Open Ajax; can be used together with standard JavaScript libraries Produced in a release independent code line to enable short shipment cycles
For detailed information including a Getting Started with SAPUI5 section, see the SAPUI5 Reference for SAP HANA.
SAPUI5 SDK
The SAPUI5 SDK (Demo Kit) provides the following sections: Developer Guide with additional information about SAPUI5, the used programming languages, open source technologies, development tools, and APIs Controls containing running demo examples with descriptions and source codes API reference with JavaScript documentation of Framework and Control API Test Suite, which shows all controls running with different property settings where you can interactively adapt the controls you use for test purposes
The Demo Kit is installed as a delivery unit. To directly access the Demo Kit, use the following link and replace the placeholders accordingly: <xsengine protocol>://<xsengine server>:<xsengine port>/sap/ui5/1/sdk/index.html. Related Information SAP UI5 Reference for SAP HANA
SAP HANA Developer Guide Building UIs
PUBLIC
361
9.2 9.2.1
Building Search UIs with SAP HANA Info Access What's the Idea behind SAP HANA Info Access?
In the first place, SAP HANA is a database. It stores any type of raw data in its tables: master data, transactional data, numbers, texts, and so on. But SAP HANA can do more than a classic database. SAP HANA also enables you to turn raw data into meaningful information. In terms of numbers, it offers the analytics features of SAP HANA. By joining, aggregating, and calculating, these can turn raw facts and numbers into meaningful measures and key figures. In terms of text, it offers the full text search and text analysis features of SAP HANA. By tokenizing, stemming, normalizing, and analyzing semantically, these can turn a set of strings into a structured and searchable text corpus. SAP HANA thus contains meaningful information. This is still not instantly available to business end users however. This is where SAP HANA info access comes in. Provided that you only need read-access, standard search and simple analytics that is, the info access provides shortcuts to Web and mobile UIs. Using the info access offering, all you need to do is build search UIs, without having to take care of the server-side logic.
9.2.2
SAP HANA Info Access Architecture
The SAP HANA info access HTTP service wraps search SQL queries and exposes them through an HTTP interface. The service operates on one SAP HANA attribute view at a time and makes use of the indexed and analysed texts joined in that view.
362
PUBLIC
On the UI layer, SAP HANA info access offers the simple info access (SINA) JavaScript API. The SINA API is a client-side or front-end API for developing browser-based search UIs. Use this API to develop custom search UIs, for example using SAPUI5, open source, or self-made controls. On top of the SINA API, there is the HTML5 development kit including UI widgets and Web site templates. Use this toolkit to easily compose a search UI using the pre-defined controls, like search slot, result list and simple charts. Whether you use the API or the toolkit, there is no intermediate layer required in your landscape. To provide info access UIs to your users, you only need SAP HANA and a Web browser.
9.2.3
Installing the Info Access Service, Toolkit, and API
The SAP HANA info access HTTP service is part of the default SAP HANA server shipment, but it is not installed automatically. It is shipped as a separate XS delivery unit that you can quickly import and activate. The UI toolkit for HTML5 and the JavaScript API are packaged together in another delivery unit that is part of the SAP HANA stack. You can download this delivery unit from SAP Service Marketplace and import it into your SAP HANA system.
9.2.3.1
Importing the Info Access Service
Prerequisites
SAP HANA Appliance Software, Support Package Stack (SPS) 06 or higher, running on a server. SAP HANA studio and SAP HANA client installed on your local machine.
Procedure
1. 2. 3. 4. 5. 6. 7. Open the SAP HANA studio. From the menu, choose Select File Import . Delivery Unit and choose Next.
SAP HANA Content
Under Target System, choose your database instance. Select Server and, from the dropdown list, select the SYS/global/hdb/content/HCO_INA_SERVICE.tgz delivery unit. Select both actions and choose Finish. In the SAP HANA modeler, in the SAP HANA Systems view, under Content, check that the following package is available: sap\bc\ina\service
PUBLIC
363
9.2.3.2
Importing the Info Access Toolkit and the SINA API
Prerequisites
SAP HANA Appliance Software, Support Package Stack (SPS) 06 or higher, running on a server. SAP HANA studio and SAP HANA client installed on your local machine.
Procedure
1. Download the INA UI toolkit archive from SAP Software Download Center at Browse our Download Catalog PLATFORM EDITION INA TOOLKIT HTML 1.0 2. SAP In-Memory (SAP HANA) SAP HANA PLATFORM EDIT. 1.0 OS independent Support Packages and Patches SAP HANA HANA
HANA Platform Edition
Comprised Software Component Versions
SAP HANA database .
Save the HCOINAUITOOLKIT<version>.SAR file to your local disk and unpack the archive using SAPCAR. The SAR archive contains the SAP HANA delivery unit HCO_INA_UITOOLKIT.tgz. Open the SAP HANA studio. From the menu, choose Select File Import . Delivery Unit and choose Next.
3. 4. 5. 6. 7. 8. 9.
SAP HANA Content
Under Target System, choose your database instance. Select Client and browse for the HCO_INA_UITOOLKIT.tgz delivery unit on your local disk. Select both actions and choose Finish. In the SAP HANA modeler, in the SAP HANA Systems view, under Content, check that the following packages are available: sap\bc\ina\demos sap\bc\ina\uitoolkit sap\bc\ina\API sap\bc\ina\uicontrols
9.2.4
Preparing Your Search Data
Before starting to build your info access UI, you need to have a clear understanding of who will use it and for what purpose. This brings you to the question which content you need to enable for access. You need to have answers to the following questions: Which records do I want to enable my users to find, for example employees, purchase orders, or documents?
364
Which attributes of the records are suitable to search through, for example last name, short text, or last changed by? Which attributes do I want to get back along with found records, and how do I want to present them? By which attributes do I want to enable my users to filter or see a count of distinct values in a chart?
Having answered these questions, you can go ahead and create the right full-text indexes, set up text analysis, model a tailored attribute view and make the search settings for certain attributes.
9.2.4.1 Ensuring Full Text Indexing and Enabling Text Analysis

Make sure that a full-text index is created for each of your table columns that contains human-readable text data that is suitable for a freestyle search.
Note
When you create a TEXT or SHORTTEXT column in a table, SAP HANA automatically creates a corresponding full text index. However, for columns of other data types, you must manually create and define any necessary full text indexes. The index structure is attached to the column and is leveraged to identify texts that contain the search terms. The full text index is automatically updated when new records are entered in the table. Along with the full text index, you can also trigger a text analysis that extracts entities, such as dates or people, from the text and, therefore, enriches the set of attributes.
Note
The text analysis provides a vast number of possible entity types and analysis rules for many industries in 20 languages. However, you do not have to deal with this complexity when analyzing your individual set of documents. The language modules included with the software contain system dictionaries and provide an extensive set of predefined entity types. Related Information Creating Full Text Indexes [page 398] When you create a TEXT or SHORTTEXT column in a table, SAP HANA automatically creates a corresponding full text index. For columns of other data types however, you have to create and define any necessary full text indexes manually. Text Analysis [page 406]
9.2.4.2
Context
Modeling Your Search Content
In the SAP HANA modeler, create an attribute view of type standard using the tables that you want to enable for the search. Create joins and add the attributes you want to use for searching and displaying.
PUBLIC
365
Note
You can also join additional attributes derived from the text analysis. To enable certain attributes for the search, proceed as follows:
Procedure
1. In the Output pane, select the attributes.
Note
The searchable attributes must not be calculated attributes, nor have lowercase letters in their names. 2. 3. In the Properties view, choose Search Properties. Set the Freestyle Search property to true. This property marks the attribute as relevant for search. When an end user runs a query all values of this attribute are searched (or the full text index if available). 4. Set the Weights for Ranking to a value between 0.0 and 1.0 (default 0.5). This property influences the ranking of items in the results list. The higher the weight of the attribute compared to others in the view, the higher up the list an item with a hit in this attribute is positioned. 5. Decide if you want to enable an error-tolerant search (Fuzziness true) or use exact search only (false). If you are using the fuzzy search, the Fuzziness Threshold property defines the grade of error tolerance for a search on this attribute. The higher the threshold, the more exactly the search terms must match the text to produce a result. Set the threshold to one of the predefined values (default 0.8). Related Information Creating Attribute Views [page 184] You can create a view that is used to model descriptive attribute data by using attributes, that is data that does not contain measures. Attribute views are used to define joins between tables and to select a subset or all of the table's columns and rows. FUZZY Search [page 420] Fuzzy Search is a fast and fault-tolerant search feature for SAP HANA. A fuzzy search returns records even if the search term contains additional or missing characters or other types of spelling errors.
9.2.5
Authorizations for SAP HANA Info Access Users
For each end user of your info access UI, you have to create a named database user with the following authorizations: Granted roles: sap.bc.ina.service.v2.userRole::INA_USER. This role grants access to the info access HTTP service. Without this role, a request from the user will result in an HTTP status 403 error (not authorized). Object privileges: SELECT for all attribute views in which you want to permit this user to search. And SELECT for all tables that you used in these attribute views.
366
SQL privileges (grouped bar chart only): EXECUTE for the _SYS_BIC schema.
Note
Newly created users first need to change the initial password that you assigned to them. A login attempt using the initial password will result in an HTTP status 403 error (not authorized). Users can easily change the password using a Web browser by calling the following URL: <protocol>://<HANAhost>:<port>/sap/hana/xs/formLogin/login.html Example: http://hana1.acme.corp:8001/sap/hana/xs/formLogin/login.html Related Information The Authorization Model [page 527] Authorization mechanisms ensure that authenticated users can do only those things they are allowed to do. You can use the authorization mechanisms of the SAP HANA database to specify who is allowed to access which data and for which activities.
9.2.6
Using the SAP HANA Simple Info Access API
The SAP HANA simple info access (SINA) API is a client-side or front-end JavaScript API for developing browserbased search UIs. This API provides the following simplified set of features from the SAP HANA Info Access HTTP service: Connecting to a SAP HANA attribute view Freestyle-searching the data of the view Suggesting possible search terms Receiving results for lists Receiving results for simple charts Filtering the results
For more information about the SINA API, see the reference documentation. It contains the following: Detailed descriptions of classes and namespaces Lots of code samples and tutorials
The SINA API reference documentation is available at the following locations: Online, at SAP Help Portal. On your SAP HANA host, at http://<HANAhost>:80<instance>/sap/bc/ina/api/doc/index.html
Example
http://hana1.acme.corp:8001/sap/bc/ina/api/doc/index.html
PUBLIC
367
9.2.7
Using the UI Toolkit for SAP HANA Info Access
The UI toolkit for SAP HANA Info Access provides UI building blocks for developing browser-based search apps on SAP HANA. The toolkit enables a freestyle search of a SAP HANA attribute view, displaying and analyzing the result set. The toolkit provides UI elements (widgets) such as a search box, a result list with a detailed view, and charts for basic analytics on the result set. The widgets are interconnected and adapt in real-time to user entries and mouse-over (hover) selections. The toolkit is based on HTML5 and JavaScript libraries such as JQuery/JQueryUI, d3 (Data Driven Documents), and Tempo. The widgets use the SAP HANA Info Access HTTP service. You do not need an additional layer to run the UI; SAP HANA and a Web browser are sufficient. The toolkit is tested on Mozilla Firefox 17. It also runs on Microsoft Internet Explorer 9 in standard mode and Google Chrome. Along with the actual toolkit (the widgets), we deliver a fully operational demo Web app built using this toolkit. The demo app enables you to explore a search application dealing with a set of sample data for electronic products. You can use the demo app as a template or for reference when you start developing your own app. You can, for example, use the demo site to easily connect your own data and compose your Web site. To create a search application this way, it is sufficient to have experience in HTML and to have read this documentation. For advanced customizing and layout of the site, more in-depth knowledge of CSS and the above-mentioned JavaScript libraries is required.
9.2.7.1
Getting to Know the Demo App
You can now explore what an app built using the UI toolkit looks and feels like. Start the sample UI in a Web browser by opening the following URL: http://<HANAhost>:80<instance>/sap/bc/ina/demos/epm/search.html Example: http://hana1.acme.corp:8001/sap/bc/ina/demos/epm/search.html Start exploring the UI.
368
PUBLIC
The demo app consists of a header row, a column on the left, and a large content area on the right. The column on the left contains some widgets; the search box and some charts. The charts are used for displaying the count of result items with distinct values. In the EPM example, it is the count of sold products by category and by currency. The content area on the right is for displaying an enlarged view of one of the widgets, the result list is enlarged at page load. The app starts with a search for all. By typing in the search box or filtering in the charts, you can refine the result set. The results are displayed in the list ranked by relevancy. From the right margin of the page, you can pull in the facet repository containing all configured facets that are not displayed in the column and the content pane. Facets are the widgets, such as the results list and charts, that display the dimensions of the result set. You can drag and drop all facets to any position on the UI, be it the column, the content area or the facet repository. When a chart is enlarged in the content pane, you can change the chart type with a click.
9.2.7.2
Getting to Know the Demo HTML
The structure and content of the UI are defined in the search.html file. Open the search.html file using the HTML editor. Familiarize yourself with the structure of the HTML. Partly collapsed, search.html looks like this:
PUBLIC
369
In the head area and at the end of the HTML, there is meta data and references to the various JavaScript libraries and CSS used by the UI. The body of the HTML contains the UI's header bar with the title text and the alert bar for displaying messages. The rest of the body is the workarea. A workarea connects to a SAP HANA attribute view and serves as a container for all other widgets on the page. The workarea is divided into the facetPane, the contentPane, and the facetrepository. The facetPane starts with the searchbox followed by a facetcolumn and the facetpane. The workareaitem widgets inside the column and the pane are only placeholders for facets of the repository that the user can shuffle around at runtime. Inside the facetrepository, there are the actual workareaitem widgets. For switching between different chart types, there are the switchbox widgets. The last widget in the repository is the resultlist.
9.2.7.3
Connecting Your Source Data
You can connect any search-enabled SAP HANA attribute view to the app by referencing the view and its attributes directly in your HTML file. To reference the attribute view and its schema in the HTML, enter their names in the workarea widget: <div data-sap-widget="workarea" data-title="searchandanalytics" data-entityset="J_EPM_PRODUCT" data-packagename="epm" data-aggregationdimension="PRODUCT_ID">
370
PUBLIC
data-entityset is the view name and data-packagename the package this view resides in. The dataaggregationdimension is used as basis for counting items with distinct values. Enter an attribute that has unique values, for example, the primary key. For chart facets that display the aggregates of attribute values, for example the grouped bar chart, enter the attribute names here: <div data-sap-widget="chart" data-title="PRICE-GROUPBAR" data-dimension-line="CURRENCY_CODE" data-dimension-x="CATEGORY" data-dimension-y="COUNT" data-charttype="groupbar">
Note
You cannot use attributes of data type TEXT_AE for charts. In the grouped bar chart example, data-dimension-line is the attribute whose distinct value count is to be displayed as the bars. The data-dimension-x attribute is displayed as an additional dimension inside the chart as a group of bars. data-dimension-y is the measurement that is displayed on the y-axis defining the height of the single bars. In the search app, the only measurement available is the distinct values count ($count) of the attribute defined in data-dimension-line. In a simple bar or pie chart, the data-dimension parameter contains the attribute whose distinct value count is to be displayed To define the attributes to be displayed in a result list entry, enter the attribute names here: <div data-sap-widget="inaresultlist" data-maxresultslarge="6" data-maxresultssmall="3" data-responseattributes="PRODUCT_ID, WEIGHT_MEASURE,WEIGHT_UNIT,PRICE,CURRENCY_CODE,DEPTH,DIM_UNIT,CATEGORY, CHANGED_AT,WIDTH,HEIGHT,THUMBNAIL"data-detailwidth="650" Do not leave the data-responseattributes parameter empty. Only use attributes from the main table of the view or attributes that are joined in 1:1 from other tables. Which response attributes are actually displayed in a result entry depends on the result layout templates. There are CSS and HTML templates available for the small result list, the large list, and the details view. Related Information workarea [page 372] chart [page 374] Defining the Layout of Result Lists and Details [page 376]
9.2.7.4
Defining the Page Layout
Now that your source data is prepared and connected, you can form your UI using the search.html template. You may want to start by arranging the available widgets on your site. To place the column, the panes, and the facets within them, copy, move, or remove the corresponding HTML blocks. First, place the facet pane and its column(s) as well as the content pane. The panes and the columns inside are displayed from left to right on the UI in the same order as in the HTML. Only one content pane is allowed. Typically, a maximum of three facet columns are used. The facet repository is always last in the HTML. The search box and the facets inside the facet columns are next. The search box can span the entire pane across multiple columns. Place as many placeholder work area items as you want to have slots in a column. Inside the
PUBLIC
371
content pane, only one placeholder is allowed. Make sure that the data-target-position count is continuously set across the facet columns and the content pane. The facet repository holds the actual facets, meaning the chart switch boxes and the result list. The datasource-position parameter defines their position inside the facet repository as well as inside the columns and the content pane at page load. If the source position equals the target position, the respective facet replaces the placeholder in the columns and pane. If there are two or more facets with the same source position number, only the first one in the HTML replaces the placeholder. In the facet repository, all defined facets are available in the order of the source position or their appearance in the HTML. At runtime, the user can drag and drop the facets. At least one facet pane and content pane are required for the facet repository and free drag-and-drop. However, you could also build a minimal static UI with a workarea containing just a search box and a result list, for example. You can even integrate single widgets into other sites. Related Information workareaitem [page 373]
9.2.7.5
Configuring the Widgets
The widgets are based on jQuery UI. In the HTML, you can customize the single widgets to a certain degree using parameters. The common parameter data-sap-widget defines the type of the widget. Each widget type has its own set of parameters. The widgets and their parameters are listed in the order of appearance in the demo HTML file.
9.2.7.5.1
Parameter Name data-title data-helphref
header
Default Value SAP HANA Text and Search none true true Description Title text in the header bar of the UI. Reference to the documentation for the users of your application. Displays the name of the current user in the header bar. Displays a button in the header bar that enables the user to log out.
data-showusername data-showlogout
9.2.7.5.2
Parameter Name datapackagename
workarea
Default Value none Description Name of the database package in which the attribute view was created.
372
Parameter Name data-entityset data-schema
Default Value none _SYS_BIC
Description Name of the attribute view. Name of the database schema (catalog) in which the activated attribute view resides. The schema _SYS_BIC is default because your activated attribute views usually end up in this schema. Primary key attribute of the items you want to search and display. The unique key is used to identify items for the result list and to count items with distinct values for the charts. Descending or ascending (ASC) order for sorting the counts in the charts. This setting is inherited by all charts if you do not set a sort order there.
datanone aggregationdime nsion dataDESC aggregationsort order Related Information
Connecting Your Source Data [page 370]
9.2.7.5.3
Parameter Name
searchbox
Default Value false 255 Description The system already performs a search with each letter a user types. Maximum number of characters that users can enter in the search box.
data-enablelivesearch data-maxinputlength
9.2.7.5.4
Parameter Name data-title
workareaitem
Default Value none Description This title is displayed on the UI as the facet headline. If the workareaitem is a placeholder, the title is used as alternative text. The alternative is displayed if the placeholder is not replaced by an actual workareaitem at runtime.
data-target-position
Position of a placeholder workareaitem on the UI in the facet or content pane. The count starts on the upper left of the UI.
data-source-position
Position of the actual workareaitem on the UI in the facet repository on the right. On page load, the workareaitem placeholders are replaced by the actual workarea items whose source positions match the target positions.
PUBLIC
373
9.2.7.5.5
Parameter Name
facetrepository
Default Value body Description Defines the area where a user can grab a facet for drag and drop. body means the complete facet, header means the facet's header bar only.
data-children-draghandle
9.2.7.5.6
Parameter Name
switchbox
Default Value 0 Description Defines which chart contained in the switchbox is displayed on page load. 0 means the first one, 1 the second, and so on.
data-activeindex
9.2.7.5.7
Parameter Name data-toplarge data-dimension
chart
Default Value 10 none Description Defines how many bars or pie segments are displayed when the chart is enlarged. Attribute whose distinct value count is to be displayed in a simple bar or pie chart.
Note
You cannot use attributes of data type TEXT_AE for charts. data-charttype data-color bar none Type of the chart (bar, pie, groupbar, or line). Color of the chart as hex triplet, for example #FFFFFF for white, or as standard HTML names, for example blue or black. data-dimension-line data-dimension-x data-dimension-y none none none Attribute whose distinct value count is to be displayed in grouped bar or line chart. Attribute that is displayed as additional dimension inside the chart as group of bars or different lines. Measurement that is displayed on the y-axis. In a search scenario, the only measurement available is the distinct value count ($count) of the attribute defined in data-dimensionline.
374
Parameter Name dataaggregationsortorder
Default Value ASC
Description Descending (DESC) or ascending order for sorting the counts in the charts. Here you can override the sort order defined centrally in the workarea widget.
data-topsmall dataanimationduration Related Information
5 1000
Defines how many bars or pie segments are displayed when the chart is small. Duration of the animation, in milliseconds, when a chart adapts (default 1000). 0 means that animation is switched off.
Connecting Your Source Data [page 370]
9.2.7.5.8
Parameter Name
resultlist
Default Value 10 5 none Description Maximum number of result items displayed on one page if the list is enlarged in the content pane. Maximum number of result items displayed on one page if the list is small in the facet column. Attributes to be displayed in a result list entry. The actual scope and layout of the response attributes on the result list and details pane are defined in the files referenced in the data-resulttemplate parameters.
data-maxresultslarge data-maxresultssmall data-responseattributes
Note
Do not leave the data-responseattributes parameter empty. Only use attributes from the main table of the view or attributes that are joined in 1:1 from other tables. Attributes with data type blob are not supported by the HTTP service. data-detailwidth data-detailheight data-resulttemplate data-resulttemplate-css data-resulttemplate-small 600 800 none none none Width of the details pop-up in pixels. Height of the details pop-up in pixels. Reference to HTML and CSS files defining the layouts of the result lists (small and large) and of the details pop-up.
PUBLIC
375
Parameter Name data-resulttemplate-smallcss data-resulttemplate-detail data-resulttemplate-detailcss data-orderby
Default Value none none none none
Description
Attribute by whose values the list is sorted alphabetically, if no relevancy ranking is available.
Note
First choice for sorting the result list is always the ranking by relevancy for the search term(s). The data-orderby setting only steps in if there is no relevancy ranking available, for example before the first search, or if there are equal ranking values. data-sortorder ASC Ascending or descending (DESC) order for the dataorderby parameter. Related Information Connecting Your Source Data [page 370] Defining the Layout of Result Lists and Details [page 376]
9.2.7.6
Defining the Layout of Result Lists and Details
You can select which attributes are displayed and how they are displayed in the result lists (small or centered) and on the details pop-up. In the search HTML file, the result templates are referenced in the inaresultlist widget using the data-resulttemplate parameters. The templates folder contains the HTML and CSS templates of the demo app for adapting. You can create your own result layouts from the templates and reference them in the parameters. Make sure that the path is correct. In the HTML templates, you define what is in a result entry in the different views. You can enter fixed text and reference the response properties and values in double braces. For a deeper understanding of these HTML templates, familiarize yourself with the Tempo JSON rendering engine.
Note
If you want to integrate graphics in result list templates, define the exact width and height in pixels. Use the corresponding CSS files to define the result layouts and the behavior on hover events. To tweak the layout of the details screen further, you can also use the widgets provided by jQuery UI.
376
PUBLIC
9.3
Using UI Integration Services
SAP HANA UI Integration Services is a set of Eclipse-based tools and client-side APIs that enable you to integrate standalone SAP HANA client applications into Web user interfaces to support end-to-end business scenarios. These Web user interfaces are referred to as application sites. Standalone SAP HANA client applications that are integrated into application sites are referred to as widgets.
Prerequisites
SAP HANA studio is installed on your local system. The SAP HANA studio version must match the current SAP HANA version. A supported browser is installed on your local system. At design time, the following browsers are supported: On Windows: Internet Explorer 9 or higher, Internet Explorer 8 with limitations On Linux: latest version of Firefox
Note
For end users at runtime, the following browsers are supported: On Windows: Internet Explorer 9 or higher, latest versions of Safari, Chrome, Firefox On Linux: latest version of Firefox
You are assigned the sap.hana.uis.db::SITE_DESIGNER role, and end users are assigned the sap.hana.uis.db::SITE_USER role. For more information, see Granting Privileges to Users [page 559].
The HANA_UI_INTEGRATION_SVC delivery unit is imported and activated. To import the delivery unit, perform the following steps: 1. 2. 3. 4. In the SAP HANA studio menu, choose Select the import source File Import . Delivery Unit , and choose Next.
SAP HANA Content
Select the target system for the delivery unit. Choose the Server option. In the dropdown list of available files, select <path>/ HANA_UI_INTEGRATION_SVC.tgz, and choose Finish.
For more information, see Importing Delivery Units. You have set up an SAP HANA application project. For more information, see Tutorial: My First SAP HANA Application [page 27] and Using SAP HANA Projects [page 48].
Related Information Creating an Application Site [page 378] Developers create application sites in the SAP HANA studio. Designing an Application Site [page 378] You can visually design and manage application sites in the browser-based design environment embedded in the SAP HANA studio. Developing Widgets [page 385]
PUBLIC
377
SAP HANA UI Integration Services provides a number of tools and client-side APIs to use when developing widgets for integration into application sites. Creating a Widget [page 384] To integrate a standalone SAP HANA XS client application or other Web application into application sites, you need to create a widget based on this application.
9.3.1
Creating an Application Site
Developers create application sites in the SAP HANA studio.
Procedure
1. 2. 3. In the project's context menu in Project Explorer, choose In the New dialog box, choose SAP HANA Development New Other .
Application Site , and then choose Next.
In the New Application Site dialog box, select a parent folder, enter the site properties, and choose Finish. The newly created site opens for design in the embedded browser window.
Related Information Designing an Application Site [page 378] You can visually design and manage application sites in the browser-based design environment embedded in the SAP HANA studio.
9.3.2
Designing an Application Site
You can visually design and manage application sites in the browser-based design environment embedded in the SAP HANA studio.
Context
Procedure
1. To open the site for editing in the embedded browser, double-click the site's .xsappsite file in Project Explorer. If you open the site from its context menu, make sure you choose the default Application Site Editor. Choosing another editor is not recommended.
378
You can perform the following tasks: Task View and modify site properties Add, organize, or remove pages Add widgets to pages Manage widgets on pages Choose site layout options Instructions Accessing Site Properties [page 379] Managing Pages [page 380] Adding Widgets to Pages [page 381] Managing Widgets on a Page [page 382] Configuring Site Layout [page 380]
Note
You access most of these tasks from the design panel located to the right of the content area. By default, the design panel is collapsed into a side bar with buttons. To expand the panel, click the side bar button that is relevant for your current task. 2. 3. To save your changes, choose File Save from the main menu. Team Activate from the
To make the site available to end users, activate it by choosing site's .xsappsite file context menu.
Note
The URL of the sites runtime version is displayed in the Site Properties pane in the design environment. At runtime, application sites are best viewed in Google Chrome or Mozilla Firefox.
9.3.2.1
Accessing Site Properties
You can view and modify application site properties.
Context
To access the application site's properties, choose in the design panel. Most of the properties are read-only.
The URL property contains the URL of the sites runtime version that is available to end users after the site is activated. You can modify the Title or Description properties:
Procedure
1. Double-click on the property field and type the new name.
PUBLIC
379
2.
The change is saved automatically. To discard the change while the field is in focus, press Esc .
9.3.2.2
Configuring Site Layout
You can configure certain site layout options.
Context
You can adjust the appearance and behavior of the shell's navigation bar to the needs of specific applications. For example, if your application site contains only one widget that has its own navigation controls, you might want to disable the navigation capabilities of the shell.
Procedure
1. 2. In the design panel, choose Option
Full Narrow Header None
to open the Layout pane.
In the Navigation Bar dropdown box, choose the required option: Description
Fully functional navigation bar of the standard size Fully functional narrow navigation bar Only header with no navigation; suitable for sites with only one page No navigation bar at all; suitable for sites containing a single widget with its own header
Results
The selected option takes effect for all end users of the application site once the site is activated.
9.3.2.3
Managing Pages
You can manage the pages of an application site using the tools of the design environment.
380
PUBLIC
Context
To optimize content structuring in an application site, you can maintain two levels of pages. For any page, you can create subpages and organize content on these subpages. To manage pages, choose following tasks: Task Add a page Add a subpage (Pages) in the design panel. In the Pages pane that opens, you can perform the Description Click Add Page. A new page with the default name New Page is added after the last page. Click Add Subpage below the page to which you want to add a subpage. A new subpage with the default name New Subpage appears after the last subpage.
Note
If the page had widgets before the first subpage was created, these widgets are automatically moved to the first subpage. Rename a page or subpage Click the page or subpage name that you want to change, and edit it in the text box that opens. The change is saved automatically. To discard the change while the text box is in focus, press Esc . Point the cursor at the page or subpage that you want to delete, and choose (Delete). If the page has widgets or subpages, a confirmation message box appears. If you confirm the deletion, the page is deleted along with all its widgets or subpages. Move a page or subpage To change the position and/or level of a page or subpage, drag and drop it in the required location in the list.
Delete a page or subpage
9.3.2.4
Adding Widgets to Pages
You can add available widgets to application site pages.
Context
You can add widgets to a page that has no subpages, or to a subpage. To add a widget to a page or subpage:
Procedure
1. Open a page or subpage by choosing its tab in the content area.
PUBLIC
381
2. 3.
In the design panel, choose
to open the Widgets pane that contains available widgets.
To locate the required widgets, type a widget name or a part of it in the search box. You can also filter the widgets by folder: from the dropdown box, select a folder in which the widgets were created. The widgets displayed in the pane match the selection criteria. Double-click the widget of your choice, or drag and drop it onto the current page. Reposition the widgets on the page as needed.
4.
Related Information Creating a Widget [page 384] To integrate a standalone SAP HANA XS client application or other Web application into application sites, you need to create a widget based on this application. Managing Widgets on a Page [page 382] You can organize and manage widgets on application site pages.
9.3.2.5
Managing Widgets on a Page
You can organize and manage widgets on application site pages.
Context
You can perform a number of tasks with widgets on a page. To access controls of a widget controls, hover the mouse over the widget to display its frame. Table 20: Widget Tasks Task Resize Toggle full screen view Description Drag the borders of the widget to resize it. Choose the size. or icon to maximize the widget or restore it to normal
Note
This setting is not persisted across sessions. Set properties Set display options Remove from page Setting Widget Properties [page 383] Setting Widget Display Options [page 383] If the widget's sidebar is not open, choose the (Open sidebar) tab at the upper right corner of the widget. In the sidebar, choose (Remove). In the confirmation dialog, choose Yes. Rearrange widgets on a page Drag and drop widgets to the required positions.
382
Next Steps
To make the changes effective for all end users of a site, you need to activate the site in the SAP HANA studio by choosing Team Activate from the site's .xsappsite file context menu.
9.3.2.5.1
Setting Widget Properties
You can customize a widget instance in an application site by setting its properties.
Context
If the widget's sidebar is not visible, choose the (Show sidebar) tab at the upper right corner of the widget.
Procedure
1. 2. 3. In the sidebar, choose (Customizable properties).
In the Properties dialog box that opens, modify the widget's title and/or any of the custom properties defined for this widget. Choose Preview to preview the customized widget, OK to save changes, or Cancel to discard them.
Results
The customized property values are persisted for the current widget instance. Related Information Enabling Widget Customization [page 393] Customization of widgets is enabled by defining custom widget properties.
9.3.2.5.2
Setting Widget Display Options
You can customize appearance of a widget in an application site by setting its display options.
Context
If the widget's sidebar is not visible, choose the (Show sidebar) tab at the upper right corner of the widget.
PUBLIC
383
Procedure
1. 2. In the sidebar, choose Option
Frame Size
(Display options).
In the Display dialog box, choose the appropriate frame and size icons to set the display options as follows: Description
Show or hide the widget's frame Normal or full screen; enabled only when the widget is the only one on the page
Selected display options are applied immediately. 3. When done, choose Close.
Results
The selected display options are persisted for the current widget instance.
9.3.3
Creating a Widget
To integrate a standalone SAP HANA XS client application or other Web application into application sites, you need to create a widget based on this application.
Context
To create an application-based widget in the SAP HANA studio, you need to write an XML specification file that either references or embeds the client-side code of the application, and run the Create New Widget wizard as follows:
Procedure
1. 2. 3. In the project's context menu in Project Explorer, choose In the New dialog box, choose SAP HANA Development New Other... .
Widget , and choose Next.
In the New Widget dialog box, choose the parent folder, enter the widget file name and specification file name, and choose Next.
Note
The specification file should be located under the current project's folder.
384
4. 5. 6.
In the next step of the wizard, set the widget properties, and choose Finish. To make the widget available for application sites, activate the widget by choosing the .xswidget file's context menu. widget, as described previously. Team Activate from
To edit the widget properties, open the .xswidget file, make the required changes, and then activate the
Related Information Sample Widget Specification Files [page 385] A widget specification file should either reference the client-side code of an application, or directly embed the application's HTML code in the <Content> section. Developing Widgets [page 385] SAP HANA UI Integration Services provides a number of tools and client-side APIs to use when developing widgets for integration into application sites.
9.3.4
Developing Widgets
SAP HANA UI Integration Services provides a number of tools and client-side APIs to use when developing widgets for integration into application sites. Related Information Sample Widget Specification Files [page 385] A widget specification file should either reference the client-side code of an application, or directly embed the application's HTML code in the <Content> section. Site Context API [page 386] Provides a messaging mechanism that enables you to implement communication between widgets in the same application site. GadgetPrefs API [page 390] Provides methods to persist widget preferences on the server side. SetTitle [page 395] A method that can be used to set a widget's title.
9.3.4.1
Sample Widget Specification Files
A widget specification file should either reference the client-side code of an application, or directly embed the application's HTML code in the <Content> section. The following are sample widget specification files: References an application: <?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Calendar"> </ModulePrefs> <Content type="html" href="/content/applications/calendar/index.html"> </Content> </Module>
PUBLIC
385
Embeds HTML code of an application: <?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Color Tester"> <Require feature="gadgetprefs"/> </ModulePrefs> <UserPref name="color" default_value="white"/> <Content type="html"> <![CDATA[ <html> <head> <script language="javascript" type="text/javascript"> var gadgetPrefs = new gadgets.GadgetPrefs(); window.onload = initiateGadgetPrefs; function initiateGadgetPrefs() { setBGcolor(); } function setColor() { var selectedColor = document.getElementById('color').value; gadgetPrefs.setPreference('color', selectedColor); setBGcolor(); } function setBGcolor() { var currentColor = gadgetPrefs.getPreference("color"); document.getElementById('main').setAttribute("bgcolor",
currentColor);
} </script> </head>
<body id="main" bgcolor="#F290F0" style="font-family:Arial;"> <label style="font-weight: bold ">Select background color: </ label><br> Color: <input type="text" name="color" id='color'/> <input type="button" value="Change Color" onClick="setColor();"/ ><br> </body> </html> ]]> </Content> </Module>
9.3.4.2
Site Context API
Provides a messaging mechanism that enables you to implement communication between widgets in the same application site. A widget can publish a message to the dedicated context object so that other widgets can subscribe a callback function to this message. To use the API, declare this feature in the <ModulePrefs> section of the widget's specification file: <ModulePrefs> <Require feature="sap-context"/>
386
PUBLIC
</ModulePrefs> The Site Context API provides the following methods: publish(key, value): Publish [page 387] subscribe(callback): Subscribe [page 388] unsubscribe(subscriptionID): Unsubscribe [page 389]
9.3.4.2.1
Publish
A method of the Site Context API that can be used by a widget to publish a message to other widgets.
publish(key, value) Use to publish messages to the sapcontext object. A message is a key-value pair that is stored in the context. The updated context is sent to all subscribed callbacks as a parameter. A widget can publish multiple values with the same key. Each time a widget publishes a different value with the same key, the new value replaces the previous one.
Parameters
Parameter key value Type String String Description The key of the published pair The value of the published pair
Example
<script language ="JavaScript"> ... gadgets.sapcontext.publish(Country, France); ... </script> Related Information Subscribe [page 388] A method of the Site Context API that can be used by a widget for subscribing to messages published by other widgets. Unsubscribe [page 389] A method of the Site Context API that can be used by a widget to remove an existing subscription.
PUBLIC
387
9.3.4.2.2
Subscribe
A method of the Site Context API that can be used by a widget for subscribing to messages published by other widgets.
subscribe(callback) Use for subscribing widgets to messages that are published to the sapcontext context object. The message is a key-value pair that is stored in the context. The updated context is sent to all subscribed callbacks as a parameter.
Parameters
Parameter callback Type Function Description The callback function that is called in response to the published message. Receives two parameters: topic and context. The topic parameter always equals sap-context.
Returns
Subscription ID
Example
<script language ="JavaScript"> ... var callback = function (topic, context) { var color = context.getPropertyByKey(widget-color); paintBackground(color); } function subscribe() { var subID = gadgets.sapcontext.subscribe(callback); } //To subscribe a widget immediately after it is loaded,
388
// register the subscribe function using gadgets.HubSettings.onConnect gadgets.HubSettings.onConnect = subscribe; ... </script> You can also call the subcribe method at any point directly. Related Information Publish [page 387] A method of the Site Context API that can be used by a widget to publish a message to other widgets. Unsubscribe [page 389] A method of the Site Context API that can be used by a widget to remove an existing subscription.
9.3.4.2.3
Unsubscribe
A method of the Site Context API that can be used by a widget to remove an existing subscription.
unsubscribe(subscriptionID) Use to remove an existing subscription.
Parameters
Parameter subscriptionID Type Int Description ID of the subscription to remove
Example
<script language ="JavaScript"> ... var subID = gadgets.sapcontext.subscribe(callback); ... gadgets.sapcontext.unsubscribe(subID); ... </script> Related Information Subscribe [page 388] A method of the Site Context API that can be used by a widget for subscribing to messages published by other widgets. Publish [page 387]
PUBLIC
389
A method of the Site Context API that can be used by a widget to publish a message to other widgets.
9.3.4.2.4
Enabling Communication Between Widgets
You can enable widgets, running in the same application site, to pass data to each other so that their content and behavior change dynamically according to this data. The following code samples illustrate how to implement communication between two widgets by using the publish-subscribe messaging mechanism provided by the Site Context API. The first widget displays a list of sales orders. Once the user selects a sales order from the list, the second widget displays the details of the order. First (source) widget: <script language ="JavaScript"> // Publish event when user selects a sales order from the list function onSalesOrderSelected(var salesOrderID){ gadgets.sapcontext.publish("selectedSalesOrderID", salesOrderID); } </script> Second (target) widget: <script language ="JavaScript"> // Callback function to display order details function callback (topic, context) { var salesOrderID = context.getPropertyByKey(selectedSalesOrderID); showSalesOrderDetails(salesOrderID); } function subscribe() { var subID = gadgets.sapcontext.subscribe(callback); } // To subscribe a widget immediately after it is loaded, // register the subscribe function using gadgets.HubSettings.onConnect gadgets.HubSettings.onConnect = subscribe; </script>
9.3.4.3
GadgetPrefs API
Provides methods to persist widget preferences on the server side. The GadgetPrefs API enables you to persist modified widget preferences on the server side. Persisted preferences of a widget override its default preferences. At design time, a single set of preferences is persisted for a widget, whereas at runtime a separate set of widget preferences is persisted for each user.
390
To use the API, declare this feature under the <ModulePrefs> tag of the widget's specification file: <ModulePrefs> <Require feature="gadgetprefs"/> </ModulePrefs> The GadgetPrefs API contains the following methods: getPreference(key): GetPreference [page 391] setPreference(key,value): SetPreference [page 393]
9.3.4.3.1
GetPreference
The GadgetPrefs API provides methods for retrieving persisted preferences of a widget.
getPreference
getPreference(key) Retrieves the value of a preference specified by its key.
Parameters
Parameter key Type String Description Key of a preference
Returns
The preference value assigned to the specified key, or undefined, if the key is not found.
getBool
getBool(key) Retrieves the value of the specified preference as Boolean.
PUBLIC
391
Parameter key
Type String
Description Key of a preference
Returns
The Boolean value of the preference, or false, if no value is set or if the key is not found.
getString
getString(key) Retrieves the value of the specified preference as string. Parameter key Type String Description Key of a preference
Returns
The string value of the preference, or an empty string, if no value is set or if the key is not found.
Example
<script language ="JavaScript"> ... var val = gadgetPrefsApi.getPreference(key); var boolVal = gadgetPrefsApi.getBool(key); if (boolVal){ var strVal = gadgetPrefsApi.getString(key); } else { var strVal = Value not set; }... </script> Related Information SetPreference [page 393] A method of the GadgetPrefs API that can be used to set a preference of a widget.
392
PUBLIC
9.3.4.3.2
SetPreference
A method of the GadgetPrefs API that can be used to set a preference of a widget.
setPreference(key,value)
Sets a preference of a widget by defining a key-value pair.
Parameters
Parameter key value Type String String Description Key of a preference Value of the key
Example
<script language ="JavaScript"> ... var gadgetPrefsApi= new gadgets.GadgetPrefs(); gadgetPrefsApi.setPreference (key1,value1); ... </script> Related Information GetPreference [page 391] The GadgetPrefs API provides methods for retrieving persisted preferences of a widget.
9.3.4.3.3
Enabling Widget Customization
Customization of widgets is enabled by defining custom widget properties. You can define customizable widget properties than can be set both at design time and at runtime. Customized property values of a widget instance, set at design time, take effect for all users, whereas the values set by an end user at runtime take effect just for this user. These properties are defined in the spec XML file of a widget within the<UserPref> tag of the following structure: <UserPref name="<pref name>" default_value="<default_value>" datatype="pref_type"> </UserPref>
PUBLIC
393
The following table lists the supported property data types, their possible values and the UI controls in which they are displayed in the widget's Properties box. Type bool enum string Possible Values "true", "false" Custom enumeration Any string Corresponding UI Control Checkbox Dropdown box Text field
Enum type properties have additional attributes, as shown below: <UserPref name="color" default_value="Aqua" datatype="enum"> <EnumValue value="red" display_value="Red"/> <EnumValue value="orange" display_value="Orange"/> <EnumValue value="white" display_value="White "/> </UserPref> The following sample illustrates how to define and set customizable widget properties: <Module> <ModulePrefs title="Widget Properties"> <Require feature="gadgetprefs" /> </ModulePrefs> <UserPref name="color" default_value="Aqua" datatype="enum"> <EnumValue value="red" display_value="Red" /> <EnumValue value="aqua" display_value="Aqua" /> <EnumValue value="lime" display_value="Lime" /> </UserPref> <UserPref name="title" default_value="widget title" /> <UserPref name="controlVisibilityFlag" default_value="true" datatype="bool" /> <Content type="html"> <![CDATA[ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <script language="javascript" type="text/javascript"> function widgetCallback(status) { if (status == false) document.getElementById('comments').innerHTML = "Could not the set the property."; else document.getElementById('comments').innerHTML = "Property set successfully."; } var widgetPrefs = new gadgets.GadgetPrefs(); window.onload = initiateWidgetProperties; function initiateWidgetProperties() { setBGcolor(); } function setColor() { var selectedColor = document.getElementById('color').value; widgetPrefs.setPreference('color', selectedColor, widgetCallback); setBGcolor(); } function setBGcolor() { var currentColor = widgetPrefs.getString("color");
394
currentColor);
document.getElementById('main').setAttribute("bgcolor", } function stringSample() { var currentTitle = widgetPrefs.getString('title'); widgetPrefs.setPreference('title', wantedTitle, widgetCallback); }
function boolSample() { var currentTitleMode = widgetPrefs.getBool('controlVisibilityFlag') ; if (currentTitleMode) { widgetPrefs.setPreference('controlVisibilityFlag', "false", widgetCallback); } else { widgetPrefs.setPreference('controlVisibilityFlag', "true", widgetCallback); } } </script> </head> <body id="main" bgcolor="#F290F0" style="font-family:Arial;"> <div id="contDiv"> <label for="unittype">Select Color:</label> <select name="color" id='color'/> <option value="red"> Red </option> <option value="aqua"> Aqua </option> <option value="lime" selected> Lime </option> </select> <input type="button" id='colorButton' value="Change Color" onClick="setColor();"/><br/><br/> </div> </body> </html> ]]> </Content> </Module> Related Information GadgetPrefs API [page 390] Provides methods to persist widget preferences on the server side. Setting Widget Properties [page 383] You can customize a widget instance in an application site by setting its properties.
9.3.4.4
SetTitle
A method that can be used to set a widget's title.
setTitle(title) Use to set the title of a widget in the current session. The title is not persisted across sessions.
PUBLIC
395
To use the API, declare this feature under the <ModulePrefs> tag of the widget's specification file: <ModulePrefs> <Require feature="settitle"/> </ModulePrefs>
Parameters
Parameter title Type String Description Title of a widget
Example
<script language ="JavaScript"> ... var newTitle="Hello World"; gadgets.window.setTitle(newTitle); ... </script>
396
10 Enabling Search
With a SAP HANA database, your users will want to search tables and views much like they would when searching for information on the Internet. In SAP HANA, you can either directly query data using SQL queries or build search UIs using SAP HANA info access.
Prerequisites
Before enabling search, note the following prerequisites: Your SAP HANA database must contain column-oriented tables. A valid data type must be assigned to each column. The data types of the columns determine how you can query your data.
Context
In SAP HANA, you can search on single or multiple columns of almost any visible data type. In addition to standard string search, SAP HANA also supports full text search. During a full text search, the SAP HANA search engine examines both structured text, such as author and date attributes, and unstructured text, such as body text. Unlike a string search, the sequence of words and characters used for a text search is not critical for finding matches. A full text index enables this functionality by analyzing and preprocessing the available text semantically. This includes normalization, tokenization, word stemming, and parts of speech tagging. To enable search, proceed as follows:
Procedure
1. Create any required full text indexes for the columns in the table. 2. 3. For columns defined with the data type TEXT or SHORTTEXT(n), full text indexes are automatically generated. For columns of any other data type, you have to create any required full text indexes manually. When you create a full text index, you can also define synchronization and trigger text analysis. Build SQL search queries. Search queries use the SQL SELECT statement. For searches on large object types or text, the queries must include the CONTAINS predicate.
Optionally, build search apps using SAP HANA Info Access. SAP HANA Info Access provides a front-end JavaScript API and a UI toolkit with pre-defined widgets for developing browser-based search apps for end users. Toolkit and API connect to the database using the SAP HANA Info Access service that wraps search SQL queries and exposes them through an HTTP interface.
SAP HANA Developer Guide Enabling Search
PUBLIC
397
10.1 Creating Full Text Indexes

When you create a TEXT or SHORTTEXT column in a table, SAP HANA automatically creates a corresponding full text index. For columns of other data types however, you have to create and define any necessary full text indexes manually.
Context
A full text index is an additional data structure that is created to enable text search features on a specific column in a table. Conceptually, full text indexes support searching on columns in the same way that indexes support searching through books. To create a full text index, proceed as follows:
Procedure
1. 2. Determine the columns that you require an index for. Use the CREATE FULLTEXT INDEX statement to create an index with the specified index name. CREATE FULLTEXT INDEX <index_name> ON <tableref> '(' <column_name> ')' [<fulltext_parameter_list>] 3. Specify any of the following additional parameters for the full text index: LANGUAGE COLUMN <column_name> LANGUAGE DETECTION '(' <string_literal_list> ')' MIME TYPE COLUMN <column_name> FUZZY SEARCH INDEX <on_off> PHRASE INDEX RATIO <on_off> CONFIGURATION <string_literal> SEARCH ONLY <on_off> FAST PREPROCESS <on_off> TEXT ANALYSIS <on_off> MIME TYPE <specified mime type, e.g. application/pdf> To set |SYNC |ASYNC |ASYNC |ASYNC |ASYNC the synchronization, specify one of the folowing parameters: FLUSH [QUEUE] EVERY n MINUTES FLUSH [QUEUE] AFTER n DOCUMENTS FLUSH [QUEUE] EVERY n MINUTES OR AFTER m DOCUMENTS
If you do not specify any parameters, the default values are used.
Note
For a complete list of parameters available see Full Text Index Parameters [page 411]. The system creates a separate hidden full text index column for each source column that you have specified. You can now create queries to search these columns.
398
PUBLIC
Results
You can check the parameters of an existing full text index by using the SYS.FULLTEXT_INDEXES monitoring view.
Example
You want to create a full text index i1 for table A, column C, with the following characteristics: Synchronous processing Fuzzy search index disabled Languages for language detection: English, German, and Korean
To create the index, you use the following syntax: CREATE FULLTEXT INDEX i1 ON A(C) FUZZY SEARCH INDEX OFF SYNC LANGUAGE DETECTION ('EN','DE','KR') Related Information Full Text Index Types [page 399] SAP HANA automatically creates full text indexes for columns of type TEXT and SHORTTEXT(n). For other column types, you must manually create any required full text indexes. Synchronization [page 403] Full text indexes in a SAP HANA database must be created and updated in synchronization with the corresponding columns. This synchronization can be either synchronous or asynchronous. Full Text Index Parameters [page 411] The content and behavior of a full text index is configured by the use of both default and user-specified parameters. To view the configuration of a full text index, you use the SYS.FULLTEXT_INDEXES view.
10.1.1
Full Text Index Types
SAP HANA automatically creates full text indexes for columns of type TEXT and SHORTTEXT(n). For other column types, you must manually create any required full text indexes. Characteristic SQL data type exposed to user Data returned by SELECT TEXT NCLOB SHORTTEXT (n) NVARCHAR(n) Manually Created Original data type Original data
Original data (returns Original data normalized data if the SEARCH_ONLY parameter is ON) SYNC Yes (via drop column) SYNC Yes (via drop column) Yes
SQL insertion mode Drop index
SYNC or ASYNC Yes Yes
Text search via CONTAINS Yes
PUBLIC
399
Characteristic SQL string search Change parameters of full text index Rebuild index Base type can be changed
TEXT Not possible Partially No No
SHORTTEXT (n) Possible Partially No No
Manually Created Depends on underlying data type All (with rebuild) Yes No (no dependency between base-column and index available)
10.1.1.1
TEXT Indexes
In a SAP HANA database, when you create a table that contains large text documents, you can define the columns with the TEXT data type. This data type allows you to query large text documents and present content excerpts in search hit lists. You can also reconstruct the document and display it in its original formatting. When you create a TEXT column and insert content, SAP HANA extracts and processes the text from the original document and then automatically generates a full text index for the column. To create this full text index, SAP HANA replaces the original data in the column with the processed text. This text is then returned with the data type NCLOB. The original data is no longer available. If you insert new entries in the TEXT column, the full text index is automatically and synchronously updated.
Example
CREATE COLUMN TABLE <tablename> ( k int primary key, content TEXT )
FAST PREPROCESS OFF PHRASE INDEX RATIO 0.77
Limitations
The TEXT data type has the following search-relevant limitations: SQL string searches are not supported. The SQL functions CONCAT and JOIN are not supported. TEXT columns cannot be converted to other data types. Text analysis is not supported.
For TEXT columns, SAP HANA does not support the following SQL expressions: HAVING
400
PUBLIC
WHERE with strings or non-alphanumeric characters ORDER BY GROUP BY Aggregate expressions (COUNT, MIN, MAX, etc.) JOIN ON
Changes to TEXT Indexes

TEXT full text indexes are automatically generated and you do not specify names for them; therefore, you cannot directly manipulate them. However, when you create, alter, or drop a table column, the same change is automatically applied to the full text index for that column. By using the ALTER TABLE statement to affect changes on the index, you can alter the following parameters: PHRASE INDEX RATIO FUZZY SEARCH INDEX
10.1.1.2
SHORTTEXT(n) Indexes
If the tables in your SAP HANA database contain columns with text strings that are relatively short in length, you can define those columns with the SHORTTEXT(n) data type. The SHORTTEXT(n) data type enables both SQL string search and full text search capabilities. SAP HANA preprocesses the text in the column and stores that preprocessed text as a full text index in a hidden column attached to the original column. When queried, the text in the full text index returns with the NVARCHAR data type. The original text is still available; however, search queries are performed, by default, on the text in the index. When you create a column table and define a column with the data type SHORTTEXT(n), as in the following example, a full text index is automatically generated. Whenever new entries are then inserted in the column, the full text index is automatically and synchronously updated.
Example
CREATE COLUMN TABLE <tablename> ( k int primary key, content SHORTTEXT(100) )
FAST PREPROCESS OFF SEARCH ONLY ON
PUBLIC
401
Changes to SHORTTEXT(n) Indexes

SHORTTEXT(n) full text indexes are automatically generated and you do not specify names for them; therefore, you cannot directly manipulate them. However, when you create, alter, or drop a table column, the same change is automatically applied to the index for that column. When using the ALTER TABLE statement to affect changes on the index, you can only alter the following parameters: PHRASE INDEX RATIO FUZZY SEARCH INDEX
Note
You cannot change the length of the original text and you cannot convert SHORTTEXT(n) to another data type.
10.1.1.3
Manually Created Indexes
If the tables in your SAP HANA database contain extensive columns that are frequently queried but do not have automatically generated full text indexes, meaning they are not TEXT or SHORTTEXT(n) type columns, you can improve search performance by manually creating full text indexes. To manually create a full text index, the column must have one of the following SQL data types: VARCHAR NVARCHAR ALPHANUM CLOB NCLOB BLOB
When you manually create an index, the system attaches a hidden column to the specified column. This hidden column contains textual data that SAP HANA Preprocessor has extracted from the text in the source column. The original text in the source column remains unchanged. Search queries are then performed on the hidden column; however, they always return the original text. Depending on the data type that is assigned to a source column, string search may be possible. You can manually create an index directly after creating a table or you can create the index later. Once you create an index for a column, the system automatically processes any text that is inserted into this column and adds the processed text to the index. Processing for manually created indexes can be performed synchronously or asynchronously. You can specify different parameters when you create a full text index. If parameter changes are required later, you can change the values for the existing index directly or re-create the index with the parameters that you want to change. Related Information Creating Full Text Indexes [page 398] When you create a TEXT or SHORTTEXT column in a table, SAP HANA automatically creates a corresponding full text index. For columns of other data types however, you have to create and define any necessary full text indexes manually.
402
Altering Full Text Index Parameters [page 410] You can alter a full text index after it is created. Altering an index includes changing the values of the parameters and altering the parameters by replacing the index. Synchronization [page 403] Full text indexes in a SAP HANA database must be created and updated in synchronization with the corresponding columns. This synchronization can be either synchronous or asynchronous. Full Text Index Parameters [page 411] The content and behavior of a full text index is configured by the use of both default and user-specified parameters. To view the configuration of a full text index, you use the SYS.FULLTEXT_INDEXES view.
10.1.2 Synchronization
Full text indexes in a SAP HANA database must be created and updated in synchronization with the corresponding columns. This synchronization can be either synchronous or asynchronous.
Synchronous
In SAP HANA, indexes of the type TEXT and SHORTTEXT(n) are synchronous. Text preprocessing is automatically performed when a column is created or new text is inserted and the full text index is then automatically updated. The system cannot transport any data to the proper database tables until text preprocessing is complete.
Asynchronous
If you manually create a full text index, you can specify whether the index is synchronous or asynchronous. By default, manually created indexes are asynchronous. Text preprocessing is not initially performed when the table or column is created or whenever new text is inserted. In this case, inserting the results of the text preprocessing and writing the original data do not occur at the same time. Therefore, the full text information may not be immediately available for searching. To handle asynchronous processing of text, SAP HANA uses queues.
10.1.2.1
Queues
The queue is a mechanism used to enable a full text index to operate asynchronously. This means that when you insert new entries into the column, the text is not made available in the column until it is preprocessed. When you insert new entries, the queue sends the text to the preprocessor for analysis. It returns a serialized instance of a DAF (document analysis format) object, which is then processed further by the HANA column store. The result is stored in the full text index.
PUBLIC
403
The SAP HANA queue manager automatically creates a queue when you create an asynchronous full text index or when the index server is started and the queue manager finds the information that a specific queue is needed. The queues are always created on the server on which the table is stored. Every entry in the queue has one of the following processing states: New Preprocessing Preprocessed Indexing Error
If the original column entry is modified or deleted during text processing, the queue is notified and, if necessary, the entry is preprocessed again.
Note
The content of the queue is not made persistent at any stage. If the HANA index server process fails, the queue data is lost and the queue manager automatically restarts the process for those entries that were not already processed. Any incomplete text preprocessing is restarted from the beginning.
Flush Scheduling
When you create an asynchronous full text index, you can specify when documents are removed from the queue after they are preprocessed and inserted into the full text index; this is called flushing. You can schedule flushing based on either time or the number of documents. To do this, when you create the full text index, define one of the following clauses with the ASYNC parameter: FLUSH EVERY (n) MINUTES FLUSH AFTER (n) DOCUMENTS FLUSH EVERY (n) MINUTES OR AFTER (m) DOCUMENTS
Note
You cannot specify negatives values for minutes or documents. To determine when the queue of an existing full text index is flushed, see the FLUSH_EVERY_MINUTES and FLUSH_AFTER_ROWS attributes in the view FULLTEXT_INDEXES. Related Information Manipulating Queue Processing [page 405] By default, queues are active initially and run automatically based on the parameters you specify when creating the full text index. However, if necessary, you can manually manipulate the processing of an existing queue.
10.1.2.2
Encoding of the Synchronization Modes
The synchronization mode of an index is encoded in two attributes in the SYS.FULLTEXT_INDEXES view.
404
If you want to know which synchronization mode is set for an index, you can check and encode the values of the FLUSH_EVERY_MINUTES and FLUSH_AFTER_DOCUMENTS attributes in the SYS.FULLTEXT_INDEXES view. Sync Mode Clause SYNC ASYNC ASYNC FLUSH EVERY n MINUTES (n>0) ASYNC FLUSH AFTER n DOCUMENTS (n>0) ASYNC FLUSH EVERY n MINUTES OR AFTER m DOCUMENTS Value of Attribute FLUSH_EVERY_MINUTES 0 -1 n -1 n Value of Attribute FLUSH_AFTER_DOCUMENTS -1 -1 -1 n m
10.1.2.3
Manipulating Queue Processing
By default, queues are active initially and run automatically based on the parameters you specify when creating the full text index. However, if necessary, you can manually manipulate the processing of an existing queue.
Context
To manipulate the processing of a queue, the following commands are available: FLUSH Updates the full text index with the documents in the queue which have already been processed and removes them from the queue. SUSPEND Suspends the full text index processing queue ACTIVATE Activates the full text index processing queue if it has been suspended To manipulate the processing of a queue:
Procedure
1. 2. Identify which queue process you want to manipulate by using the monitoring view M_FULLTEXT_QUEUES. For information about the specific content of the view, see SAP HANA System Tables and Monitoring Views. Use the ALTER FULLTEXT INDEX statement to flush, suspend, or reactivate the queue. Use the following syntax: ALTER FULLTEXT INDEX <index name> FLUSH|SUSPEND|ACTIVATE QUEUE
PUBLIC
405
Related Information SAP HANA System Tables and Monitoring Views: M_FULLTEXT_QUEUES
10.1.3 Text Analysis

Text analysis provides a vast number of possible entity types and analysis rules for many industries in 20 languages. However, you do not have to deal with this complexity when analyzing your individual set of documents. The language modules included with the software contain system dictionaries and provide an extensive set of predefined entity types. The extraction process can extract entities using these lists of specific entities. It can also discover new entities using linguistic models. Extraction classifies each extracted entity by entity type and presents this metadata in a standardized format. The following data types are enabled for text analysis: NVARCHAR, VARCHAR, NCLOB, CLOB, and BLOB. The following text analysis options are delivered by SAP: Table 21: Options Name of Option LINGANALYSIS_BASIC Description This option provides the following language processing capabilities for linguistic analysis of unstructured data: LINGANALYSIS_STEMS Segmentation - the separation of input text into its elements
This option provides the following language processing capabilities for linguistic analysis of unstructured data: Segmentation - the separation of input text into its elements Stemming - the identification of word stems or dictionary forms
LINGANALYSIS_FULL
This option provides the following language processing capabilities for linguistic analysis of unstructured data: Segmentation - the separation of input text into its elements Stemming - the identification of word stems or dictionary forms Tagging - the labeling of words' parts of speech
EXTRACTION_CORE
This option extracts entities of interest from unstructured text, such as people, organizations, places, and other parties described in the document. In most use cases, this option is sufficient.
EXTRACTION_CORE_VOICEOFCUSTOMER
Voice of the customer content includes a set of entity types and rules that address requirements for extracting customer sentiments and requests. You can use this content to retrieve specific information about your customers' needs and perceptions when processing and analyzing text. The option involves complex linguistic analysis and pattern matching that
406
PUBLIC
Name of Option
Description includes processing parts of speech, syntactic patterns, negation, and so on, to identify the patterns to be extracted. Voice of the customer content is supported for the following languages: English French German Spanish Chinese (Simplified)
To use the text analysis function, create a full text index on the column containing your texts with the following parameters: TEXT ANALYSIS ON CONFIGURATION '<NAME OF OPTION>'
Note
The technical names of the options are case-sensitive. If your tables contain a language indicator, enter the name of the column: LANGUAGE COLUMN <NAME OF COLUMN CONTAINING THE LANGUAGE INDICATOR> If no language is specified, EN will be used by default. Once indexing starts, the text analysis runs in the background. Depending on the number and size of the texts, a single analysis can take a number of hours. To check the status of the text analysis, you can use the default monitoring view FULLTEXT_INDEXES. For each full text index, the system creates an additional table with the name $TA_<index_name> in the same schema that contains the source table. This table stores the extracted entities and the analysis results. You can use this table to build joins with other search-enabled views, for example to use the data for interactive navigation or auto-completion in search input fields. For detailed information on this table, see Structure of the $TA Table. To keep track of deletions in the source table, the keys in the $TA table need to be aligned to the keys of the source table. To do this, use the following SQL statement: ALTER TABLE "<schema>"."$TA_INDEX_NAME" ADD CONSTRAINT <constraint name> COMMAND FOREIGN KEY("key_1", "key_2", "key_n") REFERENCES "<schema>"."<name of source table>"("key_1","key_2","key_n") ON DELETE CASCADE If it beomes too large, you can partition the $TA_<index_name> table. Partitioning supports you by improving manageability and performance. For example, you can use the following command to partition the $TA table using the hash partition strategy: ALTER TABLE $TA_<index_name> PARTITION BY HASH (<PRIMARY_KEY_ATTR_1>, ... , <PRIMARY_KEY_ATTR_N>) PARTITIONS <N>
PUBLIC
407
Example
Use the CREATE FULLTEXT INDEX statement to create an index named CUSTOMER_INDEX on your CUSTOMERS table to index the customername column: CREATE FULLTEXT INDEX CUSTOMER_INDEX ON "MY_SCHEMA"."CUSTOMERS" ('customername')[<fulltext_parameter_list>] If you are triggering the text analysis using the EXTRACTION_CORE option, specify the following additional parameters for the full text index: TEXT ANALYSIS ON CONFIGURATION 'EXTRACTION_CORE' LANGUAGE COLUMN LANG ALTER TABLE "MY_SCHEMA"."$TA_CUSTOMER_INDEX" ADD CONSTRAINT ALTER_COMMAND FOREIGN KEY("KEY_1", "KEY_2") REFERENCES "MY_SCHEMA"."CUSTOMERS"("KEY_1","KEY_2") ON DELETE CASCADE Related Information Text Data Processing Language Reference Guide This guide describes in detail the standard extraction content and the linguistic analysis
10.1.3.1
Structure of the $TA Table
The $TA_<index_name> table is generated automatically when you trigger creation of the index. The table is built from the key fields of the source table, additional key fields TA_RULE and TA_COUNTER, and eight additional fields. Key fields of the source table Name of the analyzed column Entity type, for example DATE or NOUN_GROUP Entity value, for example October 29, 2010 or horizontal stabilizer Normalized entity value if available, for example 2010-10-29
Table 22: Structure of TA table Column ID <n key columns from source table> Key Yes Description Data Type
To support a foreign key definition linking Same as in source table from the $TA table to its source table, the $TA table has to use exactly the same key columns as its source table (in data type and ID). The $TA table includes all keys from the source table.
TA_RULE
Yes
Stores the rule package that yielded the token. This is also required to distinguish between LXP output and output from the entity extraction.
NVARCHAR(200)
408
Column ID TA_COUNTER
Key Yes
Description The token counter counts all tokens across the document. The order is only unique for a given processing type (hence the previous attribute as key). Term or entity - depending on the processing type.
Data Type BIGINT
TA_TOKEN TA_LANGUAGE
NVARCHAR(250)
The language of the document is usually NVARCHAR(2) stated in the source table. In rare cases where this is not the case, the language code is stored here. Since there is no support for multi-language documents, the language code is identical for all result records of a document. The token type contains the linguistic or semantic type of the token, for instance "noun" (if option = LINGANALYSIS_*) or "company" (if option = EXTRACTION_*). Stores a normalized representation of the token. This becomes relevant for example in the case of German, with umlauts, or /ss. Stores the linguistic stemming information, for example the singular nominative for nouns, or the indicative for verbs. If text analysis yields several stems, only the first stem is stored, assuming this to be the best match. Stores the total number of paragraphs in the document. Stores the total number of sentences in a document. NVARCHAR(100)
TA_TYPE
TA_NORMALIZED
NVARCHAR(250)
TA_STEM
NVARCHAR(300)
TA_PARAGRAPH TA_SENTENCE TA_CREATED_AT
INTEGER INTEGER
Stores the creation time. Used only for TIMESTAMP administrative information, for reorganization for example . Stores the offset in characters relative to the beginning of the document. BIGINT
TA_OFFSET
The $TA table can be modified like any other table, but cannot be partitioned. You can add additional columns to this table, with a statement like ALTER TABLE "TA"."$TA_SOURCE_TEXT_TA" ADD(C INTEGER GENERATED ALWAYS AS 1) for example. In this example, the value 1 is written only to existing rows in the new column C. The new column will not be filled automatically in delta updates.
PUBLIC
409
Note
If the source table has a field name identical to one of the default fields in the $TA table, you receive an error message after the CREATE FULTTEXT INDEX statement, prompting you to rename the field in the source table. Once you have renamed the corresponding field, you can execute the CREATE FULLTEXT INDEX statement again.
10.1.4 Dropping Full Text Indexes

If you want to delete a full text index that you manually created, for example, because it is referenced only rarely or preprocessing is too time-consuming, you can drop the full text index. For TEXT or SHORTTEXT full text indexes, you cannot drop the full text index; instead, you must delete the related column in the table.
Context
You also need to drop full text indexes when adding or removing index parameters. As parameters cannot be added to or removed from an existing full text index, if you want to change parameters, you must first drop the full text index and then create a new index with the new parameters. To drop a full text index, you use the DROP FULLTEXT INDEX statement: DROP FULLTEXT INDEX <index_name>
Note
Before you can drop a full text index, you must remove the relationship between the source table and any existing $TA tables (for text analysis). To do so, use the following statement: ALTER TABLE SCHEMA <$TA_table> DROP <name_constraint> The name constraint must be the same as originally used when adding the constraint. For more information, see Text Analysis. Related Information Altering Full Text Index Parameters [page 410] You can alter a full text index after it is created. Altering an index includes changing the values of the parameters and altering the parameters by replacing the index. Text Analysis [page 406]
10.1.5 Altering Full Text Index Parameters

You can alter a full text index after it is created. Altering an index includes changing the values of the parameters and altering the parameters by replacing the index.
410
Procedure
To alter the parameters of a full text index, use the ALTER FULLTEXT INDEX statement. You can only use this statement to alter the following parameters: Fuzzy search index Phrase index ratio
Example syntax: ALTER FULLTEXT INDEX <index_name> PHRASE INDEX RATIO <parameter value> FUZZY SEARCH INDEX <on_off> To alter any other parameter, you must replace the existing full text index as follows: a) Delete the existing full text index by using the DROP FULLTEXT INDEX statement. b) Create a new index using the new parameter values. Related Information Creating Full Text Indexes [page 398] When you create a TEXT or SHORTTEXT column in a table, SAP HANA automatically creates a corresponding full text index. For columns of other data types however, you have to create and define any necessary full text indexes manually. Synchronization [page 403] Full text indexes in a SAP HANA database must be created and updated in synchronization with the corresponding columns. This synchronization can be either synchronous or asynchronous. Queues [page 403] The queue is a mechanism used to enable a full text index to operate asynchronously. This means that when you insert new entries into the column, the text is not made available in the column until it is preprocessed. Full Text Index Parameters [page 411] The content and behavior of a full text index is configured by the use of both default and user-specified parameters. To view the configuration of a full text index, you use the SYS.FULLTEXT_INDEXES view.
10.1.6 Full Text Index Parameters

The content and behavior of a full text index is configured by the use of both default and user-specified parameters. To view the configuration of a full text index, you use the SYS.FULLTEXT_INDEXES view. In SAP HANA, full text indexes are configured using the following parameters: Parameter LANGUAGE_COLUMN Description Specifies the language used for analyzing the document. If no language is specified, the language is detected automatically. The detected language is stored in text attribute TEXT_AE and can be queried via LANGUAGE(columnName). With this option, you can refer to a column of the same database table where the language for the document is stored.
PUBLIC
411
Parameter
Description The column is read by the queue. Language columns in base tables should be of type NVARCHAR/ VARCHAR(m) where m>=2. Valid languages are listed in the SYS.M_TEXT_ANALYSIS_LANGUAGES view. Example values: 'EN', 'KO', 'DE'
MIME_TYPE_COLUMN
This column holds a mimetype indicator that is used for preprocessing. If this is empty or invalid, auto detection is used. Valid MIME types are listed in the SYS.M_TEXT_ANALYSIS_MIME_TYPES view. Example values: 'text/plain','text/html','application/pdf'
MIME_TYPE
Specifies the default MIME type used for preprocessing (see MIME TYPE COLUMN). If both MIME TYPE and MIME TYPE COLUMN are set, and if the corresponding cell for the MIME TYPE COLUMN is null, the value of parameter MIME TYPE is used for preprocessing. Example: You can specify MIME TYPE 'application/pdf' if the table contains only pdf content.
LANGUAGE_DETECTION
Specifies the set of languages to be used for automatic language detection. If reliable language detection cannot be performed, the first language in the list will be used as the default language. This option is used to limit the languages for text analysis. Example: LANGUAGE DETECTION ('EN','DE','JA') The language is specified in the ISO 639-1 (2 characters) and not in the ABAP format (1 character with conversion exit)
FAST_PREPROCESS
Specifies whether fast preprocessing should be performed. With fast preprocessing, the language detection just returns the default language, which is 'EN'. Linguisitic analysis is skipped, and only a simple tokenizer is used. This simple tokenizer does not work for languages which do not use spaces as word separators (like Japanese). It cannot handle binary documents either. If this option is enabled, a special index is created for the fuzzy search. This index accelerates the fuzzy search, but uses additional memory. If set to ON, the original content is not stored in the text attribute. You can get a reconstructed version of the document, but it may deviate from the original content. It is not possible to show the document in its original formatting when using the highlight function or to retrieve the HTML-converted data from the text attribute. The document will use less memory however. If the text attribute is created via a manually created full text index, the source attribute that contains the original data is not affected by this setting.
FUZZY_SEARCH_INDEX
SEARCH_ONLY
SYNC
Insert/Update calls do not return until all documents have been preprocessed and inserted into the fulltext index.
412
Parameter ASYNC
Description Insert/Update calls may return before all documents are preprocessed and inserted into the fulltext index. However, preprocessing and insertion into fulltext index starts immediately upon insert/update call. Like ASYNC, but insertion into fulltext index takes place every n minutes instead of immediately upon insert/update call. Preprocessing still start immediately. Like ASYNC, but insertion into fulltext index takes place after m new documents have inserted/updated instead of immediately upon insert/update call. Preprocessing still start immediately. Like ASYNC, but insertion into fulltext index takes place every n minutes or after m new documents have been inserted/updated instead of immediately upon insert/ update call. Preprocessing still start immediately. You can use one of the following types of text analysis delivered by SAP: LINGANALYSIS_BASIC LINGANALYSIS_STEMS LINGANALYSIS_FULL EXTRACTION_CORE EXTRACTION_CORE_VOICEOFCUSTOMER
ASYNC FLUSH EVERY n MINUTES ASYNC FLUSH AFTER m DOCUMENTS
ASYNC FLUSH EVERY n MINUTES OR AFTER m DOCUMENTS CONFIGURATION
Specifies the type of text analysis to be used. This parameter requires the setting TEXT ANALYSIS = ON. For more information about the types of text analysis, see Text Analysis [page 406]. PHRASE_INDEX_RATIO Stores information about the occurrence of words and the proximity of words to one another. If a phrase index is present, phrase searches are sped up (e.g. SELECT * FROM T WHERE CONTAINS(COLUMN1, '"cats and dogs"')) . The float value is between 0.0 and 1.0. 1.0 means that the internal phrase index can use 100% of the memory size of the fulltext index. TEXT ANALYSIS Enables text analysis capabilities on the indexed column. This parameter cannot be enabled for TEXT or SHORTTEXT columns. If set to ON, the FAST PREPROCESS parameter is automatically set to OFF. Text analysis can extract entities such as persons, products, or places from documents, and thus enriches the set of structured information in SAP HANA. You can use these additional attributes, which are stored in a new table, when creating models (views) for analytics and search scenarios to enable improved analytics and search in SAP HANA. For more information, see Text Analysis [page 406].
PUBLIC
413
10.1.6.1
Memory Consumption of Full Text Index Parameters
In SAP HANA, certain full text index parameters can have a significant impact on memory consumption based on how they are defined. The following full text index parameters can have a significant impact on memory consumption: Parameter PHRASE_INDEX_RATIO Memory Impact Details If the value is greater than 0.0, then there is additional memory overhead. The maximum memory consumption is the memory consumption of the full text index multiplied by the parameter value. To increase response times for fuzzy search, when enabled, this parameter creates additional in-memory structures. For text-type columns, fuzzy search indexes require approx. 10% of the memory size of the column. If set to ON, an additional table is created for storing structured data extracted from the source text for text analysis. The amount of extracted data depends on the data in the source column, the text analysis rules, and the structure of the results. In certain cases, the memory consumption of the extracted data could exceed the memory consumption of the source data.
FUZZY_SEARCH_INDEX
TEXT ANALYSIS
10.2 Building SQL Search Queries

In column-oriented tables, you can perform searches using the SQL SELECT statement.
Prerequisites
Before building SQL search queries, the following prerequisites must be met: The tables you want to search are column-oriented. You have created any required views for the tables you want to search. You have created any required full text indexes for the columns you want to search.
414
PUBLIC
Context
SAP HANA supports the standard SQL search syntax and functions for search queries on nearly all visible data types. You build SQL queries using the SELECT statement, as in the following example: SELECT * FROM Contacts WHERE ID=1 However, in SAP HANA, columns of large object types and text have additional requirements. To enable search on columns of these types, you must ensure the following requirements are met: Full text indexes have been created for the search-relevant columns. For columns of type TEXT and SHORTTEXT, this is done automatically. Search queries on the columns use the CONTAINS predicate.
For large object types and text, you build SQL queries using the SELECT statement and CONTAINS predicate, as in the following example: SELECT * FROM Documents WHERE CONTAINS (*,'Comment') To build a search query, proceed as follows:
Procedure
1. 2. 3. Use the SQL SELECT statement and specify the table or view and column you want to search. If required, include the CONTAINS predicate. If required, specify scalar functions for the search. Specify the search terms and, optionally, the search type (EXACT, LINGUISTIC, or FUZZY).
Note
If you do not specify a search type, by default, the search query is performed as an exact search.
Example
For further examples of the syntax used with the SELECT statement, see SAP HANA SQL and System Views Reference. Related Information SAP HANA SQL and System Views Reference
10.2.1 Search Queries with CONTAINS

In SAP HANA, you can search one or multiple columns by creating a query that includes the CONTAINS predicate. In SAP HANA, a search query with CONTAINS has a look and feel similar to common Internet search engines.
PUBLIC
415
The CONTAINS predicate is optional for search queries on columns of most data types; however, for large object types and text, this predicate is mandatory. You can build a search query with the CONTAINS predicate as follows: SELECT * FROM <tablename> WHERE CONTAINS ((<column1>, <column2>, <column3>), <search_string>) When you specify the CONTAINS predicate, SAP HANA runs the following internal checks: SAP HANA checks if the query contains one or more terms. If the query contains multiple terms, the terms are tokenized and concatenated. SAP HANA checks whether the query is to be run on one or more columns. If you only specify one column, to optimize the search, additional processes are skipped and the query is run on the single column. If you specify a wildcard, and therefore possibly numerous columns, SAP HANA automatically determines which columns are relevant for the search query.
After the checks are performed, SAP HANA builds and runs an internal query on the relevant columns only.
Note
If a column has a full text index assigned, SAP HANA will automatically search on the index rather than on the original column.
Determination of Search-Relevant Columns

You can specify the search-relevant columns either at the creation of the view or directly for the query. SAP HANA determines which relevant columns to search based on the following hierarchy: 1. 2. 3. You specify a list of columns within the CONTAINS predicate. Even if a list of columns has been defined for the view, it is overridden by the columns stated in the query. If you enter an asterisk (*) instead of a column list but you specified a list of relevant columns when creating the view, this list is used for the query. If you enter an asterisk (*) and no list was provided when the view was created, all visible columns of the view or table are considered as search-relevant.
For information about creating views, see Creating Views in the SAP HANA Administration Guide.
Search Operators and Syntax

With the CONTAINS predicate, SAP HANA supports the following search operators: OR Matches are returned that contain at least one of the terms joined by the OR operator. - (minus) With a minus sign, SAP HANA searches in columns for matches that do not contain the term immediately following the minus sign. " " (quotation marks) Terms within the quotation marks are not tokenized and are handled as a string. Therefore, all search matches must be exact.
416
Note
If you enter multiple search terms, the AND operator is automatically interpreted. Therefore, you do not need to specify it. For more information about the unique syntax requirements of the CONTAINS predicate, see the SAP HANA SQL and System Views Reference.
Scalar Functions
For search queries using the CONTAINS predicate, you can use different scalar functions to either return additional information about the results of your search queries or enhance how the results are displayed. These functions include SNIPPETS, HIGHLIGHTED, and SCORE.
Limitations
The following limitations apply to search queries using the CONTAINS predicate: You cannot search on more than one table or view at a time. If more than one table is joined in the SELECT statement, then all columns mentioned in the CONTAINS predicate must come from only one of the tables. You cannot enter a minus (-) search operator directly after OR. Brackets are not supported as search operators. Searches using the CONTAINS predicate do not consider non-physical columns, such as calculated columns, as search-relevant because these columns are created during the search and, therefore, are not available when SAP HANA internally checks the CONTAINS search query. The CONTAINS predicate only works on column-oriented tables. If you specify multiple CONTAINS predicates in the WHERE clause of the SELECT statement, only one of the predicates is allowed to consist of more than one column in the list of <contains_columns>. Related Information SAP HANA SQL and System Views Reference SAP HANA Administration Guide
10.2.1.1
SNIPPETS Function
For search queries using the CONTAINS predicate, you can use the function SNIPPETS to return search results with an excerpt of the text with your search term highlighted in bold. This short text excerpt provides some context for you to see where and how the term is used in the document. This function uses the following syntax: SELECT *, SNIPPETS (<text_column>) FROM <tablename> WHERE CONTAINS (<search_term>)
PUBLIC
417
Limitations
The SNIPPETS function has the following limitations: Only the first search term specified with the CONTAINS predicate is highlighted in the returned text. The query result contains only the first hit of the first search term. The text excerpt that is displayed with the search term is limited to a string of 12 tokens. This function only works on columns of the TEXT data type or columns with a full text index.
10.2.1.2
HIGHLIGHTED Function
For search queries using the CONTAINS predicate, you can use the function HIGHLIGHTED to return the content of the found document with your search term highlighted in bold. Search queries using the HIGHLIGHTED function return the data type NCLOB. This function uses the following syntax: SELECT *, HIGHLIGHTED (<text_column>) FROM <tablename> WHERE CONTAINS (<search_term>)
Limitations
The HIGHLIGHTED function has the following limitations: Only the first search term specified with the CONTAINS predicate is highlighted in the returned text. The query result contains all hits of the first search term. This function only works on columns of the TEXT data type or columns with a full text index.
10.2.1.3
SCORE Function
For search queries using the CONTAINS predicate, you can use the function SCORE to get the score, that means the relevance, of a record found. SAP HANA calculates a score based on the following information: The relevance or weighting of attributes in a search using the CONTAINS predicate. The relevance of a hit depends on the weight of the column that caused the hit. You can specify weights when you create the view or in the CONTAINS predicate. Fuzziness in fuzzy search. The more exact a hit is, the higher the score is. Text ranking (TF-IDF).
418
This function uses the following syntax: SELECT SCORE (),* FROM <tablename> WHERE CONTAINS (<search_term>)
10.2.2 EXACT Search

An exact search returns records only if the search term or search phrase is contained in the table column exactly as specified. In the SELECT statement of the search query, you can specify the EXACT search type. In an exact search, the search engine uses the word dictionary and the phrase index to detect the possible matches. The search engine then checks whether the words appear and use exactly the same spelling. For text columns, the search term must match at least one of the tokenized terms to return a column entry as a match. For string columns, the search term must match the entire string to return a column entry as a match.
Note
For more flexibility in a search query, you can use the supported wildcards % and *. Wildcards are supported for both text and string columns. You can perform an exact search by using the CONTAINS predicate with the EXACT option in the WHERE clause of a SELECT statement. The exact search is the default search type. If you do not specify any search type in the search query, an exact search will be executed automatically.
Example
SELECT * FROM <tablename> WHERE CONTAINS (<column_name>, <search_string>, EXACT) SELECT * FROM <tablename> WHERE CONTAINS (<column_name>, <search_string>) --- Exact search will be executed implicitly. SELECT * FROM <tablename> WHERE CONTAINS (<column_name>, '"cats and dogs"') --- Phrase search.
10.2.3 LINGUISTIC Search

A linguistic search finds all words that have the same word stem as the search term. It also finds all words for which the search term is the word stem. In the SELECT statement of the full text search query, you can specify the LINGUISTIC search type. When you execute a linguistic search, the system has to determine the stems of the searched terms. It will look up the stems in the stem dictionary. The hits in the stem dictionary point to all words in the word dictionary that have this stem
PUBLIC
419
You can call the linguistic search by using the CONTAINS predicate with the LINGUISTIC option in the WHERE clause of a SELECT statement. A linguistic search for produced will also find producing and produce.
Example
SELECT * FROM <tablename> WHERE CONTAINS (<column_name, 'produced' , LINGUISTIC)
Limitations
You can only perform linguistic searches on columns that meet the following conditions: The columns contain text. For the columns, the FAST_PREPROCESS parameter is specified as OFF.
10.2.4 FUZZY Search

Fuzzy Search is a fast and fault-tolerant search feature for SAP HANA. A fuzzy search returns records even if the search term contains additional or missing characters or other types of spelling errors. The term fault-tolerant search means that a database query returns records even if the search term (the user input) contains additional or missing characters or other types of spelling error. Fuzzy search can be used in various applications, for example: Fault-tolerant search in text columns (for example, html or pdf): Search for documents on 'Driethanolamyn' and find all documents that contain the term 'Triethanolamine'. Fault-tolerant search in structured database content: Search for a product called 'coffe krisp biscuit' and find 'Toffee Crisp Biscuits'. Fault-tolerant check for duplicate records: Before creating a new customer record in a CRM system, search for similar customer records and verify that there are no duplicates already stored in the system. When, for example, creating a new record 'SAB Aktiengesellschaft & Co KG Deutschl.' in 'Wahldorf', the system shall bring up 'SAP Deutschland AG & Co. KG' in 'Walldorf' as a possible duplicate.
You can call the fuzzy search by using the CONTAINS predicate with the FUZZY option in the WHERE clause of a SELECT statement.
Example
SELECT * FROM <tablename> WHERE CONTAINS (<column_name>, <search_string>, FUZZY (0.8))
420
10.2.4.1 Supported Data Types

Fuzzy search is only available for column tables and attribute views and supports the following SQL types and column store types. SQL Type Character String Types VARCHAR NVARCHAR SHORTTEXT Large Object (LOB) Types TEXT Datetime Types DATE Other FULLTEXT INDEX text features CS_DAYDATE date features CS_TEXT text features CS_STRING CS_STRING CS_STRING string features string features text features Column Store Type Supported Fuzzy Search Features
All other SQL types are not supported by fuzzy search.
String Types
String types support a basic fuzzy string search. The values of a column are compared with the user input, using the fault-tolerant fuzzy string comparison. When working with string types, the fuzzy string comparison always compares the full strings. If searching with 'SAP', for example, a record such as 'SAP Deutschland AG & Co. KG' gets a very low score, because only a very small part of the string is equal (3 of 27 characters match). For more information, see Fuzzy Search on String Columns [page 444].
Text Types
Text types support a more sophisticated kind of fuzzy search. Texts are tokenized (split into terms) and the fuzzy comparison is done term by term. For example, when searching with 'SAP', a record such as 'SAP Deutschland AG & Co. KG' gets a high score, because the term 'SAP' exists in both texts. A record such as 'SAPPHIRE NOW Orlando' gets a lower score, because 'SAP' is only a part of the longer term 'SAPPHIRE' (3 of 8 characters match). For more information, see Fuzzy Search on Text Columns [page 458].
PUBLIC
421
Date Types
Fuzzy search on date values checks for date-specific errors like dates that lie within a given range of days or dates that have month and day exchanged (for example, American versus British date format). For more information, see Fuzzy Search on DATE Columns [page 487].
10.2.4.2 Syntax
You can call the fuzzy search by using the CONTAINS() function with the FUZZY() option in the WHERE clause of a SELECT statement. For more information, see Using the CONTAINS() Predicate [page 422]. Basic example without additional search options SELECT SCORE() AS score, * FROM documents WHERE CONTAINS(doc_content, 'Driethanolamyn', FUZZY(0.8)) ORDER BY score DESC; Example with additional search options Additional search options that change the default behavior of the fuzzy search can be specified as additional string parameters in the FUZZY() function. SELECT SCORE() AS score, * FROM documents WHERE CONTAINS(doc_content, 'Driethanolamyn', FUZZY(0.8, 'option1=value1, option2=value2')) ORDER BY score DESC; The search options are specified as a comma-separated list of key-value pairs. For more information, see Available Fuzzy Search Options [page 435].
10.2.4.3 CONTAINS Predicate 10.2.4.3.1 Using the CONTAINS() Predicate
Supported Database Objects

Fuzzy search and the CONTAINS() predicate are available for SELECT statements on one column table or on one attribute view.
422
Note
The following operations and database objects are not supported: Joins between column tables or attribute views Row tables Database views created with the CREATE VIEW statement Calculation views Analytic views
Use Cases of CONTAINS()

The CONTAINS() predicate can be used in the WHERE clause of a SELECT statement. The type of search it performs depends on its arguments: 1. 2. 3. A freestyle search on multiple columns A full text search on one column containing large documents A search on one database column containing structured data
All searches can be done either as an exact search or as a fuzzy search with additional tolerance for writing errors. Freestyle Search on Multiple Columns -- exact search SELECT ... WHERE CONTAINS((col1, col2, col3), 'term1 term2 term3') ...; -- or SELECT ... WHERE CONTAINS((col1, col2, col3), 'term1 term2 term3', EXACT) ...; -- fuzzy search SELECT ... WHERE CONTAINS((col1, col2, col3), 'term1 term2 term3', FUZZY(0.7)) ...; Full Text Search on One Column Containing Large Documents To do a full text search, the column that is to be searched must be a text column. -- exact search SELECT ... WHERE CONTAINS(col1, 'term1 term2 term3') ...; -- fuzzy search SELECT ... WHERE CONTAINS(col1, 'term1 term2 term3', FUZZY(0.7)) ...; Search on One Database Column Containing Structured Data -- exact search SELECT ... WHERE CONTAINS(col1, 'term1 term2 term3') ...; -- fuzzy search SELECT ... WHERE CONTAINS(col1, 'term1 term2 term3', FUZZY(0.7)) ...;
PUBLIC
423
Multiple CONTAINS() Predicates in one SELECT

It is possible to use the CONTAINS() predicate more than once in a WHERE clause. In this case, only one CONTAINS() can be used for a freestyle search on multiple columns. All other calls to CONTAINS() can access a single column only. SELECT ... WHERE CONTAINS((col1, col2, col3), 'a b c', FUZZY(0.8)) AND CONTAINS(col4, 'x y z', FUZZY(0.7)) AND CONTAINS(col5, 'u v w', FUZZY(0.7)) AND ...
Reserved Words and Special Characters in the Search String

When searching with CONTAINS(), some terms and characters have a special meaning, as described below. For more information, see the text search documentation. Reserved Word/Special Character OR Description A search such as CONTAINS(col, 'sap OR hana') searches for all records that contain 'sap' or 'hana' in column 'col'. The OR keyword is case sensitive, so CONTAINS(col, 'sap or hana') searches for records that contain 'sap' and 'or' and 'hana'.
Note
If your search input contains an 'or', make sure that it is not in uppercase characters to avoid the OR semantics. Minus Sign (-)
A search such as CONTAINS(col, 'sap -hana') searches for all records that contain 'sap' but not 'hana'. If the second term is given as a phrase like in CONTAINS(col, 'sap "-hana"'), the database searches for records that contain 'sap' and '-hana'. In text columns, the '-' is removed from the second search term as it is a delimiter symbol.
Note
If your search input contains terms starting with a minus sign, make sure that these terms are enclosed in double quotes to avoid the NOT semantics. Double Quotes (") A search that is enclosed in double quotes is searched as a phrase. For example, CONTAINS(col, '"sap hana"')
424
PUBLIC
Reserved Word/Special Character
Description searches for all records that contain 'sap hana' as a phrase without any additional terms in between.
Asterisk (*)
The asterisk activates a wildcard search. In this case, no fuzzy search is done. An exact match with wildcards is called instead. The percent sign is replaced with an asterisk (*) and a wildcard search is called.
Percent Sign (%)
10.2.4.3.2 The SCORE() Function

When using CONTAINS() in the WHERE clause of a SELECT statement, the SCORE() function can be used to retrieve the score. This is a numeric value between 0.0 and 1.0. The score defines the similarity between the user input and the records returned by the search. A score of 0.0 means there is no similarity. The higher the score, the more similar a record is to the search input. When more than one CONTAINS() is given in the WHERE clause, the score is calculated as an average of the scores of all columns. SELECT SCORE(), col1, col2, ... FROM tab WHERE CONTAINS(col1, 'x y z') AND CONTAINS(col2, 'a b c') AND ... ORDER BY SCORE() DESC; It is possible to assign a weight to each column. The weight is used to calculate the score as a weighted average of the scores of all columns. If a weight is not given, the default weight is 1.0. LECT SCORE(), ... FROM tab WHERE CONTAINS((col1, col2, col3), 'a b c', FUZZY(0.8), WEIGHT(1.0, 0.5, 0.5)) AND CONTAINS(col4, 'x y z', FUZZY(0.7), WEIGHT(0.7)) AND CONTAINS(col5, 'u v w', FUZZY(0.7)) AND ... ORDER BY SCORE() DESC; For example, the condition col5 = 'u v w' is also used as part of the score calculation. SELECT SCORE(), ... FROM tab WHERE CONTAINS((col1, col2, col3), 'a b c', FUZZY(0.8)) AND CONTAINS(col4, 'x y z', FUZZY(0.7)) AND col5 = 'u v w' AND ... ORDER BY SCORE() DESC;
PUBLIC
425
10.2.4.3.3 Examples
Fuzzy Search on One Column
Procedure
1. Create the data. CREATE COLUMN TABLE companies ( id INTEGER PRIMARY KEY, companyname SHORTTEXT(200) FUZZY SEARCH INDEX ON ); INSERT INSERT INSERT INSERT INSERT INSERT 2. INTO INTO INTO INTO INTO INTO companies companies companies companies companies companies VALUES VALUES VALUES VALUES VALUES VALUES (1, (2, (3, (4, (5, (6, 'SAP Corp'); 'SAP in Walldorf Corp'); 'ASAP'); 'ASAP Corp'); 'BSAP orp'); 'IBM Corp');
Perform the search on one column. SELECT SCORE() AS score, * FROM companies WHERE CONTAINS(companyname,'xSAP Corp Walldorf', FUZZY(0.7,'textSearch=compare,bestMatchingTokenWeight=0.7')) ORDER BY score DESC; SCORE 0.94 ID 2 COMPANYNAME SAP in Walldorf Corp
Fuzzy Search on Two Columns
Procedure
1. Create the data. CREATE COLUMN ( id companyname contact ); INSERT INSERT INSERT INSERT INSERT INSERT INTO INTO INTO INTO INTO INTO TABLE companies2 INTEGER PRIMARY KEY, SHORTTEXT(200) FUZZY SEARCH INDEX ON, SHORTTEXT(100) FUZZY SEARCH INDEX ON VALUES VALUES VALUES VALUES VALUES VALUES (1, (2, (3, (4, (5, (6, 'SAP Corp', 'Mister Master'); 'SAP in Walldorf Corp', 'Master Mister'); 'ASAP', 'Nister Naster'); 'ASAP Corp', 'Mixter Maxter'); 'BSAP orp', 'Imster Marter'); 'IBM Corp', 'M. Master');
companies2 companies2 companies2 companies2 companies2 companies2
426
2.
Perform the search on two columns. SELECT SCORE() AS score, * FROM companies2 WHERE CONTAINS(companyname, 'IBM', FUZZY(0.7,'textSearch=compare,bestMatchingTokenWeight=0.7')) AND CONTAINS(contact, 'Master', FUZZY(0.7,'textSearch=compare,bestMatchingTokenWeight=0.7')) ORDER BY score DESC; SCORE 0.91 ID 6 COMPANYNAME IBM Corp CONTACT M. Master
3.
Perform a freestyle search. SELECT SCORE() AS score, * FROM companies2 WHERE CONTAINS((companyname,contact), 'IBM Master', FUZZY(0.7)) ORDER BY score DESC; SCORE 0.8 ID 6 COMPANYNAME IBM Corp CONTACT M. Master
Note
Freestyle searches always use TF/IDF to calculate the score and do not support parameters like 'textSearch=compare' or 'bestMatchingTokenWeight=0.7' which influence score calculation. This therefore results in a different score for the same record.
Perform a Freestyle Search on Two Columns
Context
Procedure
1. Create the data. CREATE COLUMN ( id companyname contact ); TABLE companies2 INTEGER PRIMARY KEY, SHORTTEXT(200) FUZZY SEARCH INDEX ON, SHORTTEXT(100) FUZZY SEARCH INDEX ON
INSERT INTO companies2 VALUES (1, 'SAP Corp', 'Mister Master'); INSERT INTO companies2 VALUES (2, 'SAP in Walldorf Corp', 'Master Mister'); INSERT INTO companies2 VALUES (3, 'ASAP', 'Nister Naster');
PUBLIC
427
INSERT INTO companies2 VALUES (4, 'ASAP Corp', INSERT INTO companies2 VALUES (5, 'BSAP orp', INSERT INTO companies2 VALUES (6, 'IBM Corp', 2. Perform a freestyle search on two columns.
'Mixter Maxter'); 'Imster Marter'); 'M. Master');
SELECT SCORE() AS score, * FROM companies2 WHERE CONTAINS((companyname,contact), 'IBM Master', FUZZY(0.7)) ORDER BY score DESC; SCORE 0.83 ID 6 COMPANYNAME IBM Corp CONTACT M. Master
Note
Freestyle searches always use TF/IDF to calculate the score and do not support parameters that influence score calculationl, such as 'textSearch=compare' or 'bestMatchingTokenWeight=0.7' . This therefore results in a different score for the same record.
10.2.4.4 Fuzzy Score

The fuzzy search algorithm calculates a fuzzy score for each string comparison. The higher the score, the more similar the strings are. A score of 1.0 means the strings are identical. A score of 0.0 means the strings have nothing in common. You can request the score in the SELECT statement by using the SCORE() function. You can sort the results of a query by score in descending order to get the best records first (the best record is the record that is most similar to the user input). If a fuzzy search of multiple columns is used in a SELECT statement, the score is returned as an average of the scores of all columns used. When searching text columns, a TF/IDF (term frequency/inverse document frequency) score is returned by default instead of the fuzzy score. The fuzzy score influences the TF/IDF calculation, but it is important to keep in mind that, with TF/IDF, the range of the score values returned is normed to the interval between 0.0 and 1.0, and the best record always gets a score of 1.0, regardless of its fuzzy score. The TF/IDF calculation can be disabled so that you get the fuzzy score instead. In particular, this makes sense for short-text columns containing data such as product names or company names. On the other hand, you should use TF/IDF for long-text columns containing data such as product descriptions, HTML data, or Word and PDF documents.
10.2.4.4.1 Option similarCalculationMode

The option similarCalculationMode controls how the similarity of two strings (or, for TEXT attributes, terms) is calculated.
428
Score Calculation Modes

Basically, the similarity of two strings is defined by the number of common characters, wrong characters, additional characters in the search string, and additional characters in the reference string. The following calculation modes exist: Table 23: Modes Mode search compare (default) symmetricsearch substringsearch Impact on wrong characters high moderate high high Impact on additional characters in search high high moderate high Impact on additional characters in table low high moderate low
Note that a high impact results in a lower score. Table 24: Examples with score Request search search search Reference searching seerch Compa Search re 0.76 0.85 0.96 0.75 0.91 0.35 0.24 0.57 Symmetricsearch 0.86 0.75 0.87 0.84 0.79 0.6
searchingforextrater 0.0 restriallife 0.0 0.0 0.6
searchingforextrater searching restriallife searchingforextrater seerch restriallife searchingforextrater searchingforthemea restriallife ningoflife
SQL Examples
Preparations DROP TABLE test_similar_calculation_mode; CREATE COLUMN TABLE test_similar_calculation_mode ( id INTEGER PRIMARY KEY, s NVARCHAR(255) ); INSERT INTO test_similar_calculation_mode VALUES ('1','stringg'); INSERT INTO test_similar_calculation_mode VALUES ('2','string theory'); INSERT INTO test_similar_calculation_mode VALUES ('3','this is a very very very
PUBLIC
429
long string'); INSERT INTO test_similar_calculation_mode VALUES ('4','this is another very long string'); similarCalculationMode compare SELECT TO_INT(SCORE()*100)/100 AS score, id, s FROM test_similar_calculation_mode WHERE CONTAINS(s, 'strongtheory', FUZZY(0.5, 'similarCalculationMode=compare')) ORDER BY score DESC; Score 0.84 similarCalculationMode search SELECT TO_INT(SCORE()*100)/100 AS score, id, s FROM test_similar_calculation_mode WHERE CONTAINS(s, 'strongtheory', FUZZY(0.5, 'similarCalculationMode=search')) ORDER BY score DESC; Score 0.82 0.78 0.70 ID 2 4 3 S string theory this is another very long string this is a very very very long string ID 2 S string theory
similarCalculationMode symmetricsearch SELECT TO_INT(SCORE()*100)/100 AS score, id, s FROM test_similar_calculation_mode WHERE CONTAINS(s, 'strongtheory', FUZZY(0.5, 'similarCalculationMode=symmetricsearch')) ORDER BY score DESC; Score 0.80 0.69 0.62 0.54 ID 2 4 3 1 S string theory this is another very long string this is a very very very long string stringg
similarCalculationMode substringsearch SELECT TO_INT(SCORE()*100)/100 AS score, id, s FROM test_similar_calculation_mode WHERE CONTAINS(s, 'strongtheory', FUZZY(0.5, 'similarCalculationMode=substringsearch')) ORDER BY score DESC; Score 0.78 ID 2 S string theory
430
10.2.4.4.2 Option spellCheckFactor

The option spellCheckFactor defines the score for strings that are not identical but get a fuzzy score of 1.0. There are two use cases for the option spellCheckFactor: A) This option allows you to set the score for terms that are not fully equal but that would be a 100% match because of the internal character standardization used by the fuzzy search. For example, the terms 'Caf' and 'cafe' give a score of 1.0 although the terms are not equal. For some users it may be necessary to distinguish between both terms. The decision whether two terms are equal is based on the term representation stored in the column dictionary. Therefore, the spellCheckFactor option works differently on string and text columns, as described in the following sections. B) The fuzzy search can return a 100% match for terms that are not identical but cannot be differentiated by the fuzzy-string-compare algorithm. For example, the fuzzy search cannot differentiate between the terms 'abaca' and 'acaba'. In this case, the spellCheckFactor can be used to avoid a score of 1.0.
If A) and B) are not needed by an application, you can set the spellCheckFactor to 1.0 to disable the feature.
Standardization of Letters and Terms
All characters are replaced by lowercase characters without any diacritics before the fuzzy comparison takes place. This is called standardization. It is therefore possible to get a 100% match when comparing two unequal terms, because the standardization process returned two identical terms.
Standardization Examples
Original Letter E e Standardized Letter e e e e e e
The letter i is treated differently, since it is not standardized to an as would be the 'standard' rule. Original Letter I Standardized Letter i i
PUBLIC
431
Original Letter i German umlauts are replaced by two characters. Original Letter
Standardized Letter i i
Standardized Letter ae ae oe oe ue ue ss
Due to this standardization we get high fuzzy scores for common differences in the spelling of words. Original term mller Mueller Cafe Caf Standardized term mueller mueller cafe cafe
Search on a String Column (VARCHAR, NVARCHAR) The decision as to whether two strings are the same is based on the string representation stored in the dictionary for the column in question. The contents of a string column are converted to lowercase characters before being stored in the dictionary. No otther standardizations are carried out. It is therefore not possible to use the spellCheckFactor option for example to distinguish between 'caf' and 'cafe'.
Example
CREATE COLUMN TABLE test_spell_check_factor ( id INTEGER PRIMARY KEY, s NVARCHAR(255) ); INSERT INTO test_spell_check_factor VALUES ('1','Muller'); INSERT INTO test_spell_check_factor VALUES ('2','Mueller'); INSERT INTO test_spell_check_factor VALUES ('3','Mller');
432
INSERT INTO test_spell_check_factor VALUES ('4','Mller'); SELECT SCORE() AS score, id, s FROM test_spell_check_factor WHERE CONTAINS(s, 'Mller', FUZZY(0.5, 'spellCheckFactor=0.9')) ORDER BY score DESC; DROP TABLE test_spell_check_factor; SCORE 1.0 0.9 0.88 0.88 ID 3 2 1 4 T Mller Mueller Muller Mller << spellCheckFactor got used Description
Search on a Text Column (SHORTTEXT, TEXT or FULLTEXT INDEX)
Terms in text columns are standardized to lowercase characters without diacritics before being stored in the dictionary. In text columns it is therefore not possible to distinguish for example between 'caf' and 'cafe' or 'Mller' and 'mueller'. In this case, the search always returns a score of 1.0. The main use case of spellCheckFactor on text columns is therefore to avoid a score of 1.0 for terms like 'abaca' and 'acaba'.
Example
CREATE COLUMN TABLE test_spell_check_factor ( id INTEGER PRIMARY KEY, t SHORTTEXT(200) FUZZY SEARCH INDEX ON ); INSERT INSERT INSERT INSERT INTO INTO INTO INTO test_spell_check_factor test_spell_check_factor test_spell_check_factor test_spell_check_factor VALUES VALUES VALUES VALUES ('1','Muller'); ('2','Mueller'); ('3','Mller'); ('4','Mller');
SELECT SCORE() AS score, id, t FROM test_spell_check_factor WHERE CONTAINS(t, 'Mller', FUZZY(0.5, 'spellCheckFactor=0.9,textSearch=compare')) ORDER BY score DESC; DROP TABLE test_spell_check_factor; SCORE 1.0 1.0 ID 2 3 T Mueller Mller
PUBLIC
433
SCORE 0.88 0.88
ID 1 4
T Muller Mller
10.2.4.4.3 Option phraseCheckFactor

The phraseCheckFactor option defines the score of a search when the terms in a text field are not in the same order as in the user input. The phraseCheckFactor option defines the score of a search when the terms in a text field are not in the same order as in the user input (without any additional terms). The value of this option is multiplied with the overall fuzzy score of a text column if the search terms do not appear in the correct order. Search results returning terms in the exact term order as the search input get a higher score (see example below). The default value of this option is 1.0, so it has no influence on the score. The phraseCheckFactor search option is available for TEXT, SHORTTEXT and FULLTEXT INDEXES only. It is allowed for attribute searches only (no freestyle search). The phraseCheckFactor option is available for CONTAINS() only.
Note
Search rule sets are not supported at present.
Stopwords in the search input and in the database are ignored when comparing the order of the terms. Stopwords still influence the overall score however.
Example
CREATE COLUMN TABLE TAB_TEST (ID INT PRIMARY KEY, TEXT TEXT FAST PREPROCESS ON) ; INSERT INTO TAB_TEST VALUES ('1','International Business Machines'); INSERT INTO TAB_TEST VALUES ('2','Business Machines International'); SELECT to_decimal(score(),10,2) as SCORE, ID, TEXT FROM TAB_TEST WHERE CONTAINS (TEXT, 'International Business Machines', FUZZY(0.8, 'textSearch=compare, phrasecheckfactor=0.9')) ORDER BY SCORE DESC, ID; DROP TABLE TAB_TEST; Score 1.0 0.9 ID 1 2 Text International Business Machines Business Machines International (phraseCheckFactor got used)
434
PUBLIC
10.2.4.5 Available Fuzzy Search Options

Note that some data types in the table below are data-type combinations. String: SQL types VARCHAR and NVARCHAR Text: SQL types TEXT and SHORTTEXT and any columns that have an additional FULLTEXT INDEX Date: SQL type DATE
Table 25: Available Fuzzy Search Options Name of Option emptyScore Short Name es Range 0.0..1.0 Defa ult not set Applies to Types Text, String, Date Description Defines how an empty and a non-empty value shall match. For more information, see Option emptyScore [page 440] similarCalcul scm ationMode search, compare, symmetri csearch, substring search comp Text, String are Defines how the score is calculated for a comparison of strings (or terms in a Text column).
Note
Note that 'scm=substringsearch' is allowed for string columns only. For more information, see Option similarCalculationMode [page 428] .
spellCheckFac scf tor
0.0..1.0
0.9
Text, String
Sets the score for strings that get a fuzzy score of 1.0 but are not fully equal. For more information, see Option spellCheckFactor [page 431].
abbreviationS abs imilarity
0.0..1.0
0.0
Text
Activates abbreviation similarity and sets the score. For more information, see Option abbreviationSimilarity [page 468].
andSymmetric
as
on,off,tru e,false
off
Text
Activates a symmetric AND content search. For more information, see Partially Matching with Parameter andThreshold [page 466].
andThreshold
at
0.0..1.0
1.0
Text
Activates a 'soft AND' and determines the percentage of the tokens that need to match. For more information, see Partially Matching with Parameter andThreshold [page 466].
PUBLIC
435
Name of Option bestMatchingTo kenWeight
Short Name bmtw
Range 0.0..1.0
Defa ult 0
Applies to Types Text
Description Influences the score, shifts total score value between best token score values and root mean square of score values. For more information, see Option bestMatchingTokenWeight [page 461].
composeWords
cw
1..5
Text
The maximum number of consecutive words from user input to be composed (default value 1 means composition is disabled by default). For more information, see Option composeWords [page 483].
compoundWordW cww eight
0.0..1.0
0.9
Text
Term mapping weight for (de)compositions from (de)composeWords. For more information, see Option compoundWordWeight [page 485].
considerNonMa cnmt tchingTokens
max, min, max all, input, table
Text
Influences the score, defines the number of terms used for score calculation. For more information, see Option considerNonMatchingTokens [page 463].
decomposeWord dw s
1..5
Text
The maximum number of words a word from the user input is decomposed into (default value 1 means composition is disabled by default). For more information, see Option decomposeWords [page 484].
excessTokenWe etw ight
0.0..1.0
1.0
Text
Defines the weight of excess tokens to improve sort order. For more information, see Option excessTokenWeight [page 465].
minTextScore
mts
0.0..1.0
0.0
Text
Minimum score of a TEXT field; if not reached, the record will not be part of the result. For more information, see Option minTextScore [page 470].
phraseCheckFa pcf ctor
0.1..1.0
1.0
Text
The overall fuzzy score of a text column is multiplied with this value when the search terms do not appear in the correct order. For more information, see Option phraseCheckFactor [page 434]
436
Name of Option
Short Name
Range
Defa ult
Applies to Types Text
Description Activates the stopwords. For more information, see Usage [page 472].
stopwordListI sli d stopwordTable st not set
Text
Activates the stopwords. For more information, see Usage [page 472]
termMappingLi tmli stId
Text
Activates the term mappings. For more information, see Partially Matching with Parameter andThreshold [page 466].
termMappingTa tmt ble
not set
Text
Activates the term mappings. For more information, see Term Mappings [page 477].
textSearch
ts
fulltext, compare
fullte xt
Text, String, Date
Switches between full-text search with TF/IDF score and duplicate search with fuzzy score. For more information, see Option textSearch [page 471].
maxDateDistan mdd ce
0..100
Date
Specifies the allowed date distance when using fuzzy search on dates. For more information, see Fuzzy Search on DATE Columns [page 487].
10.2.4.5.1 Permitted Combinations of Fuzzy Search Parameters

Possible combinations of search options are shown in the table below. Depending on the following conditions, some of the searchOptions parameters might not be permitted, as they do not make sense: The data type of a column The type of the search (freestyle or attribute search) The selected method for score calculation on text columns (fuzzy score or TF/IDF, search option textSearch)
If the user sets an option that is not allowed, a SQL error is thrown, and the SELECT aborts. The search types used in the table below are Freestyle search: The CONTAINS() predicate uses more than one column. Attribute search: The CONTAINS() predicate uses a single column only Search on TEXT...: attribute search on a column of type TEXT, SHORTTEXT or other type with an additional FULLTEXT INDEX.
PUBLIC
437
Search on types other than TEXT: attribute search that is not performed on a TEXT column as defined above. Search on TEXT with Fuzzy Score Search on TEXT with TD/IDF Score Freestyle Search Search on Types Other Than TEXT
Attribute search and Attribute search and Freestyle search (full Attribute search and textSearch= textSearch=fulltext datatype <>TEXT text search with compare and and datatype=TEXT TD/IDF score) datatype= TEXT textSearch=compar e textSearch=fulltext similarCalculationM ode YES n/a YES n/a YES YES n/a n/a (default mode) YES NO NO YES (scm=substringsear ch is only valid for string types.) YES YES YES YES (Only valid for text, string and date types. Numeric types are not supported.) NO YES (Only valid for date types. Other types are not supported.) NO NO NO NO NO NO NO NO
spellCheckFactor fuzzySimilarity > 0 fuzzySimilarity = 0 emptyScore
YES YES YES YES
YES YES NO NO
YES YES NO NO
abbreviationSimilarit YES y maxDateDistance NO
NO NO
NO YES
termMappingTable/ ListId stopwordTable/ ListId andThreshold andSymmetric bestMatchingToken Weight
YES YES YES YES YES
YES NO NO NO NO NO NO NO
YES NO NO NO NO NO NO NO
considerNonMatchin YES gTokens excessTokenWeight minTextScore YES YES
438
Search on TEXT with Fuzzy Score phraseCheckFactor composeWords decomposeWords compoundWordWei ght rank Calculation YES YES YES YES fuzzy score
Search on TEXT with TD/IDF Score NO YES YES YES TF/IDF
Freestyle Search NO YES YES YES TF/IDF (text columns) or fuzzy score (other SQL types)
Search on Types Other Than TEXT NO NO NO NO Fuzzy score
Legend YES - The parameter is allowed. NO - The parameter is not allowed, and an error message is returned if the user sets this option.
10.2.4.5.2 Search Options and CONTAINS()

This section gives several examples of using search options and the CONTAINS() statement.
Example without specifying additional search options

SELECT SCORE() AS score, * FROM documents WHERE CONTAINS(doc_content, 'Driethanolamyn', FUZZY(0.8)) ORDER BY score DESC;
Example with additional search options

You can specify additional search options that change the default behavior of the fuzzy search as an additional string parameter for the FUZZY() function. SELECT SCORE() AS score, * FROM documents WHERE CONTAINS(doc_content, 'Driethanolamyn', FUZZY(0.8, 'option1=value1, option2=value2')) ORDER BY score DESC; Specify the search options as a comma-separated list of key/value pairs.
PUBLIC
439
Example with EXACT search and additional search options

You can also use search options in combination with an exact search. So, for example, you can use search options for term mappings and stopwords for fuzzy search and for exact search. SELECT SCORE() AS score, * FROM documents WHERE CONTAINS(doc_content, 'Driethanolamyn', EXACT('option1=value1, option2=value2')) ORDER BY score DESC;
10.2.4.6 Fuzzy Search - Options for All Column Types

There are search options that are not only valid for a specific column type such as text or string. These options are described in this chapter.
10.2.4.6.1 Option emptyScore
Introduction
Many database tables often contain incomplete data. For example, the first name or the phone number of a customer may be empty, either because the information was not known when the database record was created or because of missing data maintenance. Therefore, the search input may contain more information than the database record that the user is looking for. In this case, the user still expects to get the result. To get the expected behaviour using standard SQL, an application developer writes code as in the following example: SELECT score(), ... FROM ... WHERE ... AND (CONTAINS(firstname, 'Peter', FUZZY(0.8)) OR firstname IS NULL) AND ... It is not possible to specify the score for the 'firstname IS NULL' clause, so the overall score() for records with an empty firstname may get an unexpected score() that probably does not fit into the sort order of other results. In addition, SQL statements get longer and more complex with the additional WHERE clauses. This is why the option 'emptyScore' has been introduced. For symmetry reasons, the search works the other way around, too. So, when searching with an empty column, records that contain a value in the column are also returned. This is important for batch processes, for example, where the order of records processed is not known and results shall be the same, regardless of the order of processing.
440
In the following sections an empty column value is a column value that is either an empty string ('') or a NULL value. We do not distinguish between these two values.
Supported Data Types

The search option 'emptyScore' supports the following SQL data types: VARCHAR NVARCHAR SHORTTEXT TEXT DATE Columns with a FULLTEXT INDEX
Note
Numeric types like INTEGER, DECIMAL, FLOAT, and so on are currently not supported.
Example
DROP TABLE test_emptyscore; CREATE COLUMN TABLE test_emptyscore ( id INTEGER PRIMARY KEY, t TEXT FUZZY SEARCH INDEX ON ); INSERT INSERT INSERT INSERT INTO INTO INTO INTO test_emptyscore test_emptyscore test_emptyscore test_emptyscore VALUES VALUES VALUES VALUES ('1', ('2', ('3', ('4', 'eins'); ''); ' '); NULL); -- empty string -- n blanks -- NULL value
Select 'eins' without emptyScore SELECT SCORE() AS score, * FROM test_emptyscore WHERE CONTAINS(T, 'eins', FUZZY(0.5, 'textSearch=compare')) ORDER BY score DESC, id; SCORE 1.0 Select 'eins' with emptyScore SELECT SCORE() AS score, * FROM test_emptyscore WHERE CONTAINS(T, 'eins', FUZZY(0.5, 'textSearch=compare, emptyScore=0.5')) ORDER BY score DESC, id; ID 1 T eins
PUBLIC
441
SCORE 1.0 0.5 0.5
ID 1 2 4
T eins
<NULL>
Select empty string without emptyScore SELECT SCORE() AS score, * FROM test_emptyscore WHERE CONTAINS(T, '', FUZZY(0.5, 'textSearch=compare')) ORDER BY score DESC, id; SCORE 1.0 ID 2 T
Select empty string with emptyScore SELECT SCORE() AS score, * FROM test_emptyscore WHERE CONTAINS(T, '', FUZZY(0.5, 'textSearch=compare, emptyScore=0.5')) ORDER BY score DESC, id; SCORE 1.0 1.0 0.5 0.5 ID 1 4 1 3 <NULL> eins T
Select empty string with emptyScore and minTextScore SELECT SCORE() AS score, * FROM test_emptyscore WHERE CONTAINS(T, '', FUZZY(0.5, 'textSearch=compare, emptyScore=0.5, mintextscore=0.8')) ORDER BY score DESC, id; SCORE 1.0 1.0 0.5 0.5 ID 2 4 1 3 <NULL> eins T
Note
When searching with an empty value, for example, records that contain a value in the column are returned and will get the score of the parameter emptyScore. The list will not be shortened, even though the parameter minTextScore is set.
442
PUBLIC
Getting Records with Empty Column Values
When the search is called with the emptyScore option as in the following example SELECT score(), ... FROM ... WHERE ... AND CONTAINS(firstname, 'Peter', FUZZY(0.8, 'textSearch=compare, emptyScore=0.9, ...<otherOptions>...)) AND ... the records returned by the search are the same as with the following SQL statement (scores differ of course because of the emptyScore parameter) SELECT score(), ... FROM ... WHERE ... AND ( CONTAINS(firstname, 'Peter', FUZZY(0.8, 'textSearch=compare, ...<otherOptions>...)) OR firstname IS NULL OR firstname = '' ) AND ... For records containing a NULL or an empty string in the firstname column, the value of emptyScore (0.9 in this example) is used as firstname score when calculating the overall score. For records containing a non-empty firstname, the fuzzy score is calculated and used. For columns that do not allow empty strings as values (date types for example) the result of the search is the same as the query SELECT score(), ... FROM ... WHERE ... AND ( CONTAINS(dateofbirth, '2000-01-02', FUZZY(0.8, '...<otherOptions>...)) OR dateofbirth IS NULL ) AND ...
Note
Numeric types like INTEGER, DECIMAL and FLOAT are currently not supported.
Finding Non-Empty Column Values when Searching with an Empty Column Value
When the search is called with an empty string and with option emptyScore as in the following example: SELECT score(), ... FROM ... WHERE ... AND CONTAINS(firstname, '', FUZZY(0.8, 'textSearch=compare, emptyScore=0.9, ...<otherOptions>...)) AND ...
PUBLIC
443
the result of the search is the same as with the following SQL statement (scores differ, of course, because of the emptyScore parameter): SELECT score(), ... FROM ... WHERE ... AND ( firstname IS NULL OR firstname = '' OR firstname LIKE '_%' ) AND ... For records that contain a NULL or an empty string in the firstname column, a score of 1.0 is used, because an empty string is considered a 'perfect' match for a search with an empty string. Records with a non-empty firstname get a firstname score of 0.9, which is the value of the emptyScore parameter in this example. For columns that do not allow empty strings as a value (for example, date types), the result of the search is the same as the query: SELECT score(), ... FROM ... WHERE ... AND ( dateofbirth IS NULL OR dateofbirth IS NOT NULL ) AND ...
10.2.4.7 Fuzzy Search on String Columns

String types support a basic fuzzy string search. The values of a column are compared with the user input using the fault-tolerant fuzzy string comparison. When working with string types, the fuzzy string compare always compares the full strings. When searching with 'SAP' for example, a record like 'SAP Deutschland AG & Co. KG' gets a very low score, because only a very small part of the string is equal (3 of 27 characters match). A fuzzy search on string types is a replacement for non-fault tolerant SQL statements like SELECT ... FROM products WHERE product_name = 'coffe krisp biscuit' ... which would not return any results because of the spelling errors. The following SQL data types are supported: VARCHAR NVARCHAR
It is possible to speed up the fuzzy search by creating additional data structures called 'fuzzy search indexes'. These are used for faster calculation of the fuzzy score. These indexes exist in the memory only, so no additional disk space is needed. To get the best response times possible, you should enable the fuzzy search indexes for all database columns with a high load of fuzzy searches and for all database columns that are used in performance-critical queries. The following search options influence the score calculation: Option spellCheckFactor: Defines the score of terms that get a fuzzy score of 1.0 but are not equal.
444
Option similarCalculationMode: Defines how the score is calculated when comparing terms. Defines options to search with substrings of terms. Option emptyScore: Defines the score of empty column values when searching with non-empty user input (and the other way round).
10.2.4.7.1 Speeding Up the Fuzzy Search with the Fuzzy Search Index
You can speed up the fuzzy search on string types by creating a special data structure called a fuzzy search index. The additional index will increase the total memory footprint of the loaded table. In unfavourable cases the memory footprint of the column can be doubled. CREATE COLUMN TABLE mytable ( id INTEGER PRIMARY KEY, col1 VARCHAR(100) FUZZY SEARCH INDEX ON, col2 NVARCHAR(100) FUZZY SEARCH INDEX ON ); Additional performance improvements are possible when creating database indexes on the columns. CREATE INDEX myindex1 ON mytable(col1); CREATE INDEX myindex2 ON mytable(col2); The state of the fuzzy search index can be changed at a later point in time by using the ALTER TABLE statement. ALTER TABLE mytable ALTER ( col1 VARCHAR(100) FUZZY SEARCH INDEX OFF, col2 NVARCHAR(100) ); The view SYS.TABLE_COLUMNS shows the current state of the fuzzy search index. When working with attribute views, this information is also visible in SYS.VIEW_COLUMNS. SELECT column_name, data_type_name, fuzzy_search_index FROM table_columns WHERE table_name = 'MYTABLE';
10.2.4.7.2 Sub-String Optimized Fuzzy Search on String Columns

String columns (VARCHAR and NVARCHAR) are not suitable for finding small parts of a longer string, for example finding 'test' in 'this is a long test run'. This is more the domain of TEXT fields that have an additional FULLTEXT INDEX. To find a short string in what might be longer values of string columns (VARCHAR and NVARCHAR), a special search mode scm=substringsearch has been established. The substring search can be used as a
PUBLIC
445
workaround if there is no option to perform the search on a TEXT column. The results will be similar but not identical.
Score Calculation
A suitable similarCalculationMode to perform this kind of search is search. It also has the following shortcomings though: Based on the algorithm, it finds longer texts which are not similar in a human sense with a rather good score. This also impairs the sorting of the result set.
To overcome these issues, a new type of similarCalculationMode has been introduced, known as the subStringSearch. The search option scm=substringsearch should return all rows containing the search input. Very long search strings are truncated after 100 characters. A fault tolerance up to 8 typos for long search strings limits the resust list. See also the example at Fuzzy Search - Option similarCalculationMode
Results with similarCalulationMode=search

SELECT SCORE(), STRING FROM TABLE WHERE CONTAINS (STRING, 'test', FUZZY(0.5, 'similarCalculationMode=search')) SCORE() 1.0 0.93 0.91 0.68 0.68 0.62 0.58 STRING test long test this is a long test run this is a long text column this is not a result text long text
Results with similarCalulationMode=subStringSearch

SELECT SCORE(), STRING FROM TABLE WHERE CONTAINS (STRING, 'test', FUZZY(0.7, 'similarCalculationMode=substringsearch')) SCORE() 1.0 STRING test
446
SCORE() 0.97 0.95 0.8 0.77 0.76
STRING long test this is a long test run text long text this is a long text column
As shown in the example, all results containing the search term 'test' are sorted on top, followed by the results containing the term 'text'. The record 'this is not a result' is sorted out as well.
Comparison of subStringSearch on String Columns And Text Search on Text Columns
Hits and Score

The hits from a subStringSearch on string column are determined in a completely different way to the hits from a text search on a text column. The scoring calculation uses a different algorithm too. The results therefore cannot be the same. They are similar however. The following example shows a comparison of a subStringSearch with a very similar text search. Example: DROP TABLE tab; CREATE COLUMN TABLE tab ( id INTEGER primary key, str NVARCHAR(120) fuzzy search index on, txt TEXT fuzzy search index on); INSERT INTO INSERT INTO INSERT INTO INSERT INTO INSERT INTO INSERT INTO INSERT INTO INSERT INTO MERGE DELTA tab VALUES tab VALUES tab VALUES tab VALUES tab VALUES tab VALUES tab VALUES tab VALUES OF tab; (0, (1, (2, (3, (4, (5, (6, (7, 'Albia City', 'Albia City'); 'Albia', 'Albia'); 'Albia City Hall', 'Albia City Hall'); 'City Of Albia', 'City Of Albia'); 'Albion City Park', 'Albion City Park'); 'Albiacityhall', 'Albiacityhall'); 'Albiacity', 'Albiacity'); 'Cityalbia', 'Cityalbia');
SELECT TO_DECIMAL(SCORE(),3,2) score, txt FROM tab WHERE CONTAINS(txt, 'olbia city', FUZZY(0.75, 'textsearch=compare, considernonmatchingtokens=input, composewords=5, decomposewords=5')) ORDER BY SCORE() DESC; SCORE() 0.9 0.9 TXT Albia City Albia City Hall
PUBLIC
447
SCORE() 0.9 0.81 0.77
TXT City Of Albia Albiacity Cityalbia
SELECT TO_DECIMAL(SCORE(),3,2) score, str FROM tab WHERE CONTAINS(str, 'olbia city', FUZZY(0.75, 'similarcalculationmode=substringsearch')) ORDER BY SCORE() DESC; SCORE() 0.89 0.88 0.88 0.82 0.82 0.78 STR Albia City City Of Albia Albia City Hall Albiacity Cityalbia Albiacityhall
SubStringSearch uses a strict AND. Records like "Albia" are therefore not returned, as "City" is missing in the input. As for longer reference entries and additional or missing blanks, it is quite tolerant. Wrong, missing or additional characters result in a moderate deduction. The main difference to a standard string search is that subStringSearch suppresses reference hits that just contain widely spread fragments of the search string which are not considered similar to the input by the human eye.
Response Time
The response time of a subStringSearch depends on various factors. Internally, it starts with a fuzzy search on the string column. The results are then filtered, and a score is calculated. The time consumed is depends significantly on the number of hits that the fuzzy search returns. In general, the subStringSearch using the fuzzy index can take twice as long as the underlying string search. If the subStringSearch runs without fuzzy index, it might be faster than the string search, but consumes more CPU time. Compared to a text search, the subStringSearch is a few times slower or worse. It should therefore not be used for large amounts of data, and only when text columns are not an option.
Memory Consumption
The memory consumption of a subStringSearch is not different to the string search it is based on. It depends of course on whether or not the fuzzy index is used.
448
PUBLIC
10.2.4.7.3 Content-Specific Fuzzy Search on String Columns

Use Case: Fuzzy Search - House Numbers
Score Calculation
The house number comparison aims for a 'simple' solution that is easy to understand, gives good results, and works for most countries. The limitations of the algorithm are: The algorithm focuses on numeric values - either a single number ('8') or a range of numbers ('8 - 12'). House number additions (for example, the 'a' in '8a') are either equal or not equal.
When comparing two strings containing house numbers with each other, the score is calculated in accordance with the rules described below. House number addition. A house number addition in terms of this backlog item is any additional text that is written before or after the numeric value of a house number. House number ranges. When a string contains at least two numbers and there is a dash between the first and second number, this is treated as a house number range. The first number is the lower bound of the range, the last number is the upper bound. Multiple numbers. When multiple numbers are part of a house number string that does not define a house number range, the first number is the house number used for the comparison. All remaining information is used as a house number addition. Whitespace characters. For all rules, whitespace characters are ignored when comparing the house numbers. For the score calculation it does not matter if a house number is given as '8a' or '8 a' or if it is '8-10' or '8 - 10'. Symmetry. In all examples, the score calculation is symmetric. This means that either string 1 or string 2 can be the user input and the other string is stored in the database table.
Rule 1 - House Numbers or House Number Ranges Are Identical

For identical house numbers, a score of 1.0 is returned. Identical house numbers are house number strings that are equal when whitespace characters are ignored. Examples: String 1 5 5a 8-12 9 in the backyard String 2 5 5a 8-12 9 in the backyard Score 1.0 1.0 1.0 1.0
PUBLIC
449
Rule 2 - House Numbers or House Number Ranges Are Very Similar (House Number Additions Are Different)
House numbers or house number ranges are considered very similar when the numerical values are identical but the additional information differs. Examples: String 1 5 5a 5 8-12 8-12 8-12 8 this is a long text -12 7 9 in the backyard 9 String 2 5a 5b Nr. 5 8 - 12a Nr. 8-12 8 - 12/5 8 - 12a below 7 9 in the backyard 9 in the backyard Score 0.9 0.9 0.9 0.9 0,9 0.9 0.9 0.9 0.9 0.9
Rule 3 - House Numbers or House Number Ranges Are Less Similar

House numbers and house number ranges are considered less similar in the following cases: 1. 2. A house number is compared to a house number range and the numerical value of the house number equals the lower or upper bound of the range. Two house number ranges are compared and the numerical values of either the lower or upper bounds are equal. String 2 8-12 8-12 8-12 8-12 8-12 8-12 Score 0.8 0.8 0.8 0.8 0.8 0.8
String 1 8 12a 8-10 8-10 10-12a 8 in the backyard
450
PUBLIC
Rule 4 - Overlapping House Number Ranges

House numbers and house number ranges overlap in the following cases: 1. 2. A house number is compared to a house number range and the numerical value of the house number lies within the range. Two house number ranges are compared and the ranges overlap.
Examples: String 1 10 10a 9 8-12 8-12a String 2 8-12 8-12 8-12 10-14 10b-14 Score 0.7 0.7 0.7 0.7 0.7
Last Rule - House Numbers Are Not Equal

Examples: String 1 5 8a 6 8-10 String 2 6 9a 8-12 12-14 Score 0.0 0.0 0.0 0.0
House Number Columns and Other String Search Options

The following search options available for string column types are not valid for house number columns: SpellCheckFactor: When comparing house numbers, the search option 'spellCheckFactor' is ignored. So for house numbers, the results are always the same as with 'spellCheckFactor=1.0'. SimilarCalculationMode: When comparing house numbers, the search option 'similarCalculationMode' is ignored and has no effect on the search result.
Both options are ignored. No error is returned when any of the options is given.
PUBLIC
451
SQL Syntax
To enable the search for house numbers on an (N)VARCHAR column, the FUZZY SEARCH MODE clause is used in a CREATE TABLE statement. CREATE COLUMN TABLE tab ( id INTEGER PRIMARY KEY, col1 NVARCHAR(20) FUZZY SEARCH MODE 'housenumber' ); To enable or disable the house number search mode at a later point in time, use the ALTER TABLE statement. The fuzzy search mode is not changed if the FUZZY SEARCH MODE clause is omitted. -- enable housenumber search ALTER TABLE tab ALTER ( col1 VARCHAR(20) FUZZY SEARCH MODE 'housenumber' ); -- disable housenumber search ALTER TABLE tab ALTER ( col1 VARCHAR(20) FUZZY SEARCH MODE NULL ); -- do not change the status of the search mode ALTER TABLE tab ALTER ( col1 VARCHAR(20) ); You can query the state of the fuzzy search mode using the system view TABLE_COLUMNS. SELECT column_name, data_type_name, fuzzy_search_mode FROM table_columns WHERE table_name = 'TAB';
Note
You cannot use a fuzzy search index in combination with the house number search mode.
Example
The following example creates a table that contains only a single house number column and executes some searches on this column. CREATE COLUMN TABLE housenumbers ( housenumber NVARCHAR(50) FUZZY SEARCH MODE 'housenumber' ); INSERT INTO housenumbers VALUES ('5'); INSERT INTO housenumbers VALUES ('5a'); INSERT INTO housenumbers VALUES ('5 a');
452
INSERT INTO housenumbers VALUES ('Nr. 5'); INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO housenumbers housenumbers housenumbers housenumbers housenumbers housenumbers housenumbers housenumbers housenumbers housenumbers housenumbers VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES ('8-12'); ('8 - 12'); ('8 - 12a'); ('Nr. 8-12'); ('8 - 12/5'); ('8'); ('12a'); ('8-10'); ('10-12a'); ('10a'); ('10-14');
INSERT INTO housenumbers VALUES ('9'); SELECT TO_DECIMAL(SCORE(),3,2), * FROM housenumbers WHERE CONTAINS(housenumber, '5', FUZZY(0.8)) ORDER BY TO_DECIMAL(SCORE(),3,2) DESC; SELECT TO_DECIMAL(SCORE(),3,2), * FROM housenumbers WHERE CONTAINS(housenumber, 'Nr. 5', FUZZY(0.8)) ORDER BY TO_DECIMAL(SCORE(),3,2) DESC; SELECT TO_DECIMAL(SCORE(),3,2), * FROM housenumbers WHERE CONTAINS(housenumber, '8a-12', FUZZY(0.8)) ORDER BY TO_DECIMAL(SCORE(),3,2) DESC; SELECT TO_DECIMAL(SCORE(),3,2), * FROM housenumbers WHERE CONTAINS(housenumber, '10-12', FUZZY(0.8)) ORDER BY TO_DECIMAL(SCORE(),3,2) DESC; SELECT TO_DECIMAL(SCORE(),3,2), * FROM housenumbers WHERE CONTAINS(housenumber, '9 in the BACKYARD', FUZZY(0.8)) ORDER BY TO_DECIMAL(SCORE(),3,2) DESC;
Use Case: Fuzzy Search - Postcodes
Postcodes in almost all countries are ordered by region. This means that if the leading characters of the postcodes of two different addresses are the same, the addresses are near to each other. In Germany, for example, addresses within large cities share the first or even the first two digits of their postcode. The only exception known to the development team is Cambodia, where postcodes are not ordered by region. When doing a fuzzy search on addresses, it makes sense to return a higher score for postcodes that are 'near' to a given user input than for postcodes that are 'far away' from the user input. It makes sense to give a higher weight to the leading characters and a lower weight to the trailing characters of the postcode. Valid addresses may contain a country code in front of the postcode (for example, 'D-12345' or 'DE-12345' for a German address). This is also supported by the fuzzy postcode search.
PUBLIC
453
Score Calculation
Before the fuzzy score is calculated, the postcode strings are standardized. 1. Country codes are separated from the postcode strings. Country codes in this case consist of one to three letters (a-z only, no numbers) at the beginning of the postcode, followed by a minus sign. Longer words are not considered a country code because postal standards do not allow country names in front of the postcode. Country codes are standardized to enable a comparison of different codes for the same country, for example, 'D-', 'DE-' and 'DEU-' for German postcodes. All unknown/invalid country codes are standardized to one special 'dummy' country code. Spaces and dashes are removed from the remaining postcode. All letters are standardized to uppercase. Country Code Remaining Postcode 71691 71691 D DE 71691 71691 D71691 GERMANY71691 GB A1H2ZU A1H2ZU GB XX XX AI A1H2ZU 12345 12345 2640
2.
3. 4.
User Input 71691 716 91 D-71691 DE-71 691 D 71691 Germany-71691 GB-A1H 2ZU A1H-2ZU gb-A1h 2zu XY-12345 zz-12345 AI-2640
The last example is the only known example where the country code is part of the postcode (AI = Anguilla). The algorithm works here as well, since the country code is also compared. The two examples directly above the AI example show invalid country codes. Both are standardized to the same non-existent 'dummy' country code.
Postcode Comparison
The standardized postcodes are compared using a variation of the fuzzy string comparison. This variation gives a higher weight to the first two characters of the postcode. Country codes are given the same weight as a single character at the end of the postcode. Only postcodes with the same country code can get a score of 1.0. If one country code is given and the second country code is empty, the score of the postcode comparison is less than 1.0. If both country codes are given and are different, the score of the postcode comparison is also less than 1.0.
454
Parameter similarCalculationMode
The search option 'similarCalculationMode' with options 'search' and 'symmetricsearch' is available for postcode columns. When using the search option 'similarCalculationMode', a postcode search with a postcode prefix will find all addresses in a given area. A search with '71' returns all postcodes beginning with '71'. A search with '1234' returns all postcodes starting with a sequence similar to '1234' and, with a lower score, all postcodes that contain a '1234'.
Parameter spellCheckFactor
Two postcodes may be considered identical by the fuzzy string comparison, but may still be different. In this case, the value of the parameter 'spellCheckFactor' is applied and the score is multiplied by the spellCheckFactor. Examples of non-equal postcodes that get a score of 1.0 are: '123456' and '12 34 56' '7070717' and '7071707'
The default value of the search option spellCheckFactor is 0.9. To disable this feature, set 'spellCheckFactor=1.0'.
Example
The following example uses a spellCheckFactor of 1.0, which is not the default value. Postcode 1 71691 71691 71691 71691 71691 71691 D-71691 71691 Postcode 2 71691 71 691 81691 72691 71692 D-71691 A-71691 D-71692 Score 1.0 1.0 0.51 0.7 0.96 0.96 0.96 0.92 Highest weight on the first digit High weight on the second digit Lower weight on all other digits Country code missing in one column Country codes are different Remarks
PUBLIC
455
Postcode 1 D-71691 GB-A1H 2ZU XX-12345 D-12345
Postcode 2 A-71692 Gb-a1h2zu YY-12345 YY-12345
Score 0.92 1.0 1.0 0.96
Remarks
Invalid country codes are 'equal' Valid and invalid country code
SQL Syntax
(N)VARCHAR columns have to be defined as postcode columns to enable the fuzzy postcode search. You do this using the FUZZY SEARCH MODE clause. You can also improve the performance of the postcode search by activating a fuzzy search index and by creating a database index on the postcode column. CREATE COLUMN TABLE tab ( id INTEGER postcode NVARCHAR(20) );
PRIMARY KEY, FUZZY SEARCH INDEX ON FUZZY SEARCH MODE 'postcode'
CREATE INDEX myindex1 ON tab(postcode); You can enable or disable the postcode search at a later point in time with the ALTER TABLE statement. To disable the postcode search, do not specify the FUZZY SEARCH MODE for the postcode column. -- enable postcode search ALTER TABLE tab ALTER ( postcode NVARCHAR(100) );
FUZZY SEARCH MODE 'postcode'
-- disable postcode search ALTER TABLE tab ALTER ( postcode NVARCHAR(100) FUZZY SEARCH MODE NULL ); -- do not change the status of the search mode ALTER TABLE tab ALTER ( postcode NVARCHAR(100) ); You can query the status of the fuzzy search index and the fuzzy search mode from the system view TABLE_COLUMNS. SELECT column_name, data_type_name, fuzzy_search_index, fuzzy_search_mode FROM table_columns WHERE table_name = 'TAB';
456
PUBLIC
Example
CREATE COLUMN TABLE postcodes ( postcode NVARCHAR(50) FUZZY SEARCH INDEX ON FUZZY SEARCH MODE 'postcode' ); INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes postcodes VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES ('71691'); ('81691'); ('72691'); ('71692'); ('716 91'); ('A1H 2ZU'); ('A1H2ZU'); ('D-71691'); ('D-71692'); ('A-71691'); ('A-71692'); ('DE-71 691'); ('D 71691'); ('GB-A1H 2ZU'); ('XX-12345'); ('D-12345'); ('71234');
SELECT TO_DECIMAL(SCORE(),3,2), * FROM postcodes WHERE CONTAINS(postcode, '71691', FUZZY(0.5, 'spellCheckFactor=1.0')) ORDER BY SCORE() DESC; SELECT TO_DECIMAL(SCORE(),3,2), * FROM postcodes WHERE CONTAINS(postcode, 'D-71691', FUZZY(0.5, 'spellCheckFactor=1.0')) ORDER BY SCORE() DESC; SELECT TO_DECIMAL(SCORE(),3,2), * FROM postcodes WHERE CONTAINS(postcode, 'Gb-a1h2zu', FUZZY(0.5, 'spellCheckFactor=1.0')) ORDER BY SCORE() DESC; SELECT TO_DECIMAL(SCORE(),3,2), * FROM postcodes WHERE CONTAINS(postcode, 'YY-12345', FUZZY(0.5, 'spellCheckFactor=1.0')) ORDER BY SCORE() DESC; SELECT TO_DECIMAL(SCORE(),3,2), *FROM postcodes WHERE CONTAINS(postcode, '71', FUZZY(0.5, 'spellCheckFactor=1.0')) ORDER BY SCORE() DESC; SELECT TO_DECIMAL(SCORE(),3,2), * FROM postcodes WHERE CONTAINS(postcode, '1234', FUZZY(0.5, 'spellCheckFactor=1.0')) ORDER BY SCORE() DESC;
PUBLIC
457
10.2.4.7.4 Speeding Up the Fuzzy Search on String Columns
Context
Fuzzy search on string types can be sped up by creating a special data structure called a fuzzy search index. The additional index will increase the total memory footprint of the loaded table. In unfavourable cases the memory footprint of the column can be doubled. CREATE COLUMN TABLE mytable ( id INTEGER PRIMARY KEY, col1 VARCHAR(100) FUZZY SEARCH INDEX ON, col2 NVARCHAR(100) FUZZY SEARCH INDEX ON ); Additional performance improvements are possible when creating database indexes on the columns. CREATE INDEX myindex1 ON mytable(col1); CREATE INDEX myindex2 ON mytable(col2); The state of the fuzzy search index can be changed at a later point in time by using the ALTER TABLE statement. ALTER TABLE mytable ALTER ( col1 VARCHAR(100) FUZZY SEARCH INDEX OFF, col2 NVARCHAR(100) ); The view SYS.TABLE_COLUMNS shows the current state of the fuzzy search index. When working with attribute views, this information is also visible in SYS.VIEW_COLUMNS. SELECT column_name, data_type_name, fuzzy_search_index FROM table_columns WHERE table_name = 'MYTABLE';
10.2.4.8 Fuzzy Search on Text Columns

Text types support a more sophisticated kind of fuzzy search. Texts are tokenized (split into terms), and the fuzzy comparison is performed term by term. When searching with 'SAP' for example, a record like 'SAP Deutschland AG & Co. KG' gets a high score, because the term 'SAP' exists in both texts. A record like 'SAPPHIRE NOW Orlando' gets a lower score, because 'SAP' is just a part of the longer term 'SAPPHIRE' (3 of 8 characters match). Fuzzy search on text columns replaces non-fault tolerant statements like SELECT ... FROM documents WHERE doc_content LIKE '% Driethanolamyn %' ... The following SQL data types are supported: TEXT
458
SHORTTEXT fulltext index
A fulltext index is an additional index structure that can be defined for non-text columns to add text search features. Supported column types include NCLOB and NVARCHAR. It is possible to speed up the fuzzy search by creating data structures called 'fuzzy search indexes', which are used for faster calculation of the fuzzy score. These indexes exist in the memory only, so no additional disk space is needed. To get the best response times possible, you should enable the fuzzy search indexes for all database columns with a high load of fuzzy searches and for all database columns that are used in performance-critical queries.
Fuzzy Search on SQL Type TEXT

A call to contains that references a TEXT column is automatically processed as a text search. In this case, the mode textsearch=compare and all fuzzy search options are allowed: CREATE COLUMN TABLE mytable ( col1 TEXT ); SELECT score() AS score, * FROM mytable WHERE contains(col1, 'a b', fuzzy(0.8, 'textsearch=compare'));
Fuzzy Search on SQL Type SHORTTEXT

When a SHORTTEXT column is created, a column of column store type cs_string and a second hidden text column are created. A call to contains that references the SHORTTEXT column is automatically redirected by the freestyler to the additional hidden TEXT column. In this case, the mode textsearch=compare and all fuzzy search options are allowed: CREATE COLUMN TABLE mytable ( col1 SHORTTEXT(200) ); SELECT score() AS score, * FROM mytable WHERE contains(col1, 'a b', fuzzy(0.8, 'textsearch=compare'));
Fuzzy Search on a FULLTEXT INDEX

When a full text index is created on a column that is not of type TEXT (e.g. NVARCHAR, NCLOB, ...) a hidden text column is added to the table. A call to contains that references the non-TEXT column is automatically redirected
PUBLIC
459
by the freestyler to the additional text column. In this case, the mode textsearch=compare and all fuzzy search options are allowed: CREATE COLUMN TABLE mytable ( col1 NVARCHAR(2000) ); CREATE FULLTEXT INDEX myindex ON mytable(col1); SELECT score() AS score, * FROM mytable WHERE contains(col1, 'a b', fuzzy(0.8, 'textsearch=compare'));
Merge Delta for Better Performance

When inserting or loading a large number of rows into a table that has a TEXT or SHORTTEXT column or uses a FULLTEXT INDEX, it is important to merge the delta part of the table in order to ensure satisfactory search performance. A delta merge can be started manually using the following SQL statement: MERGE DELTA OF mytable; Alternatively, a delta merge can be triggered automatically by the mergedog process.
10.2.4.8.1
Multi-Token Search on Text Columns
When using more than one token in a query, the default content type is AND (for example, ... WHERE CONTAINS (mycolumn, 'software firm', FUZZY(0.5)) ... will return entries that contain a token similar to 'software' and a token similar to 'firm'). Alternatively, you can use OR by adding the key word between the tokens (for example, ... WHERE CONTAINS (mycolumn, 'apple OR 'banana', FUZZY(0.5)) ... will return entries that contain a token similar to 'apple' and entries that contain a token similar to 'banana'). PHRASE is similar to AND, but restricts hits to ones that contain the tokens as a phrase, in other words in the same order and with nothing between them. A PHRASE is indicated by adding double quotes around the tokens, within the single quotes (for example, ... WHERE CONTAINS (mycolumn, '"day dream"', FUZZY(0.5)) ... will not return an entry containing 'I dream of a day'). The content type AND that is used for full-text searches (default behavior: textSearch=fulltext) is implemented as a logical AND in order to achieve better performance. A search for 'Miller & Miller AG' for example, with content type AND, matches 'Miller AG'. For duplicate detection and for comparing company names, product names and so on, textSearch=compare should be used. This produces better search results due to the strict AND comparison that is used. In other words, when searching for 'Miller & Miller' with content type AND, only records that contain the term 'Miller' at least twice will be returned. A strict AND assigns terms from the user input to terms in the database entry just once (and vice versa). For more information, see Partially Matching with Parameter andThreshold [page 466].
460
PUBLIC
Parameters Influencing the Score

Name of Option Range Default 0 max 1.0 Applies to Types TEXT TEXT TEXT
bestMatchingTokenWei 0.0..1.0 ght considerNonMatchingT max, min, all, input, table okens excessTokenWeight 0.0..1.0
Formula for score calculation: score = bestMatchingTokenWeight x max(tokenScores) + (1-bestMatchingTokenWeight) x ((tokenScore)/ (matchedTokenCount + excessTokenCount x excessTokenWeight)) Recommendations for specific search content types If you are using an "OR" search (searching for "this or that"), you should set considerNonMatchingTokens to table to get a useful score assessment.
Parameters Influencing the Result Set

Option andSymmetric andThreshold Range on,off,true,false 0.0..1.0 Default off 1.0 Applies to Types TEXT TEXT
For examples, see Symmetric Search with Parameter andSymmetric [page 467] and Partially Matching with Parameter andThreshold [page 466] . Related Information Option bestMatchingTokenWeight [page 461] Option considerNonMatchingTokens [page 463] Option excessTokenWeight [page 465]
Option bestMatchingTokenWeight
Missing tokens in the search input or tokens with a low score can lower the total score for the field more than desired. The parameter bestMatchingTokenWeight allows you to get a better score in such cases. This is done by putting more emphasis on the score of the token that matches best. With this parameter, you can shift the total score value for a field between the root mean square of score values and the best token score value. The lower boundary (root mean square of score values) is reached by setting bestMatchingTokenWeight to 0, which is the default value. The upper boundary is reached by setting bestMatchingTokenWeight to 1.
PUBLIC
461
Examples
DROP TABLE test_table; CREATE COLUMN TABLE test_table ( id INTEGER PRIMARY KEY, t SHORTTEXT(200) FUZZY SEARCH INDEX ON ); INSERT INSERT INSERT INSERT INSERT INTO INTO INTO INTO INTO test_table test_table test_table test_table test_table VALUES VALUES VALUES VALUES VALUES ('1', ('2', ('3', ('4', ('5', 'one'); 'one two'); 'one two three'); 'one two three four'); 'one two three four five');
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'won zwo tree', FUZZY(0.5, 'textSearch=compare')) ORDER BY score DESC, id; SCORE 0.68 0.59 0.53 ID 3 4 5 T one two three one two three four one two three four five
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'won zwo tree', FUZZY(0.5,'textSearch=compare, bestMatchingTokenWeight=0.1')) ORDER BY score DESC, id SCORE 0.7 0.61 0.56 ID 3 4 5 T one two three one two three four one two three four five
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'won zwo tree', FUZZY(0.5,'textSearch=compare, bestMatchingTokenWeight=1.0')) ORDER BY score DESC, id SCORE 0.81 0.81 0.81 ID 3 4 5 T one two three one two three four one two three four five
462
Option considerNonMatchingTokens
To get the score for the whole field content, we have to compute the mean of the token scores. There are cases in which not every token in the search term has a matching token in the table content and vice versa. These tokens are called non-matching tokens (or excess tokens). You can use the parameter considerNonMatchingTokens to decide how these non-matching tokens affect the calculation of the score for the whole field content. This is done by specifying what is considered to be the number of tokens relevant for the score calculation (tokenCount). The number of matching tokens is subtracted from this number to get the number of nonmatching tokens (or excess tokens). tokenCount is determined in accordance with the parameter considerNonMatchingTokens as follows: input: use search term token count table: use column value token count all : use sum of search term and column value token count divided by 2 min : use smaller value of token counts from search term and column value max : use larger value of token counts from search term and column value (default)
Examples
DROP TABLE test_table; CREATE COLUMN TABLE test_table ( id INTEGER PRIMARY KEY, t SHORTTEXT(200) FUZZY SEARCH INDEX ON ); INSERT INSERT INSERT INSERT INSERT INTO INTO INTO INTO INTO test_table test_table test_table test_table test_table VALUES VALUES VALUES VALUES VALUES ('1', ('2', ('3', ('4', ('5', 'one'); 'one two'); 'one two three'); 'one two three four'); 'one two three four five');
considerNonMatchingTokens = input SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'won zwo tree', FUZZY(0.5,'textSearch=compare, considerNonMatchingTokens=input')) ORDER BY score DESC, id SCORE 0.68 0.68 0.68 ID 3 4 5 T one two three one two three four one two three four five
PUBLIC
463
considerNonMatchingTokens = table SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'won zwo tree', FUZZY(0.5,'textSearch=compare, considerNonMatchingTokens=table')) ORDER BY score DESC, id SCORE 0.68 0.59 0.53 considerNonMatchingTokens = all SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'won zwo tree', FUZZY(0.5,'textSearch=compare, considerNonMatchingTokens=all')) ORDER BY score DESC, id SCORE 0.68 0.61 0.59 considerNonMatchingTokens = min SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'won zwo tree', FUZZY(0.5,'textSearch=compare, considerNonMatchingTokens=min')) ORDER BY score DESC, id SCORE 0.68 0.68 0.68 considerNonMatchingTokens = max SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'won zwo tree', FUZZY(0.5,'textSearch=compare, considerNonMatchingTokens=max')) ORDER BY score DESC, id SCORE 0.68 0.59 0.53 ID 3 4 5 T one two three one two three four one two three four five ID 3 4 5 T one two three one two three four one two three four five ID 3 4 5 T one two three one two three four one two three four five ID 3 4 5 T one two three one two three four one two three four five
464
Option excessTokenWeight
The parameter excessTokenWeight defines the weight of excess (that is, unassigned) tokens. It is set to 1.0 by default. Excess tokens are tokens that do not have a counterpart token on either the input side or the request side. For example, when searching for "Art Garfunkel", the database entry "Art Garfunkel and Paul Simon" has the excess tokens "and", "Paul", "Simon". This parameter enables a better sorting by score when the lengths (that is, the number of tokens) of the request entry and the reference entry are different.
Examples
DROP TABLE test_table; CREATE COLUMN TABLE test_table ( id INTEGER PRIMARY KEY, t TEXT FUZZY SEARCH INDEX ON ); INSERT INSERT INSERT INSERT INTO INTO INTO INTO test_table test_table test_table test_table VALUES VALUES VALUES VALUES (1,'Art Garfunkel'); (2,'Art Garfunkel and Paul Simon'); (3,'A Heart in New York (Art Garfunkel solo hit)'); (4,'Tra Funkelrag');
-- select 1 SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'Art Garfunkel', FUZZY(0.5,'textSearch=compare,excessTokenWeight=1.0')) ORDER BY score DESC, id; -- select 2 SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table WHERE CONTAINS(t, 'Art Garfunkel', FUZZY(0.5,'textSearch=compare,excessTokenWeight=0.1')) ORDER BY score DESC, id; Result for select 1 SCORE 1.0 0.74 0.63 0.47 ID 1 4 2 3 T Art Garfunkel Tra Funkelrag Art Garfunkel and Paul Simon A Heart in New York (Art Garfunkel solo hit)
Result for select 2
PUBLIC
465
SCORE 1.0 0.93 0.86 0.74
ID 1 2 3 4
T Art Garfunkel Art Garfunkel and Paul Simon A Heart in New York (Art Garfunkel solo hit) Tra Funkelrag
10.2.4.8.2 Multi-Token Search with Soft AND

Partially Matching with Parameter andThreshold
It is possible to specify a 'partial AND' that requires a subset of request tokens only to match the reference tokens. You will then get better results when comparing data like company names. The 'andThreshold' parameter defines the percentage of tokens that have to match when comparing the user input with a row stored in a TEXT column. In other words, the ratio between the number of matching tokens and the number of input tokens has to be greater than or equal to the given andThreshold. Option Name andThreshold Range 0.0..1.0 Default 1.0 Applies to Types TEXT Description Determines the percentage of tokens that need to match
andThreshold = 1.0 -> all tokens have to match, 'strict AND' 0.0 < andThreshold < 1.0 -> some of the tokens have to match, 'soft AND' andThreshold = 0.0 -> at least one token has to match, 'OR' Summary The andThreshold parameter is available as a searchOption. Allowed values are between 0.0 and 1.0. An SQL error is returned for values outside this range. The parameter works on TEXT columns only and is ignored for all other SQL types. The parameter is used with content type AND only and is ignored for all other content types. The parameter influences performance.
Example
DROP TABLE test_soft_and; CREATE COLUMN TABLE test_soft_and ( id INTEGER PRIMARY KEY,
466
PUBLIC
t );
SHORTTEXT(200) INTO INTO INTO INTO INTO
FUZZY SEARCH INDEX ON VALUES VALUES VALUES VALUES VALUES ('1','eins'); ('2','eins zwei'); ('3','eins zwei drei'); ('4','eins zwei drei vier'); ('5','eins zwei drei vier funf');
INSERT INSERT INSERT INSERT INSERT
test_soft_and test_soft_and test_soft_and test_soft_and test_soft_and
Search with andThreshold SELECT SCORE() AS score, * FROM test_soft_and WHERE CONTAINS(T, 'eins XXX drei vier', FUZZY(0.5,'andThreshold=0.75,bestMatchingTokenWeight=0.5,textSearch=compare')) ORDER BY score DESC, id; SCORE 0.933012723922729 0.887298345565796 ID 4 5 T eins zwei drei vier eins zwei drei vier funf
Symmetric Search with Parameter andSymmetric
In addition to the parameter andThreshold, it is possible to specify a 'symmetric AND' that also returns a record when all tokens of a database entry are part of the user input. The parameter 'andSymmetric' was added to the fuzzy search and activates the symmetric AND comparison when comparing the user input with a row stored in a TEXT column. Option Name andSymmetric Range on,off,true,false Default off Applies to Types TEXT Short Description Activates a symmetric AND content search
Example When using content type AND, a search with 'SAP Deutschland AG' returns 'SAP Deutschland AG & Co KG' but not 'SAP Deutschland' or 'SAP Walldorf'. When using the symmetric and, the search with 'SAP Deutschland AG' returns 'SAP Deutschland AG & Co KG' and 'SAP Deutschland', but not 'SAP Walldorf'. Summary The parameter andSymmetric is available as a searchOption. Allowed values are [on,true] and [off, false]. An SQL error is returned for other values. The parameter works on TEXT columns only and is ignored for all other SQL types. The parameter is used with content type AND only and is ignored for all other content types. The parameter works in combination with andThreshold to activate a symmetric 'soft AND'. The parameter influence the performance.
PUBLIC
467
Example
DROP TABLE test_soft_and; CREATE COLUMN TABLE test_soft_and ( id INTEGER PRIMARY KEY, t SHORTTEXT(200) FUZZY SEARCH INDEX ON ); INSERT INSERT INSERT INSERT INSERT INTO INTO INTO INTO INTO test_soft_and test_soft_and test_soft_and test_soft_and test_soft_and VALUES VALUES VALUES VALUES VALUES ('1','one'); ('2','one two'); ('3','one two three'); ('4','one two three four'); ('5','one two three four five');
Search with andSymmetric=off SELECT SCORE() AS score, * FROM test_soft_and WHERE CONTAINS(T, 'one two three', FUZZY(0.5, 'andSymmetric=off,bestMatchingTokenWeight=0.5,textSearch=compare')) ORDER BY score DESC, id; SCORE 1 0.933012723922729 0.887298345565796 Search with andSymmetric=on SELECT SCORE() AS score, * FROM test_soft_and WHERE CONTAINS(T, 'one two three', FUZZY(0.5,'andSymmetric=on,bestMatchingTokenWeight=0.5,textSearch=compare')) ORDER BY score DESC, id; SCORE 1 0.933012723922729 0.90824830532074 0.887298345565796 0.788675129413605 ID 3 4 2 5 1 T one two three one two three four one two one two three four five one ID 3 4 5 T one two three one two three four one two three four five
10.2.4.8.3 Option abbreviationSimilarity

The abbreviation similarity option allows you to search for and with initial characters. You can thus find abbreviations when searching with long strings or find long strings when searching with initial characters.
468
Option Name
Range
Default 0.0
Applies to Types TEXT
Description Defines the similarity that is returned for a matching initial character.
abbreviationSimilarit 0.0..1.0 y
Note
abbreviationSimilarity = 0.0 disables the abbreviation search. The abbreviationSimilarity option works for TEXT fields only. It is available for all term actions available in SQL, like EXACT, SIMILAR, LINGUISTIC. It accepts values between 0.0 and 1.0 . If the given value for abbreviationSimilarity is out of this range, the system returns a SQL error. Search for inital characters: "Peter" finds "P." and "P" "P." always finds "P" with similarity 1.0 "Hans-Peter" finds "Hans P", "H. Peter" and "H.-P." Search with initial characters: "P." and "P" find "Peter" "P." always finds "P" with similarity 1. "Hans P" and "H P" find "Hans-Peter"
Example
The abbreviationSimilarity option is used to search for and find a word using its first character and vice versa with a given score. With abbreviationSimilarity = 0.9, a SELECT retrieves word with SCORE = 0.9 if you search with w (and vice versa). CREATE COLUMN TABLE abbrev ( id INTEGER PRIMARY KEY, name SHORTTEXT(200) FUZZY SEARCH INDEX ON ); INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INSERT INTO INTO INTO INTO INTO INTO INTO INTO INTO INTO abbrev abbrev abbrev abbrev abbrev abbrev abbrev abbrev abbrev abbrev VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES VALUES ('1','Peter'); ('2','Hans'); ('3','H.'); ('4','P.'); ('5','Hans-Peter'); ('6','H.-P.'); ('7','HP'); ('8','G Gerd'); ('9','G'); ('10','Gerd');
Search one token with abbreviationSimilarity SELECT SCORE() AS score, id, name FROM abbrev WHERE CONTAINS(name, 'HP', FUZZY(0.5,
PUBLIC
469
'abbreviationSimilarity=0.80,textSearch=compare')) ORDER BY score DESC, id; SCORE 1 0.800000011920929 0.565685451030731 ID 7 3 6 NAME HP H. H.-P.
Search two tokens with abbreviationSimilarity SELECT SCORE() AS score, id, name FROM abbrev WHERE CONTAINS(name, 'Hans Peter',FUZZY(0.5, 'abbreviationSimilarity=0.80,textSearch=compare')) ORDER BY score DESC, id; SCORE 1 0.800000011920929 ID 5 6 NAME Hans-Peter H.-P.
Search two tokens with abbreviationSimilarity SELECT SCORE() AS score, id, name FROM abbrev WHERE CONTAINS(name, 'Hans Peter',FUZZY(0.5, 'abbreviationSimilarity=0.80,textSearch=compare')) ORDER BY score DESC, id; SCORE 0.905538558959961 ID 8 NAME G Gerd
10.2.4.8.4 Option minTextScore

The minTextScore option allows you to set the score a text field has to reach to be a match. A text field can contain more than one token. Each token is evaluated against the fuzzySimilarity parameter which defines the minimum score a single token has to reach. The overall score of a text field differs from the fuzzySimilarity because the overall Text score is computed from the fuzzySimilarity of all tokens and parameters found, like bestMatchingTokenWeight, considerNonMatchingTokens and term mapping weights. minTextScore defines the minimum score the whole content of a text field has to reach. Option Name minTextScore Range 0.0..1.0 Default 0.0 Applies to Types TEXT Description Minimum score that all records in the result have to reach.
A minTextScore value of 0.0 means that all records that match the conditions defined by fuzzySimilarity and the search options are returned. The result list will not be cut.
470
Note
If you use a fuzzySimilarity of 0.0, the minTextScore parameter becomes redundant. minTextScore does not work with a freestyle or fulltext search. When using minTextScore in combination with the emptyScore parameter, rows found because of the emptyScore parameter are returned even if emptyScore is less than minTextScore. See the code example for emptyScore.
DROP TABLE tab_mintextscore; CREATE COLUMN TABLE tab_mintextscore ( id INTEGER PRIMARY KEY, t TEXT FAST PREPROCESS ON FUZZY SEARCH INDEX ON ); INSERT INTO tab_mintextscore VALUES ('1','Bert'); INSERT INTO tab_mintextscore VALUES ('2','Berta'); INSERT INTO tab_mintextscore VALUES ('3','Bart'); Search on a text column SELECT SCORE() AS score, id, t FROM tab_mintextscore WHERE CONTAINS(t, 'Ernie OR Bert', FUZZY(0.100, 'textSearch=compare, bestMatchingTokenWeight=0,minTextScore=0.70')) ORDER BY score DESC, id; SCORE 0.7 0.65 0.52 ID 1 1 1 T Bert Berta Bart Description << rank value of 0.7 is reached, this is a match << minTextScore not reached - cut off << minTextScore not reached - cut off
10.2.4.8.5 Option textSearch

The textSearch option is used to select the search algorithm for TEXT columns: textSearch=fulltext (default value): A full-text search is performed on a TEXT column. IDF calculation or specialOrRanking (depending on search flags) is used. This is the 'old' NewDB behavior. textSearch=compare: A search similar to a Fuzzy Double search is performed. Additional search options are enabled. The value of the textSearch search option defines which other search options are allowed for a search.
PUBLIC
471
Rank calculation
When 'fulltext' is specified, the search is performed using IDF or specialOrRanking (depending on the search flags). The fuzzy score is not calculated. When 'compare' is specified, the fuzzy score is calculated using bestMatchingTokenWeight and considerNonMatchingTokens. The user does not have to set these options. In this case, the default values are used.
Example
SELECT SCORE() AS score, * FROM test_soft_and WHERE CONTAINS(T, 'eins', FUZZY(0.5, 'textSearch=compare')) ORDER BY score DESC, id; Select with 'Fuzzy Score' (textSearch=compare) SELECT SCORE() AS score, * FROM test_soft_and WHERE CONTAINS(T, 'eins', FUZZY(0.5, 'textSearch=compare')) ORDER BY score DESC, id; SCORE 1.0 0.7071067690849304 0.5773502588272095 ID 1 2 3 T eins eins zwei eins zwei drei
Select with 'IDF Score' (textSearch=fulltext) SELECT SCORE() AS score, * FROM test_soft_and WHERE CONTAINS(T, 'eins', FUZZY(0.5, 'textSearch=fulltext')) ORDER BY score DESC, id; SCORE 0.888888955116272 0.6666666865348816 0.5333333611488342 ID 1 2 3 T eins eins zwei eins zwei drei
10.2.4.8.6 Stopwords
Usage Stopwords are terms that are less significant for a search and are therefore not used to generate the result set. In other words, the search is carried out as though the stopwords did not exist (either in the user input or in the database column).
472
Stopwords do influence the score that is calculated however. A record with stopwords identical to the user input gets a higher score than a record with differing or missing stopwords. Stopwords can be defined either as single terms or as stopword phrases consisting of multiple terms. Stopword phrases are only applied when all terms of the stopword appear in exactly the given order. Use case example: When searching for company names, the legal form (Ltd, SA, AG, and so on) is less significant and less selective than the other parts of the name. Stopwords are stored in a column-store table with the following format: CREATE COLUMN TABLE mystopwords ( stopword_id VARCHAR(32) PRIMARY KEY, list_id VARCHAR(32) NOT NULL, language_code CHAR(2), term NVARCHAR(200) NOT NULL ); Stopwords are language-dependent. It is possible to define the language that a stopword is valid for. You can also define stopwords for all languages by not setting a language. As with term mappings, stopwords can be grouped together in multiple groups. Groups of stopwords are identified by the value of the list_id column that is part of the stopword table. INSERT INTO mystopwords INSERT INTO mystopwords INSERT INTO mystopwords beschrnkter Haftung'); INSERT INTO mystopwords INSERT INTO mystopwords VALUES (1, 'legalform', '', 'Ltd'); VALUES (2, 'legalform', 'de', 'GmbH'); VALUES (3, 'legalform', 'de', 'Gesellschaft mit VALUES (4, 'legalform', 'de', 'AG'); VALUES (5, 'legalform', 'de', 'Aktiengesellschaft');
To activate stopwords for a search on a TEXT column, you need to provide two search options (similar to the options used for term mappings): stopwordListId=mylist1,mylist2,mylist3 stopwordTable=[<schemaname>.]<tablename> SELECT TO_DECIMAL(SCORE(),3,2) as score, company FROM mydata WHERE CONTAINS(company, 'xy gmbh', FUZZY(0.7, 'textsearch=compare, stopwordTable=MYSTOPWORDS, stopwordListId=legalform')) ORDER BY score DESC; To activate language-specific stopwords, you have to provide the language parameter: SELECT TO_DECIMAL(SCORE(),3,2) as score, company FROM mydata WHERE CONTAINS(company, 'xy gmbh', FUZZY(0.7, 'textsearch=compare, stopwordTable=MYSTOPWORDS, stopwordListId=legalform'), language('de')) ORDER BY score DESC;
Note
In this case, all stopwords where language_code is set to 'de' or empty will be used. Any stopwords with other language codes will be ignored. Stopwords are removed from the search term first. In this example, the result set of the search is the same as for the search '... WHERE CONTAINS(company, 'xy', ...'.
PUBLIC
473
When calculating the score, the fuzzy scores of the non-stopword terms have the biggest influence on the resulting score. Stopwords in the user input and in the database records are also given less weight than the nonstopword terms, so records with matching stopwords get a higher score than records with differing or missing stopwords. The result of the above example is as follows: Score 1.00 0.95 0.95 0.92 0.78 Company XY GmbH XY XY Aktiengesellschaft XY Gesellschaft mit beschrnkter Haftung XY Company Missing stopword Differing stopword Many differing stopwords Additional non-matching term, no stopword Comment
The value given for stopwordTable can be any valid SQL identifier as defined in the SQL reference manual. If no schema is given, the current one is used. The following examples all reference the same stopword table. SET SCHEMA schema1; SELECT ... WHERE CONTAINS(c, 'xy', FUZZY(0.7, 'stopwordTable=schema1.mystopwords, ...'))...; SELECT ... WHERE CONTAINS(c, 'xy', FUZZY(0.7, 'stopwordTable="SCHEMA1"."MYSTOPWORDS", ...'))...; SELECT ... WHERE CONTAINS(c, 'xy', FUZZY(0.7, 'stopwordTable=mystopwords, ...'))...;
Using Multiple Stopword Lists

It is possible to use more than one stopword list in a single call to CONTAINS(). The names of the stopword lists have to be specified as a comma-separated list enclosed in double quotation marks. The following example shows how to specify one or more stopword lists: /* use one stopword list */ SELECT TO_DECIMAL(SCORE(),3,2) as score, company FROM mydata WHERE CONTAINS(company, 'xy gmbh', FUZZY(0.7, 'textsearch=compare, stopwordTable=MYSTOPWORDS, stopwordListId=list01')) ORDER BY score DESC; /* or */ SELECT TO_DECIMAL(SCORE(),3,2) as score, company FROM mydata WHERE CONTAINS(company, 'xy gmbh', FUZZY(0.7, 'textsearch=compare, stopwordTable=MYSTOPWORDS, stopwordListId="list01"')) ORDER BY score DESC; /* use multiple stopword lists */ SELECT TO_DECIMAL(SCORE(),3,2) as score, company FROM mydata WHERE CONTAINS(company, 'xy gmbh', FUZZY(0.7, 'textsearch=compare, stopwordTable=MYSTOPWORDS, stopwordListId="list01,list02,list03"')) ORDER BY score DESC; /* use all stopword lists */ SELECT TO_DECIMAL(SCORE(),3,2) as score, company FROM mydata WHERE CONTAINS(company, 'xy gmbh', FUZZY(0.7, 'textsearch=compare,
474
PUBLIC
stopwordTable=MYSTOPWORDS, stopwordListId=*')) ORDER BY score DESC;
Stopword Example
CREATE COLUMN TABLE stopwords ( stopword_id VARCHAR(32) PRIMARY KEY, list_id VARCHAR(32) NOT NULL, language_code CHAR(2) NOT NULL, term NVARCHAR(200) NOT NULL ); CREATE COLUMN TABLE companies ( id INTEGER PRIMARY KEY, companyname SHORTTEXT(200) FUZZY SEARCH INDEX ON ); INSERT INTO companies VALUES ('1', 'SAP AG'); INSERT INTO companies VALUES ('2', 'SAP Aktiengesellschaft'); INSERT INTO stopwords VALUES ('1', '01', 'de', 'AG'); INSERT INTO stopwords VALUES ('2', '01', 'de', 'Aktiengesellschaft'); INSERT INTO stopwords VALUES ('3', '01', 'de', 'blub'); Query 1: User input without stopwords. Stopwords in the database table only. SELECT TO_DECIMAL(SCORE(), 3, 2) AS score, * FROM companies WHERE CONTAINS(companyname, 'sap', FUZZY(0.8, 'stopwordTable=stopwords, stopwordListId=01, textSearch=compare')) ORDER BY score DESC, ID; SCORE 0.95 0.95 ID 1 2 COMPANYNAME SAP AG SAP Aktiengesellschaft
Query 2: User input with stopword. Other stopwords in the database table. SELECT TO_DECIMAL(SCORE(), 3, 2) AS score, * FROM companies WHERE CONTAINS (companyname, 'sap blub', FUZZY(0.8, 'stopwordTable=stopwords, stopwordListId=01, textSearch=compare')) ORDER BY score DESC, ID; SCORE 0.95 0.95 ID 1 2 COMPANYNAME SAP AG SAP Aktiengesellschaft
Query 3: User input with stopword. One record with matching stopword, one record with differing stopword. SELECT TO_DECIMAL(SCORE(), 3, 2) AS score, * FROM companies WHERE CONTAINS (companyname, 'sap aktiengesellschaft', FUZZY(0.8, 'stopwordTable=stopwords, stopwordListId=01, textSearch=compare')) ORDER BY score DESC, ID;
PUBLIC
475
SCORE 1 0.95
ID 2 1
COMPANYNAME SAP Aktiengesellschaft SAP AG
Query 4: User input with two stopwords. Database records with one matching stopword. SELECT TO_DECIMAL(SCORE(), 3, 2) AS score, * FROM companies WHERE CONTAINS (companyname, 'sap ag aktiengesellschaft', FUZZY(0.8, 'stopwordTable=stopwords, stopwordListId=01, textSearch=compare')) ORDER BY score DESC, ID; SCORE 0.97 0.97 ID 1 2 COMPANYNAME SAP AG SAP Aktiengesellschaft
Stopwords Combined With Term Mappings
When stopwords and term mappings are combined in a single query, term mappings are applied first. Stopwords are then applied to all variations of the search term created by the term mappings. Let us assume that you have defined the following term mapping: Term 1 Incredible Busy Machines Ltd Now you search for "Incredible Busy Machines Ltd". The search would be carried out for all possible search terms: Search Terms Incredible Busy Machines Ltd Incredible Busy Machines Limited IBM Ltd IBM Limited Let us assume that you have defined the following stopwords: Stopword busy machines ltd The stopwords will not be searched, so the resulting search terms would be: Term 2 IBM Limited
476
Search Terms Incredible Busy Machines Ltd Incredible Busy Machines Limited IBM Ltd IBM Limited
10.2.4.8.7 Term Mappings

Facts About Term Mappings
Term mappings have the following characteristics: Term mappings can be used to extend the search by adding additional search terms to the user input. When the user enters a search term, the search term is expanded, and synonyms, hypernyms, hyponyms, and so on are added. The result that is returned to the user contains additional records or documents related to the search term that could be useful to the user. Term mappings are defined in a column table and can be changed at any time. The current term mapping definition is applied when a search is started. The definition of term mappings does not change the data that is stored in the database tables (unlike the definition of synonyms in Text Analysis, where a change of synonyms requires the text data to be reloaded or reindexed). Term mappings can be grouped. Each group of term mappings is identified by a list_id that is stored in the term mapping table. By grouping term mappings, it is possible to apply different sets of term mappings to different columns of a table. You may want to use certain term mappings when searching company names for example, and other term mappings when searching documents. When starting a search, it is possible to specify which term mapping list_ids to apply to each column. Term mappings can be assigned a weight. In this case, records that are found because of a term mapping will receive a lower score than records found with the original user input. From the user's view, the sorting of the result list is more meaningful. Term mappings are defined as a unidirectional replacement. For a term mapping definition of 'term1' -> 'term2', 'term1' is replaced with 'term2', but 'term2' is not replaced with 'term1'. This is helpful if you want a search with a hypernym to find all hyponyms, but not the other way round. If a bidirectional replacement is needed (as for synonyms), both directions have to be added to the term mapping table. Term mappings are language dependent. It is possible to define the language that a term mapping is valid for. You can also define term mappings for all languages by not setting a language.
Use Cases
Synonyms If you have a large database of company names, you might want to map the companies' legal forms.
PUBLIC
477
For example: Searching for AG Ltd You would also like to find Aktiengesellschaft Limited With a weight of 1.0 1.0
Since these are synonyms, the term mappings have to be added to the term mapping table in both directions, as shown in the example below. Usually, synonym definitions get a weight of 1.0, because records found when the term mapping is applied are as good as records found with the original user input. Hypernyms, Hyponyms If you search with a hypernym, you might also find other documents related to this topic. For example: Searching for car You would also like to find VW Golf With a weight of 0.8
Since these are not synonyms, and a search with 'VW Golf' should not return all documents about cars, the term mapping is added to the term mapping table in this direction only.
Format of the Term Mapping Table

Column Name MAPPING_ID LIST_ID LANGUAGE_CODE Type VARCHAR(32) VARCHAR(32) VARCHAR(2) Primary Key x Description Primary key Comment For example, a GUID
Term mapping list ID Used to group term mappings Language code (ISO2) Term 1, the term to be replaced Term 2, the term that replaces term 1 Weight, 0.0 <= Weight <= 1.0 NULL: term mapping is valid for all languages
TERM_1 TERM_2 WEIGHT
NVARCHAR(200) NVARCHAR(200) DECIMAL
The definition of the term mapping table is checked, so tables with other column names or data types cannot be used for a fuzzy search. Nevertheless, the table may contain additional columns that are ignored by the fuzzy search engine. Example code for creating a term mapping table: CREATE COLUMN TABLE termmappings (
478
);
mapping_id list_id language_code term_1 term_2 weight
VARCHAR(32) VARCHAR(32) VARCHAR(2), NVARCHAR(255) NVARCHAR(255) DECIMAL
PRIMARY KEY, NOT NULL, NOT NULL, NOT NULL, NOT NULL
Basic Example
The value given for the termMappingTable parameter can be any valid SQL identifier as defined in the SQL reference manual. If no schema is specified, the current schema is used. CREATE COLUMN TABLE termmappings ( mapping_id VARCHAR(32) list_id VARCHAR(32) language_code VARCHAR(2), term_1 NVARCHAR(255) term_2 NVARCHAR(255) weight DECIMAL ); CREATE COLUMN TABLE companies ( id INTEGER companyname SHORTTEXT(200) language VARCHAR(2) );
PRIMARY KEY, NOT NULL, NOT NULL, NOT NULL, NOT NULL
PRIMARY KEY, FUZZY SEARCH INDEX ON LANGUAGE COLUMN language,
INSERT INTO companies VALUES ('1','SAP AG', 'de'); INSERT INTO companies VALUES ('2','SAP Aktiengesellschaft', 'de'); INSERT INTO termmappings VALUES ('1','01','de','AG','Aktiengesellschaft','0.9'); INSERT INTO termmappings VALUES ('2','01','de','Aktiengesellschaft','AG','0.9'); SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM companies WHERE CONTAINS(companyname, 'sap aktiengesellschaft', FUZZY(0.8, 'termMappingTable=termmappings,termMappingListId=01,textSearch=compare')) ORDER BY score DESC, id; SCORE 1.0 0.9 ID 2 1 COMPANYNAME SAP Aktiengesellschaft SAP AG
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM companies WHERE CONTAINS(companyname, 'sap ag', FUZZY(0.8,'termMappingTable=TERMMAPPINGS,termMappingListId=01,textSearch=compare')) ORDER BY score DESC, id; SCORE 1.0 0.9 ID 1 2 COMPANYNAME SAP AG SAP Aktiengesellschaft
PUBLIC
479
To activate language-specific term mappings, you must provide the language parameter: SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM companies WHERE CONTAINS(companyname, 'sap ag', FUZZY(0.8,'termMappingTable=TERMMAPPINGS,termMappingListId=01,textSearch=compare'), language('de')) ORDER BY score DESC, id;
Note
In this case, all term mappings where language_code is set to 'de' or empty are used. Any term mappings with other language codes are ignored.
Using Multiple Term Mapping Lists

It is possible to use more than one term mapping list in a single call to CONTAINS(). The names of the term mapping lists have to be specified as a comma-separated list enclosed in double quotes. The following example shows how to specify one or more term mapping lists. /* use one term mapping list */ SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM companies WHERE CONTAINS(companyname, 'sap ag', FUZZY(0.8,'termMappingTable=TERMMAPPINGS,termMappingListId=01,textSearch=compare'), language('de')) ORDER BY score DESC, id; /* or */ SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM companies WHERE CONTAINS(companyname, 'sap ag', FUZZY(0.8,'termMappingTable=TERMMAPPINGS,termMappingListId="01",textSearch=compare') , language('de')) ORDER BY score DESC, id; /* use multiple term mapping lists */ SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM companies WHERE CONTAINS(companyname, 'sap ag', FUZZY(0.8,'termMappingTable=TERMMAPPINGS,termMappingListId="01,02,03",textSearch=com pare'), language('de')) ORDER BY score DESC, id; /* use all term mapping lists */ SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM companies WHERE CONTAINS(companyname, 'sap ag', FUZZY(0.8,'termMappingTable=TERMMAPPINGS,termMappingListId=*,textSearch=compare'), language('de')) ORDER BY score DESC, id;
480
10.2.4.8.8 Compound Words
Introduction
A search on a TEXT column is very sensitive to compound spelling. This means that a search for a compound word (written without blanks) might not find a document if there is an additional blank character between the components. In some cases, compound words (for example in Finnic and Germanic languages) may be a combination of more than two words. Examples of compound words: "Hans-Peter" vs. "Hanspeter" "Abfahrt Zeit" vs. "Abfahrtszeit" "Post Office" vs. "Postoffice" "soft ball" vs. "softball" "Example-Cola" vs. "ExampleCola" "htuloskytv" vs. "ht ulos kytv" (emergency exit in finnish)
To mitigate this, it is possible to generate compositions and decompositions for a query on the fly. Each (de)composition can be thought of as a term mapping (see Fuzzy Search - Term Mappings) In this context, a word is any sequence of at least two characters. The following options are offered: composeWords For more information, see Option composeWords [page 483]. decomposeWords For more information, see Option decomposeWords [page 484]. compoundWordWeight For more information, see Option compoundWordWeight [page 485].
Differences to Term Mappings

Generally, (de)compositions work like term mappings with a WEIGHT of compoundWordWeight. However, to limit the number of (mostly redundant) candidates, compound words and decomposition phrases are always searched with a fixed similarCalculationMode and fuzziness of the maximum of 0.7 and the value given by the user.
Stopwords
From a user perspective, it does not make any difference whether (de)composition terms are augmented or entered manually. (De)compositions therefore apply to stopwords as well as non-stopwords. Consequently, the
PUBLIC
481
following statement finds "SAPAG" regardless of whether "AG" is a stopword or not, and vice versa (with decomposeWords=2): CONTAINS(COMPANY, 'SAP AG', FUZZY(0.8, 'composeWords=2'))
Performance Considerations
Setting decomposeWords>=3, a large number of search terms and very long words can have a negative impact on performance, due to the large number of resulting combinations. This can be mitigated by raising minTextScore and lowering compoundWordWeight, as all combinations with an effective weight (product of all term mapping/ compound word weights) less than minTextScore can be skipped during the search. For more information, see Option minTextScore [page 470] Setting composeWords>=2 should not have a significant performance impact. Let's have a look at impact factors in different data domains
Note
Factor: An impact factor of 2 means that your runtime might be doubled. Data Domain lastnames full-text documents music tracks (short text documents) Table Rows 10 000 000 130 000 6 400 000 Dictionary Size 540 000 1 200 000 1 250 000 Request Baseline 50ms 70ms 70ms composeWor ds Factor 1 2 5 decomposeW Comment ords Factor 1.6 6 7 IDF scoring textSearch=c ompare
Examples
Creating a table: CREATE COLUMN TABLE SNACKS (TEXT TEXT FUZZY SEARCH INDEX ON); INSERT INTO SNACKS VALUES('Mini-Maxi YadaThing Comp.'); SELECT TO_DECIMAL(SCORE(),3,2) AS SCORE, TEXT FROM SNACKS WHERE CONTAINS(TEXT, 'minimaxi yada thing', FUZZY(0.7, 'ts=compare')); Score Text
SELECT TO_DECIMAL(SCORE(),3,2) AS SCORE, TEXT FROM SNACKS WHERE CONTAINS(TEXT, 'mini-maxi yadathing', FUZZY(0.7, 'ts=compare'));
482
Score 0.86
Text Mini-Maxi YadaThing Comp.
SELECT TO_DECIMAL(SCORE(),3,2) AS SCORE, TEXT FROM SNACKS WHERE CONTAINS(TEXT, 'minimaxi yada thing', FUZZY(0.7, 'ts=compare,composeWords=2,decomposeWords=2')); Score 0.7 Text Mini-Maxi YadaThing Comp.
SELECT TO_DECIMAL(SCORE(),3,2) AS SCORE, TEXT FROM SNACKS WHERE CONTAINS(TEXT, 'minimaxi yada thing', FUZZY(0.7, 'ts=compare,composeWords=2,decomposeWords=2,compoundWordWeight=1.0')); Score 0.86 Text Mini-Maxi YadaThing Comp.
SELECT TO_DECIMAL(SCORE(),3,2) AS SCORE, TEXT FROM SNACKS WHERE CONTAINS(TEXT, 'minimaxi yada thing', FUZZY(0.7, 'ts=compare,composeWords=2,decomposeWords=2,compoundWordWeight=0.8')); Score 0.55 Text Mini-Maxi YadaThing Comp.
Option composeWords
The option composeWords defines how words in the user input are combined into compound words. Option composeWords Range 1..5 Default 1 (off) Description Each consecutive series of at most composeWords words in the user input is concatenated into a compound word.
Examples
User Input gene rat ion composeWords Value => 2 Generated Compound Words generat ion
PUBLIC
483
User Input
composeWords Value
Generated Compound Words gen eration
=> 3
generat ion gen eration generation
Option decomposeWords
The option decomposeWords defines how words in the user input are split into separate words, building a decomposition phrase. Option decomposeWords Range 1..5 Default 1 (off) Description Each word in the user input is split into at most decomposeWords words .
Examples
User Input generation decomposeWords Value => 2 Generated Compound Words ge neration gen eration gene ration gener ation genera tion generat ion => 3 all of the above and ge ne ration ge ner ation ge nera tion ge nerat ion ge nerati on gen er ation gen era tion gen erat ion
484
PUBLIC
User Input
decomposeWords Value
Generated Compound Words gen erati on gene ra tion gene rat ion gene rati on gener at ion gener ati on genera ti on
Option compoundWordWeight
The option compoundWordWeight defines how compound word hits affect the score of a document. Option compoundWordWeight Range 0.0..1.0 Default 0.9 Description Compound mapping weight.
For each applied (de)composition, the score of a document is multiplied by compoundWordWeight.
Examples
User Input minimaxi yada yada company minimaxi yada yada company compoundWord Weight 0.8 composeWords 2 decomposeWor ds 2 Document mini-maxi yadayada company mini-maxi yadayada company Score Multiplier 0.8*0.8 = 0.64
0.8
0.8 (if found)
10.2.4.8.9 Speeding Up the Fuzzy Search on Text Columns

Context
You can speed up the fuzzy search for all SQL types except DATE by creating a special data structure known as a fuzzy search index. The additional data structures increase the total memory footprint of the loaded table, in some cases even doubling it.
PUBLIC
485
TEXT Columns TEXT columns offer the 'FUZZY SEARCH INDEX' option to enable and disable the indexes when creating a table: CREATE COLUMN TABLE mytable ( id INTEGER PRIMARY KEY, col1 TEXT FUZZY SEARCH INDEX ON ); You can change this later using the ALTER TABLE command. ALTER TABLE mytable ALTER ( col1 TEXT FUZZY SEARCH INDEX OFF ); The SYS.TABLE_COLUMNS view shows the current state of the fuzzy search indexes. When working with attribute views, this information is also visible in SYS.VIEW_COLUMNS. SHORTTEXT Columns SHORTTEXT columns offer the 'FUZZY SEARCH INDEX' option to enable and disable the indexes when creating a table: CREATE COLUMN TABLE mytable ( id INTEGER PRIMARY KEY, col2 SHORTTEXT(100) FUZZY SEARCH INDEX ON ); You can change this later using the ALTER TABLE command. ALTER TABLE mytable ALTER ( col2 SHORTTEXT(100) FUZZY SEARCH INDEX OFF );
Note
The following limitation applies: Since SHORTTEXT creates a hidden column of type Text, the state of the fuzzy search index is not visible in SYS.TABLE_COLUMNS and SYS.VIEW_COLUMNS. SYS.FULLTEXT_INDEXES can be used to query the state of the fuzzy search indexes. SELECT index_name, internal_column_name, fuzzy_search_index FROM fulltext_indexes WHERE table_name = 'MYTABLE'; Full-Text Indexes A full-text index offers the 'FUZZY SEARCH INDEX' option to enable and disable the indexes when creating a fulltext index: CREATE COLUMN TABLE mytable ( col3 NVARCHAR(2000) );
486
CREATE FULLTEXT INDEX myindex ON mytable(col3) FUZZY SEARCH INDEX ON; You can change this later using the ALTER FULLTEXT INDEX command: ALTER FULLTEXT INDEX myindex FUZZY SEARCH INDEX OFF; The SYS.FULLTEXT_INDEXES view shows the current state of the fuzzy search indexes. SELECT index_name, internal_column_name, fuzzy_search_index FROM fulltext_indexes WHERE table_name = 'MYTABLE';
10.2.4.9 Fuzzy Search on DATE Columns

A fuzzy search on DATE columns supports two types of error: Date-specific typos Dates lying within a user-defined maximum range
It is not possible to create additional data structures for date types in order to speed up the search. The performance of queries is perfectly satisfactory without the need for database tuning.
Note
Fuzzy search for dates works with valid dates only. A search with an invalid date does not return any results. The following example does not return any results, as '31' is not a valid month: ...WHERE CONTAINS(mydate, '2012-31-01', FUZZY(0.8))...
Score Calculation for Typos

Instead of using Levenshtein distance or other string-compare algorithms, the following date-specific typos and errors are defined as similar: 1. 2. 3. One wrong digit at any position (2011-08-15 instead of 2011-08-25 for example). This type of error gets a score of 0.90. Two digits interchanged within one component (day, month, or year) (2001-01-12, 2010-10-12, or 2010-01-21 instead of 2010-01-12 for example). This type of error gets a score of 0.85. Month and day interchanged (US versus European date format) (2010-10-12 instead of 2010-12-10 for example). This type of error gets a score of 0.80.
Only one of these errors is allowed. Dates with more than one error are not considered similar, so the score is 0.0. Dates with a score less than the fuzzySimilarity parameter are not returned.
PUBLIC
487
Example: SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM dates WHERE CONTAINS(dateofbirth, '2000-01-10', FUZZY(0.8)) ORDER BY score DESC; For this example we get: 2000-01-09 -> 0.00 (not returned to the user) 2000-01-10 -> 1.00 2000-01-11 -> 0.90 2000-01-12 -> 0.90 ... 2000-01-21 -> 0.00 (not returned to the user) ... 2000-10-01 -> 0.80
Score Calculation for Date Distance

The maximum allowed distance between dates can be defined using the search option 'maxDateDistance', which defines a number of days. The default for this option is 0, meaning that the feature is disabled. This is shown in the following example: SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM dates WHERE CONTAINS(dateofbirth, '2000-01-10', FUZZY(0.95, 'maxDateDistance=5')) ORDER BY score DESC; This query returns all dates between 2000-01-05 and 2000-01-15. The fuzzy score for dates is calculated as follows: 1. 2. 3. The identical date gets a score of 1.0. The date that is maxDateDistance days away from the search input gets a score that equals the fuzzySimilarity parameter (0.95 in the example above). The score of dates between the identical date and maxDateDistance is calculated as a linear function between the two dates defined above. In other words, for each day the score is reduced by ((1-fuzzySimilarity) / maxDateDistance). For dates outside the range of maxDateDistance, the score is 0.0.
4.
With the example above, we therefore get: 2000-01-04 -> 0.00 2000-01-05 -> 0.95 2000-01-06 -> 0.96 ...
488
2000-01-09 -> 0.99 2000-01-10 -> 1.0 2000-01-11 -> 0.99 2000-01-12 -> 0.98 ... 2000-01-15 -> 0.95 2000-01-16 -> 0.00 The distance between dates is calculated following the rules of the Gregorian calendar. The special case 'fuzzySimilarity = 1.0' and maxDateDistance=n is allowed and returns all dates within a range of n days with a rank of 1.0.
Dates That Meet Both Conditions

If a date meets the conditions of a typo and the conditions of the maxDateDistance parameter, two scores are calculated for the same date. In this case, the score() function returns the highest of both scores. This is shown in the following example: SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM dates WHERE CONTAINS(dateofbirth, '2000-01-10', FUZZY(0.8, 'maxDateDistance=5')) ORDER BY score DESC; This query returns the following: 2000-01-04 -> 0.00 2000-01-05 -> 0.80 2000-01-06 -> 0.84 2000-01-07 -> 0.88 2000-01-08 -> 0.92 2000-01-09 -> 0.96 2000-01-10 -> 1.0 2000-01-11 -> 0.96 2000-01-12 -> 0.92 2000-01-13 -> 0.90 2000-01-14 -> 0.90 2000-01-15 -> 0.90 2000-01-16 -> 0.90
PUBLIC
489
10.2.4.10 Search Rules

Overview
The fuzzy search in SAP HANA allows you to search for structured database content that is similar to the user input. In this case, the user input and the records in the database are nearly the same but differ in their spelling (for example, typing errors) or contain additional information (for example, additional or missing terms). One of the use cases for the fuzzy search on structured data is the prevention of duplicate records. New database records can be checked for similar and already existing records in real time, just before the new record is saved. For example, before saving a new customer to the database, the application checks for similar customers that may be duplicates of the new customer that has been entered. The application does some searches and then presents to the user any existing customers that are similar to the user input. The user then decides whether to create a new customer (because the records presented are similar, but not really duplicates) or to accept one of the existing customers and continue with this customer record. The searches performed by the application are defined by business rules that define when two customers are similar. For example, the application may consider two customers to be similar as soon as one of the following conditions is true: 1. 2. 3. The customers' names and addresses are similar. The customers' last names and addresses are identical but the first names are different (may be persons living in the same household). The customers' names are similar and the dates of birth are identical.
These rules can be hardcoded in the application by writing three SELECT statements that perform the three searches defined above. Whenever the requirements for the search rules change, the application code has to be changed, tested, and deployed to the productive system. This may be costly in terms of time and the development resources needed. Alternatively, the application can use search rules to store the rules as a configuration object in the SAP HANA database. Instead of embedding the rules in SELECT statements that are part of the application code, the application has to call a database procedure to process all rules defined in the configuration object. If the business requirements change, only the search rule definition in the configuration object has to be changed, tested, and deployed. The interface to the database procedure that is called by the application remains unchanged. So, without any change to the application code, the definition of the search rules is changed and the user immediately gets search results according to the new requirements. This results in much less effort and more flexibility when changing search rules.
Supported Database Objects

You can search on attribute views. The views have to be modeled using the SAP HANA studio and have to be stored as objects in the SAP HANA repository. Other database objects, such as row tables, column tables, calculation views, or analytic views, are not supported.
490
PUBLIC
Important Terms
A search rule set is the configuration object that is stored in the SAP HANA repository and that contains the definition of the search rules. When the database procedure is called to do a search, a search rule set is executed. This means that all rules that are defined in the search rule set are executed. A search rule defines a condition when two records the user input and a record in the database are considered similar. Each rule in a search rule set is converted to a SELECT statement and is executed when the search rule set is processed.
10.2.4.10.1 Creating Search Rule Sets

Prerequisites
Before you can create a search rule set in the SAP HANA Studio, you have to create a workspace and a project in the SAP HANA studio. In this workspace, you create a package that will contain your rule set. To set up the project in the SAP HANA Studio, use the connection of the user who modeled the attribute view (for example the user from the MODELOWNER tutorial) and add the package that you want to contain the search rule sets to the project (for example the package from the apps.customer tutorial).
Procedure
1. 2. 3. 4. 5. 6. In the SAP HANA modeler, open the Project Explorer view and navigate to your package. From the context menu of your package, choose New Other Search Rule Set .
Enter a file name for your rule set. The file has to have the extension .searchruleset. Open and edit the search rule set in the search rule set editor. See Working with the Search Rule Set Editor [page 492] Define the attribute view, key columns, score selection parameter, stopwords, and term mappings. See Configuring Search Rule Sets [page 493] From the context menu of your package or search rule, choose Team Activate .
Results
You can now execute a search with the rule set. See Executing a Search With a Rule Set [page 500] Related Information Search Rules - A Tutorial [page 506] This tutorial documentation describes the development of an application that uses the search rule sets to search on a table containing a company's customers.
PUBLIC
491
10.2.4.10.2 XML Structure of a Search Rule Set

Search rule sets are stored in XML files in the local file system. The search rule set editor reflects the structure of these files and displays the search rule set in a tree-like structure. To edit search rule sets, you need some basic knowledge of the structure of the XML files. The XML structure of a search rule set configuration is as follows: +Document Root +Rule Set +Attribute View +Key Column 1 +... +Key Column n +Rule 1 +Column 1 +optional: +... +Column n +optional: +... +Rule n +Column 1 +optional: +... +Column n +optional:
Column Options (text, string or date options) Column Options
Column Options Column Options
10.2.4.10.3 Working with the Search Rule Set Editor

Context
To open a rule set in the editor, double-click a rule set file or, choose the context menu. Action Adding new nodes, children or siblings Description To add new nodes, children or siblings, you can use the context menu of each node. You can a new key column node in the following ways for example: Select the attribute view node and, choose New Key Column in the context menu. Select a key column node and choose New Key Column in the context menu. Open With Search Rule Set Editor in
Deleting a node
To delete a node from the search rule set, select the node and choose Delete in the context menu. This deletes the node together with all its child nodes.
492
Action Changing the order of nodes
Description To change the order of nodes or to move nodes to other parent nodes, you can drag and drop them. With the SAP HANA studio running on Microsoft Windows, you can copy nodes below the same parent node or even to another parent node by pressing CTRL while dragging.
Changing the node properties
To change properties, click on the value of the property in the Properties view and enter the new value. Each node contains a set of properties that define the behavior of the search rules. Node properties are displayed in the Properties view in the SAP HANA studio when a node is selected in the tree. If the Properties view is not displayed, you can open it by choosing Window Show View Properties .
Note
Some node properties refer to database objects or to column names. These properties are casesensitive, so be sure to enter all names in the correct notation.
10.2.4.10.4 Configuring Search Rule Sets

Procedure
1. Define the attribute view. The search rule set searches on an attribute view that is modeled using the SAP HANA studio. The attribute view to be used is defined in the attribute view node of the search rule set. The name property contains the name of the attribute view. The FQN notation (fully qualified name) is used to specify the view. There are two ways to set the name of the view: You can type in the name of the view in the "Properties" view using the correct syntax for catalog and repository objects. You can use Drag&Drop. Drag the catalog and repository objects from the "SAP HANA Systems", view and drop them on the view node. You can also drag tables from the catalog and drop them on the "Stopwords (table-based)" and "Term Mappings (table-based)" nodes.
Once you have defined the view, and your project is shared with a HANA repository workspace, you do not need to enter all the column names and the names of the key columns manually. The "Property View" of the corresponding node (column or key column) provides you a combobox containing all availale fields. Example attribute view name: apps.customer::CUSTOMER
PUBLIC
493
2.
Define the key columns and the score selection parameter. A search might return the same record more than once, as it matches more than one rule. To enable the search to return each record just once, key columns must be defined in a way that makes records in the result set unique. For an attribute view, there is no definition of key columns available, so the key columns have to be defined for each search rule set. The key columns are a set of one or more columns of the attribute view that clearly identify a record in the view. So the key columns are similar to the primary key columns of a database table. As for primary keys, LOB types (BLOB, CLOB, NCLOB, TEXT) are not allowed as key columns.
Note
It is possible to create an invalid key column definition that does not make the result set unique. In this case, when running a search, an error is raised when records returned by a single rule are not unique. By default, each search rule set contains one key column node below the attribute view node. If more columns are needed to make records unique, more key column nodes can be added below the attribute view node. In each key column node, enter the name of the attribute view column in the properties panel. In addition to the key columns, you have to define how the result set should be made unique. Records returned by more than one rule usually have different scores assigned. Only one combination of score and rule name can be returned in the result set. The score selection parameter defines whether the values with the highest score or the values found with the first matching rule are returned. You define the score selection parameter in the properties panel of the rule set node. 3. Optional: Define stopwords and term mappings. To use stopwords and term mappings in a search rule set, the configuration options have to be added to the rule set. First, open the context menu for the Search Rule Set node and choose New Stopwords (table-based) or New Term Mappings (table based). In the properties of the new nodes, you can define the stopword table and term mapping table that is used. On the Stopwords (table-based) or Term Mappings (table-based) node, select New Column to enable the stopwords or term mappings on a column. In the properties panel, you can define the name of the column where you want stopwords and term mappings to be applied. Below the Column nodes, create new List ID nodes (open the context menu and choose New List ID). In each list ID node, you can configure a stopword or term mapping list that is applied on the column. The stopword and term mapping settings are valid for a given column in all rules. 4. Add rules. To add a new rule to the search rule set, open the context menu on the Search Rule Set node and choose New Rule. You can change the order of the rules by dragging a rule with the mouse to a new position.
494
10.2.4.10.5 Configuration Settings and Properties
Search Rule Set Properties

The only property of a search rule set is the Score Selection. Score selection defines which rule number is returned for a record if it was found by multiple rules. highestScore will choose the rule that gives the highest score for the record (used for non-hierarchical views or together with Rule Cut) and firstRule will pick the first rule (top down) that found this record (used for hierarchical rules).
Attribute View Properties

A search rule set needs an attribute view on which the rules are executed. To connect the search rule set with the attribute view, the node Attribute View with the property Name is used. Name takes the full name consisting of package and attribute view, separated by a double colon. _SYS_RT needs SELECT granted on this view. Key Columns When searching with multiple search rules, it is likely that the same row is returned by more than one rule. In this case, the search rules runtime has to make a decision on what score, rule ID, and rule number are returned for this record because EXECUTE_SEARCH_RULE_SET returns every row only once. To make the results unique, the EXECUTE_SEARCH_RULE_SET function needs a definition of the 'key columns' that identify each row. This is done by adding a Key Column node for each column the key consists of. Its property Name takes the column's name. If the key consists of multiple columns, the same number of Key Column nodes have to be defined. LOB types (CLOB, NCLOB, TEXT) are not allowed for key columns.
Stopwords and Term Mapping Properties

To use stopwords, the node Stopwords (table-based) has to be added. It takes Schema and Table names of the stopword table as properties. _SYS_RT needs SELECT granted on this table. For each column that uses stopwords, a Column node has to be added. Its property Name takes the column name for which stopwords are to be used. Multiple List ID nodes can be defined under the Column node. Their property Id indicates a list ID of the stopword table that is used for the given column. The same is valid for term mappings with the node Term Mappings (table-based).
Rule Properties
For each rule that shall be defined, a node Rule has to be added. The order of the rules (top down) in the resource set also defines the order of the execution. You name the rule by setting the Name property.
PUBLIC
495
Min Fuzziness defines the minimum score that the rule's columns have to result in to trigger this rule. All records with a lower score will not show in the result. The property Weight is a factor that lowers the rule's score (for example, a score of 0.9 with a weight of 0.9 will result in 0.81). This is used to show that the rule's hits have a lower value. Rule Cut is used to stop the processing before a rule is used. Whenever the total number of hits of earlier rules exceeds the value of Rule Cut, no more rules are processed. A value of 0 (zero) deactivates Rule Cut for this rule. Rule Cut is used for the following reasons: To separate rules (or groups of rules) that have a different hierarchy by putting a Rule Cut = 1 into the next rule (or first rule of the next group). If you do this, the next rule (or next group) will not be executed if the previous rule (or group of rules) results in hits. To speed up processing. This is done by putting a Rule Cut with the desired number of hits into every rule. As soon as this number is reached, no more rules are processed.
Column Properties
A rule needs at least one column to search on. The column's Name property points to a column of the Attribute View defined above. Min Fuzziness corresponds to the fuzziness of the fuzzy() function within the contains() statement. The property Weight is a factor that lowers the column's score (for example, a score of 0.9 with a weight of 0.9 will result in 0.81). This is used to show that the column's hits have a lower value. The column of the attribute view has a certain type in the table it is based on. The fuzzy search allows certain column options for each type. These translate directly into column properties: Column Type TEXT, SHORTTEXT, any STRING column with fulltext index Column Option Node Text Column Options Available Properties Other STRING columns String Column Options DATE, TIMESTAMP Date Column Options abbreviationSimilarity andSymmetric andThreshold bestMatchingTokenWeight considerNonMatchingToken s emptyScore enableStopwords enableTermMappings minTextScore similarCalculationMode spellCheckFactor emptyScore similarCalculationMode spellCheckFactor emptyScore maxDateDistance
496
PUBLIC
The column option nodes are optional; if not specified, default values for their properties will be used. TEXT columns (as well as SHORTTEXT and any STRING columns with fulltext index) always get the fuzzy search option textsearch=compare set. This is to ensure that the fuzzy score will be retrieved instead of the TF/IDF score. The two properties enableStopwords and enableTermMappings are not standard fuzzy() parameters. However, since stopwords and term mappings are defined for a column and are independent of the rules, these parameters are needed to individually switch them off (false) for single rules. The default value of enableStopwords and enableTermMappings is true.
Column Conditions
Each column in a rule can have three different column conditions. These conditions steer the behavior of the column and/or the rule at runtime. Depending on how the queried rule is filled, either the column will be skipped from the where clause, or the whole rule will be skipped. It is also possible to change the requested value of the column. The table below shows the various condition types, together with the properties that can be set for them: Condition If Equals Action skipColumn skipRule replace Value value to compare to Replace By new value Description Column is given in the query to the EXECUTE_SEARCH_R ULE_SET function. The condition matches if there is a request value given that equals the value of the column condition. If Not Empty skipColumn skipRule replace new value Column is given in the query to the EXECUTE_SEARCH_R ULE_SET function. The condition matches if there is any request value given. If Missing skipColumn skipRule replace new value If no column condition is given, the behavior is as follows: Missing columns in a rule cause the rule to be
PUBLIC
497
Condition
Action
Value
Replace By
Description skipped. Empty values will be requested as empty.
If the if Equals condition matches the value, the if Not Empty condition is also true. In this case, only the action for the If Equals condition will be performed. The If Equals condition can be given more than once per column. If no column condition is given, the behavior is as follows: Missing columns in a rule cause the rule to be skipped. Empty values will be requested as empty.
Configuring Column Conditions in the Search Rule Set Editor

1. Add a new column condition to your rule. Open the context menu on a column and choose a condition.
498
2.
Set the properties for the column condition. Example properties for a condition:
Example properties for the If Equals condition:
Example Search Rule Set
Let us look at this example of a search rule set:
This rule set includes the following properties:
PUBLIC
499
10.2.4.10.6 Executing a Search With a Rule Set

HANA exports a new built-in function: SYS.EXECUTE_SEARCH_RULE_SET, that you can use to execute a previously defined search rule set. The function has one parameter, which is an XML string to run the search. In the XML, you have to specify the following: The ruleset to be executed How the result will be returned The limitation of the result The input values
The EXECUTE_SEARCH_RULE_SET method returns a ResultSet object by default. This object contains all the columns from the referenced attribute view, plus the additional columns _SCORE and _RULE_ID. Alternatively, the EXECUTE_SEARCH_RULE_SET can write the result into a results table that needs to be created by the user.
500
For code samples of SYS.EXECUTE_SEARCH_RULE_SET calls, see Searching with a Rule Set - Code Examples [page 503]. Transaction Isolation Level The EXECUTE_SEARCH_RULE_SET function creates one SELECT statement for each of the rules and runs the statements independently of each other. The statements are executed in the transaction context of the calling application, and use the same isolation level as the application. The isolation level influences the results of the EXECUTE_SEARCH_RULE_SET function if other transactions that change the contents of the database tables are running in parallel . When the isolation level 'READ COMMITTED' is used, each of the SELECT statements of the search rule set sees all changes that have been committed when execution of the SELECT statement begins. The second rule of a rule set might see a new record that was not committed when the first rule was executed for example. In this case, the new record might be returned by the 'wrong' rule, and the user obtains an incorrect result. If the isolation levels 'REPEATABLE READ' or 'SERIALIZABLE' are used, all SELECT statements see the same state of the database. The results returned by EXECUTE_SEARCH_RULE_SET are therefore always correct. Available XML Tags and Parameters XML Tag query Occurence 1 1 Parameter limit offset Description Defines the maximum number of rows that are returned Defines the number of rows skipped
Note
limit and offset work as the SQL options limit and offset ruleset resulttableschema resulttablename column resultsetcolumn 0..1 0..1 1..n 0..n name name name name name Name of the ruleset that will be executed Schema name of the resulttable Table name of the resulttable Input column name Defines the column to be returned. Columns are returned in the order defined by these tags. If no resultsetcolumn is defined, all columns are returned that are defined in the attribute view plus _SCORE and _RULE_ID.
Note
This tag is not valid if you use a resulttable for the search result. In this case the resulttable defines the structure of the result. filter 0..1 SQL WHERE clause limiting the search to a subset of the view contents
PUBLIC
501
Predefined Columns Column _SCORE SQL Type Description The Fuzzy Score for each hit in the result. It can be used in combination with a result table and the resultset. The name of the rule that provided this hit. It can be used in combination with a result table and the result set. The number of the rule. The first rule is given _RULE_NUMBER 1.
_RULE_ID
_RULE_NUMBER
Note
The _RULE_NUMBER column is only returned if the user specifies this. Can be used in combination with a result table and the resultset.
Examples for Executing Rule Sets
Execute a search - Return the result as a ResultSet

CALL EXECUTE_SEARCH_RULE_SET(' <query> <ruleset name="documentation.customersearch:Search.searchruleset" /> -specifies the SearchRuleSet <column name="FIRSTNAME">Herbert</column> -- specifies the input value for column FIRSTNAME <column name="LASTNAME">Hofmann</column> -- specifies the input value for column LASTNAME </query> ');
Execute a search - Write the result to a column table provided by the user
--First create the result table set schema MY_SCHEMA; CREATE COLUMN TABLE MY_RESULT_TABLE ( _SCORE FLOAT, _RULE_ID VARCHAR(255), "FIRSTNAME" TEXT FUZZY SEARCH INDEX ON FAST PREPROCESS ON,
502
"LASTNAME" TEXT FUZZY SEARCH INDEX ON FAST PREPROCESS ON }; -- Afterwards you can execute the search using the created result table. CALL EXECUTE_SEARCH_RULE_SET(' <query> <ruleset name="documentation.customersearch:Search.searchruleset" /> -specifies the SearchRuleSet <resulttableschema name="MY_SCHEMA"/> -- specifies the schema of the result table <resulttablename name="MY_RESULT_TABLE"/> -- specifies the name of the result table <column name="FIRSTNAME">Herbert</column> -- specifies the input value for column FIRSTNAME <column name="LASTNAME">Hofmann</column> -- specifies the input value for column LASTNAME </query> '); -- get the result select * from MY_RESULT_TABLE;
Limiting the number of rows returned by a search

When calling the system procedure EXECUTE_SEARCH_RULE_SET, the application can define the maximum number of rows that are returned by setting a limit parameter. By default, this parameter is undefined, which means that an unlimited number of rows is returned. The limitation takes place after each rule and at the end when all rules are performed. In the following example, a maximum number of 100 rows will be returned. -- run the search CALL EXECUTE_SEARCH_RULE_SET(' <query limit="100"> <ruleset name="documentation.customersearch:Search.searchruleset" /> <column name="FIRSTNAME">billy</column> <column name="LASTNAME">smith</column> </query> ');
10.2.4.10.7 Searching with a Rule Set - Code Examples

This topic contains some code examples for search rule sets.
Executing a search and returning the result as a ResultSet

CALL SYS.EXECUTE_SEARCH_RULE_SET(' <query>
PUBLIC
503
<ruleset name="documentation.customersearch:Search.searchruleset" /> -specifies the SearchRuleSet <column name="FIRSTNAME">Herbert</column> -- specifies the input value for column FIRSTNAME <column name="LASTNAME">Hofmann</column> -- specifies the input value for column LASTNAME </query> ');
Executing a search and writing the result to a column table provided by the user
--First create the result table set schema MY_SCHEMA; CREATE COLUMN TABLE MY_RESULT_TABLE ( _SCORE FLOAT, _RULE_ID VARCHAR(255), "FIRSTNAME" TEXT FUZZY SEARCH INDEX ON FAST PREPROCESS ON, "LASTNAME" TEXT FUZZY SEARCH INDEX ON FAST PREPROCESS ON }; -- Afterwards you can execute the search using the created result table. CALL SYS.EXECUTE_SEARCH_RULE_SET(' <query> <ruleset name="documentation.customersearch:Search.searchruleset" /> -specifies the SearchRuleSet <resulttableschema name="MY_SCHEMA"/> -- specifies the schema of the result table <resulttablename name="MY_RESULT_TABLE"/> -- specifies the name of the result table <column name="FIRSTNAME">Herbert</column> -- specifies the input value for column FIRSTNAME <column name="LASTNAME">Hofmann</column> -- specifies the input value for column LASTNAME </query> '); -- get the result select * from MY_RESULT_TABLE;
Limiting the number of rows returned by a search

Note
When calling the system procedure EXECUTE_SEARCH_RULE_SET, the application can define the maximum number of rows that are returned by setting a limit parameter. In the default setting, this parameter is undefined, meaning that an unlimited number of rows is returned. The limitation takes place after each rule and at the end, when all rules are performed. In the following example, a maximum number of 100 rows will be returned. -- run the search CALL SYS.EXECUTE_SEARCH_RULE_SET('
504
PUBLIC
<query limit="10" offset="100"> <ruleset name="documentation.customersearch:Search.searchruleset" /> <column name="FIRSTNAME">billy</column> <column name="LASTNAME">smith</column> </query> '); You can use this parameter with the ResultSet object and with the custom result table.
Getting a paged result list by using the parameter offset

When calling the system procedure EXECUTE_SEARCH_RULE_SET, the application can return a paged result list by using the parameters limit and offset. limit defines the number of rows returned offset defines the number of rows skipped
The following example returns a result list starting from row number 101 and ending with row number 110: -- run the search CALL EXECUTE_SEARCH_RULE_SET(' <query limit="10" offset="100"> <ruleset name="documentation.customersearch:Search.searchruleset" /> <column name="FIRSTNAME">billy</column> <column name="LASTNAME">smith</column> </query> '); The parameter offset is only allowed together with the parameter limit.
Getting a user defined resultset

When calling the system procedure EXECUTE_SEARCH_RULE_SET, the application can return a user defined resultset instead of all columns defined in the attribute view. -- run the search CALL EXECUTE_SEARCH_RULE_SET(' <query limit="10" offset="100"> <ruleset name="documentation.customersearch:Search.searchruleset" /> <column name="FIRSTNAME">billy</column> <column name="LASTNAME">smith</column> <resultsetcolumn name="_SCORE" /> <resultsetcolumn name="_RULE_ID" /> <resultsetcolumn name="_RULE_NUMBER" /> <resultsetcolumn name="FIRSTNAME" /> <resultsetcolumn name="LASTNAME" /> </query> '); In this case, the application returns a result set with the columns _SCORE, _RULE_ID, _RULE_NUMBER, FIRSTNAME and LASTNAME.
PUBLIC
505
Limiting the search to a subset of the view contents

-- run the search CALL EXECUTE_SEARCH_RULE_SET(' <query> <ruleset name="documentation.customersearch:Search.searchruleset" /> <column name="FIRSTNAME">billy</column> <column name="LASTNAME">smith</column> <resultsetcolumn name="_SCORE" /> <resultsetcolumn name="_RULE_ID" /> <resultsetcolumn name="_RULE_NUMBER" /> <resultsetcolumn name="FIRSTNAME" /> <resultsetcolumn name="LASTNAME" /> <filter>"ORDER_DATE" BETWEEN '2012-09-01' AND '2012-12-31'</filter> </query> '); This filter limits the search to documents with an ORDER_DATE in the specified range. The filter condition is evaluated in every rule, before evaluating the rule cut option and the query parameters limit and offset. The filter condition must be a valid SQL WHERE clause with some extra rules: Only a limited set of SQL keywords is allowed: NOT, AND, OR, BETWEEN, IN, LIKE, ESCAPE, IS, NULL, UPPER, LOWER, SUBSTRING The CONTAINS() function is not allowed, as this would affect the score() that is returned Only columns defined in the attribute view are allowed All column identifiers must be enclosed in double quotes (")
10.2.4.10.8 Search Rules - A Tutorial

This tutorial documentation describes the development of an application that uses the search rule sets to search on a table containing a company's customers.
Prerequisites
As a developer who wants to create search rule sets, you are familar with the SAP HANA development environment. The development tools for search rule sets are part of the development environment for native SAP HANA applications. Nevertheless, search rule sets can be used in all types of SAP HANA applications.
The Scenario
This tutorial documentation describes the development of an application that uses the search rule sets to search on a table containing a company's customers. The data model used for this tutorial is very simple. Let us assume that all customers are persons, so no company information can be stored in the table.
506
Users and Roles

When building an application based on SAP HANA, different database users are created for modeling content and for running the application. Privileges have to be granted to give each user a minimum set of access rights needed to perform tasks corresponding to his/her role. The scenario in this documentation uses the following database users: The data stored in the column tables is owned by the first user called TABLEOWNER. Attribute views and search rules are modeled by a second user called MODELOWNER. Finally, the application runs with a third user called APPOWNER.
Instead of granting privileges to users directly, you can use roles.
Creating the Application Package
Context
In our example, the database content (the attribute view and the search rule set) will be stored in a package called "apps.customer".
Procedure
In the SAP HANA studio, create a new package named customer. You can create the package in the SAP HANA Systems view of the SAP HANA studio (either in the Modeler perspective or in the SAP HANA Development perspective). Use the SYSTEM user or any other user with sufficient privileges.
PUBLIC
507
Creating the Users
You have to create three users and and assign a set of privileges to them. The users are created by the administration user SYSTEM or by any other user with sufficient privileges.
Context
Procedure
1. Create the TABLEOWNER CREATE USER tableowner PASSWORD "********"; -- privilege needed to create the application schema GRANT CREATE SCHEMA TO tableowner; 2. Create the MODELOWNER CREATE USER modelowner PASSWORD "********"; -- Allow repository access from SAP HANA studio GRANT EXECUTE ON _sys_repo.repository_rest TO modelowner; -- Privileges needed to access packages in the HANA repository
508
-- read access to packages and designtime objects (native and imported objects) GRANT REPO.READ ON "apps.customer" TO modelowner; -- all kinds of inactive changes to design-time objects in native packages GRANT REPO.EDIT_NATIVE_OBJECTS ON "apps.customer" TO modelowner; -- activate / reactivate design-time objects in native packages GRANT REPO.ACTIVATE_NATIVE_OBJECTS ON "apps.customer" TO modelowner; -- create, update or delete native packages, or create subpackages of native packages GRANT REPO.MAINTAIN_NATIVE_PACKAGES ON "apps.customer" TO modelowner; -- permission go grant and revoke privileges on activated content (like, for example, attribute views) GRANT EXECUTE ON GRANT_PRIVILEGE_ON_ACTIVATED_CONTENT TO modelowner; GRANT EXECUTE ON REVOKE_PRIVILEGE_ON_ACTIVATED_CONTENT TO modelowner; -- A user needs an analytical privilege to access activated attribute views. --- The predefined privilege _SYS_BI_CP_ALL gives access to all activated content. -- Create your own analytical privilege if a limited access to activated content is needed. CALL _SYS_REPO.GRANT_ACTIVATED_ANALYTICAL_PRIVILEGE('_SYS_BI_CP_ALL', 'MODELOWNER'); -- privileges needed to run the search rules GRANT EXECUTE ON sys.execute_search_rule_set TO modelowner;
Note
_SYS_RT.SEARCH_RULE_SETS Table The _SYS_RT.SEARCH_RULE_SETS must not be queried in applications using search rule sets. If you do not want to assign a large number of privileges to each modeling user, you can create a new role containing all necessary privileges and assign this role to the users. This is the preferred option, but alternatively you can also use the predefined MODELING or CONTENT_ADMIN roles to grant the privileges. 3. Create the APPOWNER CREATE USER appowner PASSWORD "********"; -- A user needs an analytical privilege to access activated attribute views. CALL _SYS_REPO.GRANT_ACTIVATED_ANALYTICAL_PRIVILEGE('_SYS_BI_CP_ALL', 'APPOWNER'); -- privileges needed to run the search rules GRANT EXECUTE ON sys.execute_search_rule_set TO appowner;
Note
_SYS_RT.SEARCH_RULE_SETS Table The _SYS_RT.SEARCH_RULE_SETS must not be queried in applications using search rule sets.
PUBLIC
509
Creating the Database Schema and Tables
Context
You have to create a new database schema called 'CUSTOMERS' to store the database tables. Then, you create the table 'CUSTOMER' in the new schema to store information about customers such as name, address, phone number, and date of birth. The example uses a simple table definition only, but more complex table definitions including 1:n relationships between names and addresses are possible. The schema and table are created by the user TABLEOWNER.
Procedure
Creating the Database Schema and Tables CREATE SCHEMA customers; SET SCHEMA customers; -- create sample table CREATE COLUMN TABLE customer ( id INTEGER firstname SHORTTEXT(100) lastname SHORTTEXT(100) streetname NVARCHAR(100) housenumber NVARCHAR(20) 'housenumber', postcode NVARCHAR(20) 'postcode', cityname NVARCHAR(100) countrycode NVARCHAR(2), phone NVARCHAR(20), dateofbirth DATE );
PRIMARY KEY, FUZZY SEARCH INDEX ON, FUZZY SEARCH INDEX ON, FUZZY SEARCH INDEX ON,
FUZZY SEARCH MODE
FUZZY SEARCH INDEX ON FUZZY SEARCH MODE FUZZY SEARCH INDEX ON,
-- needed to model an attribute view on top of the table GRANT SELECT ON customer TO modelowner; -- needed to allow activation of attribute views that use this table GRANT SELECT ON customer TO _sys_repo WITH GRANT OPTION; -- for better performance, database indexes should be created -- on all NVARCHAR columns that are used in the search rules -- example: CREATE INDEX customer_cityname ON customer(cityname); -- insert a sample record: INSERT INTO customer VALUES(1, 'Billy', 'Smith', 'Summerset Drv', '1001', '123456789', 'Littleton', 'US', '555-1234', '1950-12-01'); -- to be able to use stopwords a stopword table is needed: CREATE COLUMN TABLE stopwords (
510
stopword_id list_id language_code term );
VARCHAR(32) VARCHAR(32) VARCHAR(2), NVARCHAR(200)
PRIMARY KEY, NOT NULL, NOT NULL
GRANT SELECT ON stopwords TO _sys_repo WITH GRANT OPTION; INSERT INTO stopwords VALUES('1', 'firstname', '', 'Dr'); -- and for term mappings another table: CREATE COLUMN TABLE termmappings ( mapping_id VARCHAR(32) PRIMARY KEY, list_id VARCHAR(32) NOT NULL, language_code VARCHAR(2), term_1 NVARCHAR(255) NOT NULL, term_2 NVARCHAR(255) NOT NULL, weight DECIMAL NOT NULL ); GRANT SELECT ON termmappings TO _sys_repo WITH GRANT OPTION; INSERT INTO '1.0'); INSERT INTO '0.9'); INSERT INTO '0.9'); INSERT INTO '1.0'); INSERT INTO '0.9'); INSERT INTO '0.9'); INSERT INTO '0.9'); INSERT INTO '0.9'); INSERT INTO '1.0'); termmappings VALUES('1', 'firstname', '', 'William', 'Will', termmappings VALUES('2', 'firstname', '', 'William', 'Bill', termmappings VALUES('3', 'firstname', '', 'William', 'Billy', termmappings VALUES('7', 'firstname', '', 'Will', termmappings VALUES('8', 'firstname', '', 'Will', termmappings VALUES('9', 'firstname', '', 'Will', termmappings VALUES('4', 'firstname', '', 'Bill', termmappings VALUES('5', 'firstname', '', 'Bill', termmappings VALUES('6', 'firstname', '', 'Bill', 'William', 'Bill', 'Billy', 'William', 'Will', 'Billy',
Defining the Attribute View
As the user MODELOWNER, you create the attribute view that is used for the search.
Context
The attribute view is created in the SAP HANA Systems view that is part of the SAP HANA studio (either in the Modeler perspective or in the SAP HANA Development perspective).
PUBLIC
511
Procedure
1. 2. In the package 'apps.customer', create a new attribute view called CUSTOMER (containing all columns from table CUSTOMERS.CUSTOMER). Save and activate the attribute view.
A SELECT privilege is required for a user to see the contents of the activated attribute view. -- allow users MODELOWNER and APPOWNER to see the contents of the attribute view CALL GRANT_PRIVILEGE_ON_ACTIVATED_CONTENT('SELECT', '"apps.customer::CUSTOMER"', 'MODELOWNER'); CALL GRANT_PRIVILEGE_ON_ACTIVATED_CONTENT('SELECT', '"apps.customer::CUSTOMER"', 'APPOWNER'); The contents of the view are now visible to users MODELOWNER and APPOWNER. -- test the view SELECT * FROM "apps.customer::CUSTOMER";
Creating the Search Rule Set
Read about the steps needed to define a search rule set and to run the final application.
Procedure
1. Preparing the Development Environment
512
PUBLIC
The SAP HANA studio is used to create, modify, and activate search rule sets. Before creating your first search rule set, you have to set up a native SAP HANA Development project in the SAP HANA studio: 1. 2. 3. Open the SAP HANA Development perspective. Create a new repository workspace in the SAP HANA Repositories view. Use the database connection of user MODELOWNER for the repository workspace. Create a new project called 'project' in package 'apps.customer'. 2. Select 'General/Project' for a project that contains search rule sets only. Select 'SAP HANA Development/XS Project' for native SAP HANA projects. Use 'Team/Share Project' to move the project to the repository package 'apps.customer'.
Defining the Search Rule Set The next step for user MODELOWNER is to define the search rule set that will be used by the application. This is done in the Project Explorer view in the SAP HANA studio. The steps to define the search rule set are as follows: 1. 2. In your project, create a new search rule set 'Search.searchruleset'. The search rule set is created in the package 'apps.customer.project'. Edit the search rule set. 3. 4. Define view "apps.customer::CUSTOMER" as the view that will be searched. Define at least one rule (for example, use columns FIRSTNAME and LASTNAME in the rule).
Save the search rule set. Commit and activate your changes.
Now you can call the search in the SAP HANA studio: -- run the search CALL SYS.EXECUTE_SEARCH_RULE_SET(' <query> <ruleset name="apps.customer:Search.searchruleset" /> <column name="FIRSTNAME">Dr. bill</column> <column name="LASTNAME">smiths</column> <column name="CITYNAME">littleton</column> <column name="DATEOFBIRTH">1950-12-02</column></query> '); 3. Running the Application The application user (APPOWNER) can now build an application that uses the attribute view and the search rules defined previously. In the application, you can call the following statements: -- show contents of attribute view SELECT * FROM "apps.customer::CUSTOMER"; -- run the search CALL SYS.EXECUTE_SEARCH_RULE_SET(' <query> <ruleset name="apps.customer:Search.searchruleset" /> <column name="FIRSTNAME">Dr. bill</column> <column name="LASTNAME">smiths</column> <column name="CITYNAME">littleton</column>
PUBLIC
513
<column name="DATEOFBIRTH">1950-12-02</column></query> ');
10.2.4.10.9 Information Views

Applications can query information about search rule sets to allow their UI to be aligned with the current configuration. The following views provide the information needed by the search applications: SYS.SEARCH_RULE_SETS SYS.SEARCH_RULE_SET_CONDITIONS
SYS.SEARCH_RULE_SETS
Applications need to know which search rule sets are defined for a given database object. Example: When a database object is searched, the user can select from a list of available search rule sets valid for the database object. The database objects used by the search rule sets can be either catalog objects like 'normal' SQL views, column tables or column views created using SQL, or design time objects like attribute views or column tables that are activated using the SAP HANA repository. Catalog objects are referenced as SEARCHED_SCHEMA_NAME and SEARCHED_OBJECT_NAME in the view. For design time objects, developers do not need to know the name of the resulting catalog object and it the search rule set the name of the design time object is used. Design time objects therefore are referenced as SEARCHED_REPOSITORY_PACKAGE_ID and SEARCHED_REPOSITORY_OBJECT_NAME. When a search rule set is activated, no catalog objects are created. All information is written to the _SYS_REPO.SEARCH_RULE_SETS. table The search rule set can therefore be referenced as a design time object only. Column SEARCH_RULE_SET_PACKAGE_ID SEARCH_RULE_SET_NAME SEARCHED_SCHEMA_NAME* Type NVARCHAR(256) NVARCHAR(256) NVARCHAR(256) Description The name of the repository package of the search rule set. The name of the search rule set. The schema of the catalog object that is searched by the given search rule set. The name of the catalog object that is searched by the given search rule set.
SEARCHED_OBJECT_NAME*
NVARCHAR(256)
514
Column SEARCHED_REPOSITORY_PACKAGE _ID*
Type NVARCHAR(256)
Description The name of the repository package of the repository object that is searched by the given search rule set. The name of the repository object that is searched by the given search rule set.
SEARCHED_REPOSITORY_OBJECT_ NAME*
NVARCHAR(256)
*: Either SEARCHED_SCHEMA_NAME and SEARCHED_OBJECT_NAME or SEARCHED_REPOSITORY_PACKAGE_ID and SEARCHED_REPOSITORY_OBJECT_NAME are given.
SYS.SEARCH_RULE_SET_CONDITIONS
Applications need to know which columns are accepted by a search rule set as input columns. This information is used to align the UI with the search rule set (for example by hiding columns that are part of the view that is searched, but are not used by the search rule set). A rule in a search rule set contains conditions that define if a rule is executed or not. A rule may be skipped if a column is empty for example. An application can use the definition of column conditions to inform the user of the minimal input, so that at least one rule is executed. Column SEARCH_RULE_SET_PACKAGE_ID SEARCH_RULE_SET_NAME RULE_NUMBER RULE_ID SEARCHED_COLUMN_NAME Type NVARCHAR(256) NVARCHAR(256) INTEGER NVARCHAR(256) NVARCHAR(256) Description The name of the repository package of the search rule set. The name of the search rule set. The number of the rule that contains the column. The ID of the rule that contains the column. The name of a column that is used by a search rule set (a 'searchable column'). The condition. Possible values are 'EQUALS', 'NOT EMPTY', 'MISSING'. The value to compare if condition is 'EQUALS'. The action that is performed if the condition is true. Possible values are 'SKIP COLUMN', 'SKIP RULE', 'REPLACE'.
SEARCHED_COLUMN_CONDITION
NVARCHAR(20) NVARCHAR(5000) NVARCHAR(20)
SEARCHED_COLUMN_VALUE
ACTION
PUBLIC
515
10.2.4.11 Support Information 10.2.4.11.1 Monitoring Views

This topic lists the monitoring views related to fuzzy search and fuzzy search indexes.
Checking the memory usage of all fuzzy search indexes with M_FUZZY_SEARCH_INDEXES
The M_FUZZY_SEARCH_INDEXES view shows the memory usage of all fuzzy search indexes. A fuzzy search index has no name and is described by its schema name, table name and column name. The view shows all columns with a fuzzy search index in a table regardless of whether or not it is loaded. Shadow columns (SHORTTEXT, FULLTEXT INDEX) are also shown in the view. The view has the following columns: View Column HOST PORT SCHEMA_NAME TABLE_NAME COLUMN_NAME PART_ID SQL Data Type VARCHAR INTEGER NVARCHAR NVARCHAR NVARCHAR INTEGER 256 256 256 Dimension 64 Default Comment Host name Internal port Schema name Table name Column name Partition ID; 0 for non-partitioned tables; 1 through n for the partitions 16 'default' or 'postcode'/'house number' (same as in SYS.Columns view) Sum of MEMORY_SIZE_IN_ MAIN and MEMORY_SIZE_IN_ DELTA Current memory consumption of the fuzzy search index of the column in main index
FUZZY_SEARCH_M ODE
VARCHAR
MEMORY_SIZE_IN_ TOTAL
BIGINT
MEMORY_SIZE_IN_ MAIN
BIGINT
516
View Column MEMORY_SIZE_IN_ DELTA
SQL Data Type BIGINT
Dimension
Default
Comment Current memory consumption of the fuzzy search index of the column in delta index
LOADED
VARCHAR
'TRUE' or 'FALSE'. Flag to indicate that the fuzzy search index of the column is loaded
Example: Memory usage in delta index ID INT PRIMARY KEY, HNR VARCHAR(255)); INSERT INSERT INSERT INSERT INTO INTO INTO INTO FUZZY_HOUSENUMBERS FUZZY_HOUSENUMBERS FUZZY_HOUSENUMBERS FUZZY_HOUSENUMBERS VALUES VALUES VALUES VALUES ('1','10'); ('2','10-12'); ('3','10a'); ('4','10b');
ALTER TABLE FUZZY_HOUSENUMBERS ALTER (hnr nvarchar(255) FUZZY SEARCH INDEX ON); SELECT to_int(score() * 100) AS s, id, hnr FROM FUZZY_HOUSENUMBERS WHERE contains((hnr), '10a', FUZZY(0.8)) ORDER BY s DESC,id; SELECT * FROM SYS.M_FUZZY_SEARCH_INDEXES WHERE TABLE_NAME = 'FUZZY_HOUSENUMBERS'; The result: Column HOST PORT SCHEMA_NAME TABLE_NAME COLUMN_NAME PART_ID FUZZY_SEARCH_MODE MEMORY_SIZE_IN_TOTAL MEMORY_SIZE_IN_MAIN MEMORY_SIZE_IN_DELTA LOAD Memory usage in main index: MERGE DELTA OF FUZZY_HOUSENUMBERS; Value YOUR HOST YOUR PORT SYSTEM FUZZY_HOUSENUMBERS HNR 0 DEFAULT 2752 0 2752 TRUE
PUBLIC
517
SELECT * FROM SYS.M_FUZZY_SEARCH_INDEXES WHERE SCHEMA_NAME = 'SYSTEM' AND TABLE_NAME = 'FUZZY_HOUSENUMBERS'; The result: Column HOST PORT SCHEMA_NAME TABLE_NAME COLUMN_NAME PART_ID FUZZY_SEARCH_MODE MEMORY_SIZE_IN_TOTAL MEMORY_SIZE_IN_MAIN MEMORY_SIZE_IN_DELTA LOAD Value YOUR HOST YOUR PORT SYSTEM FUZZY_HOUSENUMBERS HNR 0 DEFAULT 2704 2704 0 TRUE
Note
The memory values can vary depending on your environment.
Checking the memory usage with M_HEAP_MEMORY

All data structures for fuzzy search share a common 'Pool/FuzzySearch' allocator. Statistics can be obtained from the system view M_HEAP_MEMORY . SELECT * FROM m_heap_memory WHERE category LIKE '%FuzzySearch%'; Column HOST PORT VOLUME_ID STATISTICS_ID CATEGORY DEPTH INCLUSIVE_SIZE_IN_USE INCLUSIVE_COUNT_IN_USE Value "lu3412587" 30003 2 36723 "Pool/FuzzySearch" 2 4989216 14399
518
PUBLIC
Column INCLUSIVE_ALLOCATED_SIZE INCLUSIVE_DEALLOCATED_SIZE INCLUSIVE_ALLOCATED_COUNT INCLUSIVE_DEALLOCATED_COUNT INCLUSIVE_MAX_SINGLE_ALLOCATION_SIZE INCLUSIVE_PEAK_ALLOCATION_SIZE EXCLUSIVE_SIZE_IN_USE EXCLUSIVE_COUNT_IN_USE EXCLUSIVE_ALLOCATED_SIZE EXCLUSIVE_DEALLOCATED_SIZE EXCLUSIVE_ALLOCATED_COUNT EXCLUSIVE_DEALLOCATED_COUNT EXCLUSIVE_MAX_SINGLE_ALLOCATION_SIZE EXCLUSIVE_PEAK_ALLOCATION_SIZE EXCLUSIVE_ALLOC_ERRORS MALLOC_PROXY_CACHE_MISSES FLAGS
Value 15428600 10439384 49177 34778 524288 4989216 4989216 14399 15428600 10439384 49177 34778 524288 4989216 0 0 "(none)"
This information is also available in the Management Console. hdbadm@lu3412587:/usr/sap/HDB/HDB00 $ hdbcons SAP HANA DB Management Client Console (type '\?' to get help for client commands) Try to open connection to server process 'hdbindexserver' on system 'HDB', instance '00' SAP HANA DB Management Server Console (type 'help' to get help for server commands) Executable: hdbindexserver (PID: 2644) [OK] -> mm list Pool/FuzzySearch -s +----------------+-----+-----------------+-----+-----------------+------+-------+ |Name |Used |Local size |TUsed|Total size |ACount|TACount| +----------------+-----+--------+--------+-----+--------+--------+------+-------+ |Pool/FuzzySearch|14399|4989216B|4872.2KB|14399|4989216B|4872.2KB| 49177| 49177| +----------------+-----+--------+--------+-----+--------+--------+------+-------+ [OK] ->
10.2.4.11.2 Sizing Information

This topic contains information about the sizing of fuzzy search indexes. When setting FUZZY SEARCH INDEX ON, index structures are created in memory to make the fuzzy search faster. It is important to be aware of the additional memory usage when sizing an SAP HANA server. It is not
PUBLIC
519
possible to give exact numbers here, since the size of a fuzzy search index depends on the contents of the column and on the compression mode used for this column. A fuzzy search index on a VARCHAR column for example is large if each row contains a distinct value. The index is much smaller if the number of distinct values in this column is small. The size of the fuzzy search index can be determined with the M_FUZZY_SEARCH_INDEXES monitoring view. More information: Monitoring Views [page 516].
Fuzzy Search Indexes for String Types

When creating a fuzzy search index on a string-type column (VARCHAR, NVARCHAR), the size of the fuzzy search index can be up to twice the memory size of the column itself.
Fuzzy Search Indexes for Text Types

The fuzzy search index on a text-type column (SHORTTEXT, TEXT or a hidden column created with the CREATE FULLTEXT INDEX statement) needs about 10 percent of the memory size of the column. Labels parameters
10.2.4.11.3 Activating the Trace in the SAP HANA Studio

Context
Useful tracing and logging information for a fuzzy search is stored in the database traces. The traces are written for several services of the system (for example, INDEXSERVER and NAMESERVER). If the database trace is configured, trace information for the specified database will be written to files named as follows: <servicename>_<hostname>.<portnumber>.000.trc. Tracing the output of a fuzzy search is available for the components fuzzysearch, searchrulesexecution, and searchruleruntime. The trace of the component fuzzysearch shows information about selected search options and the scoring and number of search results. You should use this trace for single fuzzy search requests. If the trace for searchrulesexecution and/or searchruleruntime is configured, information about the search rule configuration and search rule set results are tracked. The components searchrulesexecution and/or searchruleruntime should be used if a search rule set that combines multiple fuzzy search requests is used.
Procedure
1. In the SAP HANA studio, open the Administration perspective by double-clicking your system name in the navigation pane.
520
2.
Select the tab Trace Configuration and choose the icon Edit Configuration at the right corner of the tracing section you want to configure.
3.
Set the trace levels in the window Database Trace.
PUBLIC
521
Trace Level NONE ERROR and FATAL WARNING INFO DEBUG 4.
Description Tracing is switched off. However, information about error situations is still recorded. Information about errors is recorded. Information about potentially problematic situations is recorded. Information about activity in the database is recorded. Detailed information intended for debugging is recorded.
To configure the trace targets, choose Show All Components and filter for fuzzysearch or searchrules, as shown below. To get information about a fuzzy search, you only have to configure the INDEXSERVER. All other servers do not output relevant information regarding a fuzzy search.
522
PUBLIC
To get basic tracing data with information for every search, set the trace level to INFO. To get detailed information for every search, set the trace level to DEBUG.
Note
DEBUG information cannot be read by end users and should be used for support issues only. The default name for the trace file is indexserver_$host_$port.000.trc. After executing a fuzzy search statement, you can find all trace files in the section Diagnosis Files of your administration perspective. To get only the information of the last request, you should delete older trace files before executing a fuzzy search. By clicking the column header of the traces table, you can reorder the trace files view, for example, by the date of the last modification.
To open a selected trace file, double-click it. If you have problems with a fuzzy search, you can download trace files of your search and send them to SAP customer support. You can download an opened trace file by using the function Download File it the left corner of the trace file window.
PUBLIC
523
10.2.4.12 Frequently Asked Questions

Why are there results with a score lower than the requested fuzzySimilarity?
In text fields, the parameter fuzzySimilarity sets the minimum similarity that a token has to match to be included in the search result. All other fuzzy search operations (for example, applying term mappings, considering stopwords, abbreviationSimilarity) can influence the score that you will see.
How many misspellings are allowed with a particular fuzzySimilarity?

This question is not easy to answer. The scoring algorithm is not linear to the number of misspellings; the position of the misspelling is also important. You can use the following example to familiarize yourself with it: DROP TABLE test; CREATE COLUMN TABLE test ( id INTEGER PRIMARY KEY, companyname SHORTTEXT(200) FUZZY SEARCH INDEX ON ); INSERT INTO test VALUES ('1','abc'); INSERT INTO test VALUES ('2','abx'); INSERT INTO test VALUES ('3','xbc'); INSERT INTO test VALUES ('4','axc'); INSERT INTO test VALUES ('5','abcx'); INSERT INTO test VALUES ('6','xabc'); SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test WHERE CONTAINS(companyname, 'abc', FUZZY(0.5,'textSearch=compare,bestMatchingTokenWeight=1')) ORDER BY score DESC, id; SCORE 1 0.89 0.82 0.75 0.61 ID 1 5 2 6 3 COMPANYNAME abc abcx abx xabc xbc
524
SCORE 0.61
ID 4
COMPANYNAME axc
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test WHERE CONTAINS(companyname, 'abcx', FUZZY(0.5,'textSearch=compare,bestMatchingTokenWeight=1')) ORDER BY score DESC, id; SCORE 1 0.89 0.88 0.75 0.59 0.59 ID 5 1 6 3 3 4 COMPANYNAME abcx abc xabc abx xbc axc
How do I find out if the fuzzy search index is enabled for column x?
See Using the CONTAINS() Predicate [page 422].
How do I enable the fuzzy search index for a particular column?

See Using the CONTAINS() Predicate [page 422]. The additional data structures will increase the total memory footprint of the loaded table. In unfavorable cases the memory footprint of the column can double.
How can I see how much memory is used for a fuzzy search index?
See Monitoring Views [page 516].
Is the score between request and result always stable for TEXT columns?
It depends on how you look at the topic. The algorithm is indeed deterministic, but you need to take all parameters into account. Cases can be constructed where a small change in the fuzzySimilarity will change the rank between the same strings. Why is this? The fuzzySimilarity is the minimum score that tokens need to reach to be considered for the result. If you use andThreshold or the keyword "OR" in your search, not all tokens have to reach the fuzzySimilarity to be
PUBLIC
525
part of the result. This can lead to a change in the total score if you change the fuzzySimilarity. Let us look at an example: DROP TABLE companies; CREATE COLUMN TABLE companies ( id INTEGER PRIMARY KEY, companyname SHORTTEXT(200) ); INSERT INTO companies VALUES(1, 'aktien gesellschaft'); INSERT INTO companies VALUES(2, 'aktiv gesellschaft'); Important: The similarity between "aktien" and "aktiv" is 0.77. If the fuzzySimilarity is lower than 0.77, the token scoring will be part of the result score. If the fuzzySimilarity is higher than 0.77, the token scoring will not be considered, so the total scoring will be lower. SELECT TO_DECIMAL(SCORE(),3,2) AS score, id, companyname FROM companies WHERE CONTAINS(companyname, 'aktiv OR gesellschaft', FUZZY(0.75, 'textSearch=compare')) ORDER BY score DESC, id; SCORE 1 0.89 ID 2 1 COMPANYNAME aktiv gesellschaft aktien gesellschaft
SELECT TO_DECIMAL(SCORE(),3,2) AS score, id, companyname FROM companies WHERE CONTAINS(companyname, 'aktiv OR gesellschaft', FUZZY(0.80, 'textSearch=compare')) ORDER BY score DESC, id; SCORE 1 0.71 ID 2 1 COMPANYNAME aktiv gesellschaft aktien gesellschaft
526
11
11.1
Setting Up Roles and Authorizations

The Authorization Model
Authorization mechanisms ensure that authenticated users can do only those things they are allowed to do. You can use the authorization mechanisms of the SAP HANA database to specify who is allowed to access which data and for which activities. Authorization mechanisms can also be used to help control who is allowed to execute stored procedures and functions or execute system-level activities, for example: making backups, creating schema, users, roles, and so on. Authorizations are specified by granting privileges to principals. Principals are either users or roles. Roles represent collections of privileges that can be granted to users or other roles, which enables you to create a hierarchy of roles. Privileges are granted to principals by users. In SAP HANA, you can use roles to assign permissions for different areas to users. For example, a role enables you to assign SQL privileges, analytic privileges, system privileges, package privileges, and so on. To create and maintain artifacts in the SAP HANA repository, you can assign application-development users pre-defined roles that provide access to the areas and objects they require.
Note
A SAP HANA user with the necessary authorization can modify existing roles, for example, to remove or restrict privileges in particular areas. Authorized users can also create new customized roles, for example, to provide application developers with precisely the privileges they need to perform the every-day tasks associated with application development. SAP HANA database authorization mechanisms use the following privileges: SQL privileges Run SQL commands and access table data System privileges Perform system-level operations or administrative tasks Object privileges Perform specified actions on specified database objects Analytic privileges Allow selective access control for database views generated when modeled are activated Package Privileges Allow operations on packages, for example, creation and maintenance. Privileges can differ for native and imported packages.
Other types of privileges enable you to provide specific additional authorizations, for example, to users who need to perform administrative tasks on objects in the repository or to users and clients that need access to applications: Repository Privileges Enable users to perform basic repository operations, for example: import and export packages, and maintain delivery units (DU) Application Privileges Enable users and clients to access an application, configure what data to expose, and set rules for exposing URLs.
SAP HANA Developer Guide Setting Up Roles and Authorizations
PUBLIC
527
11.2
Authentication Overview
Authentication is the process used to validate the identity of the users who connect to SAP HANA. Secure authentication mechanisms ensure that the users requesting a connection really are who they claim to be.
Note
For connections to SAP HANA it is important to distinguish between SQL- and HTTP-based connections. For SQL access to SAP HANA by means of client interfaces, for example, JDBC or ODBC, the following authentication methods are supported: External authentication: Kerberos services A standardized service for client authentication in networks. The client connects to the Kerberos server to authenticate the user and to acquire an authentication ticket that proves the users identity to the SAP HANA database. The client uses the ticket to connect to the SAP HANA database. Kerberos also ensures the correct identity of the server. SAML (bearer token) SAP HANA can authenticate users who provide a valid standard-based SAML assertion issued by a trusted identity provider.
Internal authentication Users are authenticated by the SAP HANA database using the database user name and password.
SAP HANA maps the external identity approved by external authentication service to the identity of an internal database user. This internal database user is then used for authorization checks during the database session. For HTTP access to SAP HANA by means of SAP HANA XS, the following authentication methods are supported: User name and password: Using HTTP basic authentication Form-based authentication
SAP logon tickets
11.3
Roles
Roles contain privileges that are used to define which data, application, or function can be accessed and in which manner consumed. Roles are assigned either to users or to other roles at runtime. SAP delivers some generic roles with SAP HANA that can be used as they are or as templates (during design time) for creating roles that meet your company's specific requirements. More information about roles, their use at runtime and in design time are explained in the subsequent sections. Roles Roles as Repository Objects Creating Roles in the Repository
528
PUBLIC
11.3.1
Roles
A role is a collection of privileges that can be granted to either a 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 in the modeler of the SAP HANA studio Database administrators operating and maintaining the database and users in the Administration editor of the SAP HANA studio
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. Several standard roles are delivered with the SAP HANA database (for example, MODELING, MONITORING). You can use these as templates for creating your own roles. Roles in the SAP HANA database can exist as runtime objects only, or as design-time objects that become runtime objects on activation.
Role Structure
A role can contain any number of the following privileges: System privileges for administrative tasks (for example, AUDIT ADMIN, BACKUP ADMIN, CATALOG READ) Object privileges on database objects (for example, SELECT, INSERT, UPDATE) 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 XS applications
A role can also extend other roles.
Role Modeling
You can model roles in the following ways: As runtime objects As design-time objects in the repository of the SAP HANA database
It is recommended that you model roles as design-time objects for the following reasons. Firstly, unlike roles created in runtime, roles created as design-time objects can be transported between systems. This is important for application development as it means that developers can model roles as part of their application's security concept and then ship these roles or role templates with the application. Being able to transport roles is also advantageous for modelers implementing complex access control on analytic content. They can model roles in a test system and then transport them into a production system. This avoids unnecessary duplication of effort. Secondly, roles created as design-time objects are not directly associated with a database user. They are created by the technical user _SYS_REPO and granted through the execution of stored procedures. Any user with access
PUBLIC
529
to these procedures can grant and revoke a role. Roles created in runtime are granted directly by the database user and can only be revoked by the same user. Additionally, if the database user is deleted, all roles that he or she granted are revoked. As database users correspond to real people, this could impact the implementation of your authorization concept, for example, if an employee leaves the organization or is on vacation.
Caution
The design-time version of a role in the repository and its activated runtime version should always contain the same privileges. In particular, additional privileges should not be granted to the activated runtime version of a role created in the repository. Although there is no mechanism of preventing a user from doing this, the next time the role is activated in the repository, any changes made to the role in runtime will be reverted. It is therefore important that the activated runtime version of a role is not changed in runtime.
11.3.2
Roles as Repository Objects
The repository of the SAP HANA database consists of packages that contain design-time versions of various objects. Being a repository object has several implications for a role.
Grantable Privileges
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 SQL 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 modeled 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 privileges are not dropped when the granting user is dropped (for example, because she leaves the company.
The following table summarizes the situation described above: Privilege System privilege Package privilege Action Necessary to Grant in Repository Role None None
530
Privilege Analytic privilege Application privilege SQL object on activated object (for example, attribute view, analytic view) SQL object privilege on runtime object (for example, replicated table)
Action Necessary to Grant in Repository Role None None None Grant privilege to user _SYS_REPO with WITH GRANT OPTION
Granting and Revoking

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 SQL object privilege EXECUTE on these procedures.
WITH ADMIN OPTION and WITH GRANT OPTION

When you create a role on the basis of SQL statements (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. Therefore, 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).
Auditability
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.
11.3.3
Custom Development Role
A role enables you to assign one or more privileges to a user according to the area in which the user works; the role defines the privileges the user is granted.
PUBLIC
531
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.
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 roledefinition file must have the suffix .hdbrole, for example, MyRoleDefinition.hdbrole. After activating the design-time role definition, you assign 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 Schema _SYS_BI SELECT for all BIMC_* tables UPDATE, INSERT and DELETE for M_* tables
SQL privileges:
Catalog object REPOSITORY_REST (SYS) EXECUTE privilege _SYS_BI_CP_ALL SELECT for the data preview on the views Package privileges: For the root package REPO.MAINTAIN_NATIVE_PACKAGES For packages containing application content REPO.EDIT_NATIVE_OBJECTS REPO.ACTIVATE_NATIVE_OBJECTS
Analytic privileges
Design-time privileges:
Application privileges: Application privileges are used to authorize users (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:
532
PUBLIC
Execute and Save privileges for the applications the developers are assigned to work on. The application privileges can be defined in a .privileges file. 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": SELECT; // 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::Execute, Save; application privilege: sap.hana.xs.debugger::Debugger; }
PUBLIC
533
Related Information Roles as Repository Objects [page 530] The repository of the SAP HANA database consists of packages that contain design-time versions of various objects. Being a repository object has several implications for a role. Creating Roles in the Repository [page 534] You model roles in the SAP HANA repository in a domain-specific language (DSL). Privileges [page 539] The Application-Privileges File [page 78] 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.
11.3.4
Creating Roles in the Repository
You model roles in the SAP HANA repository in a domain-specific language (DSL).
Prerequisites
A shared project must exist with a suitable package for storing roles. You have the package and system privileges required for modeling and activating objects in the repository.
Caution
Theoretically, a user with authorization to model 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 productive systems are imported from a test or development system and 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 have granted privileges on non-activated runtime objects that you want to grant in the new role to the technical user _SYS_REPO.
Context
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
534
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.
Procedure
1. From the main menu in the SAP HANA studio, choose Role . The New Role dialog box appears. 2. 3. 4. In the Container field, enter the path to the package where you want to create the role. In the Role name field, enter the name of the new role. Choose Finish. The new role appears in the Project Explorer view and opens in the role editor as follows: // an empty role role <package_name>::<role_name> { } The role is now ready to be defined. 5. Optional: Specify the role(s) that you want to embed within the new role. You can specify both roles created in runtime and repository roles as follows: extends role <package_name>::<role_name> extends catalog role "role_name" File New Other SAP HANA Development
Example
role <package_name>::<role_name> extends role sap.example::role1 extends catalog role "CATROLE2" { } 6. Model the required privileges.
Note
Unlike when you create a role using SQL statements, it is not possible to grant ALL PRIVILEGES when creating a role in the repository. You must model every privilege individually. a) Model system privileges using the keyword "system privilege" as follows: system privilege: PRIVILEGE;
Example
role <package_name>::<role_name> { // multiple privileges in one line are OK system privilege: BACKUP ADMIN, USER ADMIN;
PUBLIC
535
// you can also split lists into multiple entries system privilege: LICENSE ADMIN;
b) Optional: Model object privileges on the design-time objects views and procedures using the keyword "SQL object" as follows: sql object <package>:<object>.extension: PRIVILEGE;
Example
role <package_name>::<role_name> { sql object sap.example:MY_VIEW.attributeview: DROP; // object privileges can be split across lines sql object sap.example:MY_VIEW.attributeview: DROP; // a single privilege can be given on multiple objects in a single line sql object sap.example:MY_VIEW.attributeview, sap.example:MY_OTHER_VIEW.analyticview, sap.example:MY_THIRD_VIEW.analyticview: SELECT; } c) Optional: Model object privileges on catalog objects using the keyword "catalog SQL object" as follows: catalog sql object "SCHEMA"."CATALOG_OBJECT": PRIVILEGE;
Note
You must always qualify catalog objects with the schema name. You must also reference catalog objects within double quotes, unlike design-time objects.
Example
role <package_name>::<role_name> { // catalog objects must always be qualified with the schema name catalog sql object "MY_SCHEMA"."MY_VIEW": SELECT; } d) Optional: Model schema privileges on schemas using the keywords "catalog schema" or "schema" as follows depending on whether you are referring to an activated schema or a schema in the repository: catalog schema "SCHEMA": PRIVILEGE; schema <package>:<schema>.schema: PRIVILEGE;
Example
role <package_name>::<role_name> { catalog schema "MY_SCHEMA": SELECT; schema sap.example:MY_OTHER_SCHEMA.schema: SELECT; } e) Optional: Model package privileges using the keywords "package" as follows: package PACKAGE: PRIVILEGE;
536
Example
role <package_name>::<role_name> { package sap.example: REPO.READ; } f) Optional: Model analytic privileges using the keywords "analytic privilege" or "catalog analytic privilege" depending on whether you are referring to an activated analytic privilege or a runtime analytic privilege analytic privilege: <package>:<analytic_priv_name>.analyticprivilege catalog analytic privilege: "analytic_priv_name";
Example
role <package_name>::<role_name> { analytic privilege: sap.example:sp1.analyticprivilege, sap.example:AP2.analyticprivilege; catalog analytic privilege: "sp3"; } g) Optional: Model application privileges using the keyword "application privilege" as follows: application privilege: <application_priv_name>;
Example
role <package_name>::<role_name> { application privilege: sap.example::Execute; }
Note
Application privileges are implemented using the application-privileges file (.xsprivileges). 7. 8. From the main menu, choose File Save . The role is saved as an .hdbrole file. After it has been saved, the file is committed to the repository Activate the role by right-clicking it in the Project Explorer view and choosing Team Activate .
Note
Any changes made to a previously activated version of the role in runtime will be reverted on activation. This is to ensure that the design-time version of a role in the repository and its activated runtime version contain the same privileges. It is therefore important that the activated runtime version of a role is not changed in runtime.
PUBLIC
537
Results
The activated role is now visible in the Navigator view under Security Roles following the naming convention package::role_name and can be granted to users as part of user provisioning.
Example
Complete Role Definition Example role <package_name>::<role_name> extends role sap.example::role1 extends catalog role "CATROLE1", "CATROLE2" { // system privileges system privilege: BACKUP ADMIN, USER ADMIN; // schema privileges catalog schema "SYSTEM": SELECT; schema sap.example:app1.schema: INSERT, UPDATE, DELETE; // sql object privileges // privileges on the same object may be split up in several lines catalog sql object "SYSTEM"."TABLE2": SELECT; catalog sql object "SYSTEM"."TABLE2": INSERT, UPDATE, DELETE; // or a list of objects may get a list of privileges (object = table, view, procedure, sequence) // SELECT, DROP for all objects in list sql object sap.example:VIEW1.attributeview, sap.example:PROC1.procedure, sap.example:SEQ1.sequence: SELECT, DROP; // additional INSERT, UPDATE for TABLE1 sql object sap.example:MY_VIEW.attributeview: DROP; // analytic privileges analytic privilege: sap.example:sp1.analyticprivilege, sap.example:AP2.analyticprivilege; catalog analytic privilege: "sp3"; // design time privileges package sap.example: REPO.EDIT_NATIVE_OBJECTS; package sap.example, sap.co: REPO.READ; application privilege: sap.example::Execute, sap.example::Save; }
Related Information Setting Up Your Application [page 42] In SAP HANA Extended Application Services (SAP HANA XS), the design-time artifacts that make up your application are stored in the repository like files in a file system. You first choose a root folder for your applicationdevelopment activities, and within this folder you create additional subfolders to organize the applications and the application content according to your own requirements. The Application-Privileges File [page 78] 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. SAP HANA Administration Guide
538
PUBLIC
11.4 Privileges
SAP HANA offers various privileges that can be assigned to users. Users can be a system, an application, a service, or a person, and each user is assigned specific roles. Privileges can be assigned to users, roles, or both. There are several privileges that are required either by the SAP HANA studio or by development tools, such as SQL. The following types of privileges are explained in the subsequent sections. System privileges Object privileges Package privileges Analytic privileges
This section also contains information for creating and granting privileges to users.
11.4.1
System Privileges
System privileges are required to perform system-level operations or administrative tasks. The following lists shows some of the most common system-level tasks that administrators regularly must perform: Database schema Creation and deletion of database schema Users/Roles Maintenance and management of users and roles Monitor/Trace Administration of monitoring and tracing Backup/Restore Performance of backup and restore operations
In the SAP HANA database the user SYSTEM has all system privileges. The SYSTEM user can grant system privileges to other users and roles.
11.4.2
Object Privileges
Object privileges enable users to perform specified actions on specified database objects. Object privileges are not specific to the SAP HANA database; they are part of the SQL standard. You can use the SQL statements GRANT and REVOKE to manage privileges.
Note
. If object privileges (or any other privilege type) are granted to roles created in the repository, granting and revoking actions happen through the execution of stored procedures.
PUBLIC
539
The set of actions that can be allowed by an object privilege depends on the object type. For tables, you can use actions such as: drop, alter, select, insert and update. An execute action is available for privileges for procedures and functions. Privileges on a schema level are used to enable actions such as: create objects, perform select, update, delete or execute operations on all objects contained in the schema. In the SAP HANA database object privileges are not only available 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. Some database objects depend on other objects. Views, for example, are defined as queries on other tables and views. The authorization for an operation on the dependent object (the queried tables and views) requires privileges for the dependent object and the underlying object. In case of views, the SAP HANA database implements the standard SQL behavior. A user has the authorization for an operation on a view if the following is true: The privilege for operations on the view has been granted to the user or a role assigned to the user. The owner of the view has the corresponding privileges on the underlying objects with the option to grant them to others.
This behavior can be used to grant selective access to a table.
11.4.3
Package Privileges
In the SAP HANA repository, authorizations can be assigned to individual packages. Authorizations assigned to 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.
Note
Package authorizations can be set for a specific user or for a role. 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 authorizations, there is a distinction to be made 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 package objects 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 should only be modified in exceptional cases, for example, to carry out emergency repairs.
540
PUBLIC
To perform every-day, package-related, application-development tasks in the repository, developers typically need the following privileges for the application packages: REPO.READ Read access to the selected package and design-time objects (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
To perform every-day application-development tasks on imported packages, developers need the following privileges:
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. REPO.EDIT_IMPORTED_OBJECTS Authorization to modify design-time objects in packages originating in a system other than the one the user is working in REPO.ACTIVATE_IMPORTED_OBJECTS Authorization to activate/reactivate design-time objects in packages originating in a system other than the one the user is working in REPO.MAINTAIN_IMPORTED_PACKAGES Authorization to update or delete native packages, or create sub-packages of packages originating in a system other than the one in which the user is working
11.4.3.1
SAP HANA Repository Privileges
In addition to the authorizations you can grant users for specific packages (and the design-time objects in those packages), you can also assign general system privileges to users to enable them to perform basic repository operations, for example: importing and exporting content, and maintaining delivery units (DU). If your daily tasks include general administration tasks, you need basic system-level privileges in the repository. To perform basic administration tasks in the repository, you typically need the following privileges: REPO.EXPORT Enables you to export delivery units; exporting a DU transports it to another system REPO.IMPORT Enables you to import delivery units; importing a DU transports it from another system REPO.MAINTAIN_DELIVERY_UNITS Enables you to maintain your own delivery units (the DU-vendor must equal the system-vendor) REPO.WORK_IN_FOREIGN_WORKSPACE Enables you to move objects from a "foreign" inactive workspace into your own workspace
PUBLIC
541
You can grant or revoke basic, repository privileges to users in the following ways: SAP HANA Studio The System Privileges tab page in the Modeler perspective: Catalog -> Authorization -> Roles or Users
Caution
If you want to access the repository from the SAP HANA studio, Eclipse, or other clients,you need the EXECUTE privilege for SYS.REPOSITORY_REST, the database procedure through which the REST API is tunneled.
11.4.3.2
Defining Repository Package Privileges
In the SAP HANA repository, 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. You can also specify if the assigned user authorizations can be passed on to other users.
Context
To set user (or role) authorizations for repository packages, perform the following steps:
Procedure
1. 2. Open the SAP HANA Systems view in the SAP HANA studio's Modeler perspective. In the SAP HANA Systems view, expand the Security Roles/Users repository that contains the packages you want to grant access to. node for the system hosting the
You can also define roles via source files; roles defined in this way can be assigned to a delivery unit and transported to other systems. 3. 4. 5. 6. 7. 8. Double click the user (or role) to whom you want to assign authorizations. Open the Package Privileges tab page. Choose [+] to add one or more packages. Press and hold the Ctrl key to select multiple packages. In the Select Repository Package dialog, use all or part of the package name to locate the repository package that you want to authorize access to. Select one or more repository packages that you want to authorize access to; the selected packages appear in the Package Privileges tab page. Select the packages to which you want authorize access and, in the Privileges for screen page, check 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
542
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
11.4.4 Analytic Privileges

SQL privileges implement coarse-grained authorization at object level only. Users either have access to an object, such as a table, view or procedure, or they do not. 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 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. Analytic privileges are intended to control read-only access to SAP HANA information models, that is: Attribute views Analytic views Calculation views
Therefore, all column views modeled and activated in the SAP HANA modeler automatically enforce an authorization check based on analytic privileges. Column views created using SQL must be explicitly registered for such a check (by passing the parameter REGISTERVIEWFORAPCHECK).
Note
Analytic privileges do not apply to database tables or views modeled on row-store tables. Access to database tables and row views is controlled entirely by SQL object privileges. You create and manage analytic privileges in the SAP HANA modeler.
11.4.4.1
Structure of 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. Each restriction 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 specification of these restrictions is contained in an XML document that conforms to a defined XML schema definition (XSD).
PUBLIC
543
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. 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 view(s) 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.
544
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>
Activity Restriction
This restriction specifies the activities that the user is allowed to perform on the restricted view(s), 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
Note
All analytic privileges automatically become immediately valid and have unlimited validity when activated in the SAP HANA modeler. This restriction is therefore not configurable.
PUBLIC
545
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 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 analytical 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> 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"
546
PUBLIC
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>
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"))
PUBLIC
547
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")
11.4.4.2 Dynamic Value Filters in the Attribute Restriction of Analytic Privileges

The attribute restriction of an 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. This allows userspecific filter conditions to 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
548
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.
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. 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.
PUBLIC
549
If the procedure fails to execute, the users 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. 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.
11.4.4.3 Runtime Authorization Check of Analytic Privileges

When a user requests access to data stored in an attribute, analytic, or calculation view, an authorization check based on analytic privileges is performed and the data returned to the user is filtered accordingly. Access to a view and the way in which results are filtered depend on whether the view is independent or associated with other modeling views (dependent views).
Independent Views
The authorization check for a view that is not defined on another modeling view is as follows: 1. The user requests access to an individual view, for example with a SELECT query. This is possible if the both of the following prerequisites are met: The user has been granted the SQL privilege SELECT on the view or the schema in which it is located. The user has been granted an analytic privilege that is applicable to the view. An analytic privilege is applicable to a view if it contains the view in the view restriction and at least one filter on one attribute of the view.
Note
The user does not require the SELECT privilege on the underlying base tables or views of the modeling view. 2. The authorization check determines the analytic privileges that are relevant for the current user and view. Relevant analytic privileges are those that met all of the following criteria: Analytic privileges previously granted to the user, either directly or indirectly through a role Analytic privileges with a view restriction that includes the accessed view Analytic privileges with a currently valid validity restriction
Note
This check is always positive for analytic privileges created and activated in the SAP HANA modeler.
550
Analytic privileges with an activity restriction covering the activity requested by the query are considered
Note
This check is always positive for analytic privileges created and activated in the SAP HANA modeler. 3. Analytic privileges with dimension restrictions covering some of the views attributes
If no relevant analytic privileges are found, the users queries are rejected with a Not authorized error. This means that even though the user has the SELECT privilege on the view, access is not possible. If the user does have a relevant analytic privilege but does not have the SELECT privilege on the view, access is also not possible. If relevant analytic privileges are found, the authorization check evaluates the value filters specified in the dimension restrictions and presents the appropriate data to the user.
Note
Multiple dimension restrictions and/or multiple value filters are combined as described in the section on the structure of analytic privileges.
Dependent Views
Calculation views can be defined by selecting data from other column views, in particular, attribute views, analytic views, and other calculation views. This can lead to a complex view hierarchy that requires careful design of rowlevel authorization. If a user requests access to such a calculation view that is dependent on another view, the behavior of the authorization check and result filtering is performed as follows: A user can access a calculation view based on other view(s) if both of the following prerequisites are met: The user has been granted the SELECT privilege on the calculation view or the schema that contains the calculation view. The user has been granted analytic privileges that cover the calculation view itself and all the other column views in the hierarchy.
Result filtering on the calculation view is performed as follows: 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.
Note
If an analytic view designed in the SAP HANA modeler contains one of the elements listed below, the analytic view will be activated automatically with an calculation view (with the name of the analytic view appended by the suffix /olap) on top of it. Currency or unit conversions Calculated attributes Calculated measures that use attributes, calculated attributes, or input parameters in their formulas
PUBLIC
551
This represents a view hierarchy for which the prerequisites described above apply.
Note
An analytic view can be defined on attribute views. However, this in no way represents a view dependency or hierarchy with respect to authorization check and result filtering. Analytic privileges are checked and combined independently for the analytic view and their related attribute views. However, as the analytic view inherits and exposes the same attributes from the attribute views, the same filters on the same attribute can be used in analytic privileges to filter an analytic view and its related attribute views. This is convenient to define in a single analytic privilege with the view restriction including both the analytic view and the related attribute views to control access to the views together.
11.4.4.4 Creation and Management of Analytic Privileges

Analytic privileges can be created, dropped, and changed in the SAP HANA modeler. To create analytic privileges, the system privilege CREATE STRUCTURED PRIVILEGE is required. To drop analytic privileges, the system privilege STRUCTUREDPRIVILEGE ADMIN is required. In the SAP HANA modeler, repository objects are technically created by the technical user _SYS_REPO, which by default has the system privileges for both creating and dropping analytic privileges. To be able to create, activate, drop, and redeploy analytic privileges in the SAP HANA modeler therefore, a database user requires the package privileges REPO.EDIT_NATIVE_OBJECTS and REPO.ACTIVATE_NATIVE_OBJECTS for the relevant package.
Granting and Revoking Analytic Privileges

You grant and revoke analytic privileges in the same way as other privilege types. As repository objects, analytic privileges are owned by the _SYS_REPO user. To be able to grant and revoke an analytic privilege, a user needs the privilege EXECUTE on the procedures GRANT_ACTIVATED_ANALYTICAL_PRIVILEGE and REVOKE_ACTIVATED_ANALYTICAL_PRIVILEGE respectively. Related Information SAP HANA Administration Guide SAP HANA Developer Guide
11.4.4.5 Example: Creating an Analytic Privilege with Dynamic Value Filter

This example shows you how to create using SQL an analytic privilege that contains a dynamic procedure-based value filter and a fixed value filter in the attribute restriction.
552
Context
Note
The analytic privilege in this example is created using SQL. Under normal circumstances, it is recommended that you create analytic privileges using the SAP HANA modeler. Analytic privileges created using SQL 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 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. 4. Create the analytic privilege: CREATE STRUCTURED PRIVILEGE '<?xml version="1.0" encoding="utf-8"?> <analyticPrivilegeSchema version="1"> <analyticPrivilege name="AP2"> <cubes>
PUBLIC
553
<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())
11.4.5
Creating Analytic Privileges
You apply analytic privileges when business users access values with certain combinations of dimension attributes. You can use them to partition data among various users sharing the same data foundation. You can define restrictions for a selected group of models or apply them to all content models across packages.
Prerequisites
You have system privileges CREATE STRUCTURED PRIVILEGE and STRUCTUREDPRIVILEGE ADMIN to create, activate and drop the privilege. CREATE STRUCTURED PRIVILEGE and STRUCTUREDPRIVILEGE ADMIN are correctly owned by the SYS_REPO user. , The database user has corresponding repository privileges, namely REPO.EDIT_NATIVE_OBJECTS and REPO.ACTIVATE_NATIVE_OBJECTS to activate and redeploy analytic privileges in the Modeler.
554
PUBLIC
Context
The attribute restriction of an 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. This allows userspecific filter conditions to 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. After activation, an analytic privilege needs to be assigned to a user before taking any effect. The user views the filtered data based on the restrictions defined in the analytic privilege. If no analytic privilege applicable for models is assigned to a user, he or she cannot access the model. If a user is assigned to multiple analytic privileges, the privileges are combined with OR conditions.
Remember
In addition to the analytic privileges, a user needs SQL Select privileges on the generated column views. The generated column views adhere to the following naming conventions: For a view MyView in package p1.p2 (that is, subpackage p2 of package p1), the generated column view lies in schema _SYS_BIC and is named _SYS_BIC.p1.p2/MyView. Ensure that the users who are allowed to see the view have select privileges on the view (or the entire schema _SYS_BIC).
Note
Multiple restrictions applied on the same column are combined by OR. However, restrictions across several columns are always combined by AND.
Procedure
1. Set Parameters for the Analytic Privilege a) If you are in the Modeler perspective, do the following: 1. 2. 3. 4. 5. 6. Expand the system node from the SAP HANA Systems view. Expand the Content node. Select the required package. From the context menu, choose New Analytic Privilege . Enter a name and description for the analytic privilege, and choose Next. Select the information models that you want to use for applying restrictions and choose Finish
Tip
You can choose to add more models in the editor pane. b) If you are in the SAP HANA Development perspective, perform the following: 1. 2. Select a project and in the context menu, choose In the pop-up wizard, select SAP HANA Modeler. New Other... .
PUBLIC
555
3. 4. 2.
Select Analytic Privilege. Enter a name and description for the analytic privilege, and choose Finish.
Select Applicable to all Information Models optionIf you want to add restrictions for all models.
Note
If you do not select this option, the restrictions you create apply only to the secured list of models available in the Reference Models panel that you selected above. 3. In the Associated Attributes Restrictions panel, choose Add to select the attributes for defining restrictions, and choose OK
Note
If you do not add any attributes for restrictions there will be unrestricted access to the selected models or to all the models (if Applicable to all the Information Models option is selected). 4. In the Assign Restrictions pane, choose Add to add value restriction for the selected attributes. Select the required Type: Table 26: Type Fixed Description If you want to create an analytic privilege with static filter conditions such that, once granted to a user, will be automatically applied to all the queries of a user to restrict the query results only to the authorized data. Example For example, DEPARTMENT IN ("Finance", "Development") on the DEPARTMENT attribute of the view. A granted user can then only access records of the view qualifying the filter condition, as the results of all queries of the user on the view are automatically filtered using the filter condition For example, the same filter condition in the example above can be defined as DEPARTMENT IN (GET_DEPARTMENT_FOR_USER( )) Here, GET_DEPARTMENT_FOR_USER is a database procedure, which can contain any arbitrarily complex logic to determine the relevant DEPARTMENT value for a given user. At runtime, the procedure is executed and the obtained result is employed as operand in the actual filter condition DEPARTMENT IN <...>.
Catalog Procedure or Repository Procedure
For example, DEPARTMENT IN ("Finance", "Development") on the DEPARTMENT attribute of the view. A granted user can then only access records of the view qualifying the filter condition, as the results of all queries of the user on the view are automatically filtered using the filter condition
556
Note
Only views for which the property Enable Analytic Privilege is set to true, are checked for the applied restrictions while querying the views otherwise, no restriction is checked against the view. This is required in some of the scenarios like, the suite virtual data model in which only the query views (top level views) needs to be protected by analytic privileges. The underlying views should only be protected by SQL privileges. The operators supported are: IN <list of scalar value> CONTAINSPATTERN <pattern with *> EQUAL (=), LESSEQUAL (<=), LESSTHAN (<), GREATERTHAN (>), GREATEREQUAL (>=) <scalar value> BETWEEN <scalar value as lower limit> <scalar value as upper limit>. NULL and IS NULL is not supported. 5. Select the required operator and enter a value (manually or via Value Help dialog).
Note
If you are not using the value help for adding value for dynamic privilege, the syntax for repository procedure is <package name>::<procedure name>. In case of catalog procedure, the syntax is "<schema name>".<procedure name>. 6. Activate the analytic privilege using the Save and Activate option in the editor.
Remember
To activate the analytic privilege, you must assign a minimum of one restriction to each attribute.
Note
Select the Save and Activate All option to activate the privilege along with all the required objects. 7. Assign the privilege to a user a) In the SAP HANA Systems view, go to b) In the context menu, choose Open. c) Choose the Analytic Privileges tab page, and add the privilege. d) From the editor toolbar, choose Deploy. Security Authorizations Users . Select a user.
Example
Consider an analytic view (without fields coming from attribute views) or a calculation view SALES, which is added as part of an analytic privileges secured models having the following data. CUST_ID
1 2 3 1
CUST_GROUP
GRP1 GRP2 GRP3 GRP4
SALES
1000 1500 1200 1300
If you create a restriction on column CUST_ID to filter data for CUST_ID 1 and 2, the conditions are combined with OR and the data available for a user is:
PUBLIC
557
CUST_ID
1 2 1
CUST_GROUP
GRP1 GRP2 GRP4
SALES
1000 1500 1300
If you create restrictions on columns CUST_ID and CUST_GROUP such as CUST_ID = 1 and CUST_GROUP = 1, the conditions are combined with AND, and the data available for a user is: CUST_ID
1
CUST_GROUP
GRP1
SALES
1000
Note
The technical name used for attributes of calculation views and local attributes of analytic views, is the same as that of the attribute name. Hence any restriction applied to a local attribute of an analytic or calculation view attribute is also applied to any other local attribute of an analytic view and calculation view attribute having the same name. In the above example, if there is any other analytic view or calculation view, which is part of a privileges secured list of models, and has a field called CUST_ID (not coming from any attribute view), the data for these privileges also gets restricted. If Applicable to all information models is selected, any analytic view/calculation view (even if not part of the secured models) which has a (private) attribute called CUST_ID, the data for these privileges also get restricted. The behavior for the calculation view is the same as that of the analytic view described above.
Consider an attribute view CUSTOMER which is part of an analytic privileges secured list of models having the following data. CUST_ID
1 2 3 1
COUNTRY
IN IN US DE
MANDT
1 1 1 2
If you create a restriction on column CUST_ID to filter data for CUST_ID 1 and 2, the conditions are combined with OR and the data is shown as follows: CUST_ID
1 2 1
COUNTRY
IN IN DE
MANDT
1 1 2
If you create restrictions on columns CUST_ID and COUNTRY such as CUST_ID = 1 and COUNTRY = IN, the conditions are combined with AND, and the data available for a user is: CUST_ID
1
COUNTRY
IN
MANDT
1000
558
Note
The technical name used for an attribute view attribute is <package name>/<attribute view name> $<attribute name>. In the above example, the technical name for CUST_ID is mypackage/ CUSTOMER$CUST_ID. This implies that if there is any other attribute view STORE which is a part of the analytic privilege and has CUST_ID as its attribute, it is restricted. Any analytic view that is part of the privileges secured list of models and has this attribute view as its required object, is also restricted. In the example above, if an analytic view contains the attribute views CUSTOMER and STORE, both CUST_ID attributes are handled independently, because their internal technical name used for the privilege check are mypackage/CUSTOMER$CUST_ID and myotherpackage/STORE$UST_ID. If Applicable to all information models is selected, any analytic view (even if it is not part of the secured models) having this attribute view as its required object, is also restricted.
Related Information Structure of Analytic Privileges [page 543] 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. Each restriction 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. Runtime Authorization Check of Analytic Privileges [page 550] When a user requests access to data stored in an attribute, analytic, or calculation view, an authorization check based on analytic privileges is performed and the data returned to the user is filtered accordingly. Access to a view and the way in which results are filtered depend on whether the view is independent or associated with other modeling views (dependent views). Dynamic Value Filters in the Attribute Restriction of Analytic Privileges [page 548] The attribute restriction of an 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. This allows userspecific filter conditions to 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. Creation and Management of Analytic Privileges [page 552] Analytic privileges can be created, dropped, and changed in the SAP HANA modeler. Example: Creating an Analytic Privilege with Dynamic Value Filter [page 552] This example shows you how to create using SQL an analytic privilege that contains a dynamic procedure-based value filter and a fixed value filter in the attribute restriction.
11.4.6 Granting Privileges to Users

Privileges can be granted to database users either directly, or indirectly through roles that they have been granted. In this case, the privileges are inherited. Roles are the standard mechanism of granting privileges to users.
PUBLIC
559
Prerequisites
To be able to grant and revoke privileges and roles to and from users and roles, the following prerequisites must be met: Action Grant system privilege, object privilege, or package privilege to user or role Grant analytic privilege to user or role Prerequisite Granting user must have the privilege being granted and be authorized to grant it to other users and roles Granting user must have the object privilege EXECUTE on the procedure GRANT_ACTIVATED_ANALYTICAL_PRIVILEGE Granting user must have the object privilege EXECUTE on the procedure GRANT_PRIVILEGE_ON_ACTIVATED_CONTENT Granting user must have the role being granted and be authorized to grant it to other users and roles, or Granting user must be have the system privilege ROLE ADMIN
Grant object privilege on activated modeled objects, such as calculation views, to user or role Grant role created in runtime to user or role
Grant role created in the repository to user or role Grant application privilege Grant object privilege on schema containing activated modeled objects, such as calculation views, to user or role Revoke system privilege, object privilege, or package privilege from user or role Revoke object privilege on schema activated containing modeled objects, such as calculation views, from user or role Revoke analytic privilege from user or role
Granting user must have the object privilege EXECUTE on the procedure GRANT_ACTIVATED_ROLE Granting user must have the object privilege EXECUTE on the procedure GRANT_APPLICATION_PRIVILEGE Granting user must have the object privilege EXECUTE on the procedure GRANT_SCHEMA_PRIVILEGE_ON_ACTIVATED_CONT ENT Revoking user must be the user who granted the privilege Revoking user must have the object privilege EXECUTE on the procedure REVOKE_SCHEMA_PRIVILEGE_ON_ACTIVATED_CON TENT Revoking user must have the object privilege EXECUTE on the procedure REVOKE_ACTIVATED_ANALYTICAL_PRIVILEGE Revoking user must be the user who granted the role Revoking user must have the object privilege EXECUTE on the procedure REVOKE_ACTIVATED_ROLE Revoking user must have the object privilege EXECUTE on the procedure REVOKE_APPLICATION_PRIVILEGE
Revoke role created in runtime from user or role Revoke role created in the repository from user or role Revoke application privilege
560
Action Revoke object privilege on activated modeled objects, such as calculation views from user or role
Prerequisite Revoking user must have the object privilege EXECUTE on the procedure REVOKE_PRIVILEGE_ON_ACTIVATED_CONTENT
Procedure
1. 2. In the SAP HANA Systems view, choose Security Users .
Open the relevant user and grant the required roles and privileges (object privileges, analytic privileges, system privileges, and package privileges) to the user. To grant a role or privilege, choose the button and search for the required role or privilege.
To allow the user to pass on his or her privileges to other users, select Grantable to other users and roles.
Note
This option is not available if you are granting a role that was created in the repository.
Note
You cannot grant application privileges directly to users in the SAP HANA studio. It is recommended that you grant application privileges to roles created in the repository and then grant the role to the user. 3. Choose the (Deploy) button to save the changes.
Related Information SAP HANA Administration Guide
11.5
Application Access
When you develop and deploy applications in the context of SAP HANA Extended Application Services (SAP HANA XS), you must define the application descriptors, which describe the framework in which the application runs. This application framework includes the root point in the package hierarchy where content is to be served to client requests, whether or not the application is permitted to expose data to client requests, what kind of access to the data is allowed, and what if any privileges are required to perform actions on application-related packages and package content. The application descriptors include the following files: Application-descriptor file The location of the application-descriptor file defines the root path of the resources exposed to client requests by the application you develop. You can further restrict access using the application-access and application-privileges files. 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
PUBLIC
561
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), allow or prevent the creation of entity tags (Etags), and so on. 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. Application-Privileges File 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 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.
Note
An additional access-related file, the SQL-connection configuration file, enables you to execute SQL statements from inside your SAP HANA XS JavaScript application with credentials that are different to the credentials of the requesting user. Each SQL-connection configuration object has a unique name, and the administrator can assign specific, individual database users to this configuration. Related Information The Application-Descriptor File [page 63] 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 Application-Access File [page 65] SAP HANA XS enables you to define access to each individual application package that you want to develop and deploy. The Application-Privileges File [page 78] 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.
562
12
Implementing Lifecycle Management
Application lifecycle management includes all the activities that you need to plan and perform to ensure that the software components you develop for SAP HANA Extended Application Services (SAP HANA XS) are not only produced and shipped in a regulated way but also meet the requirements laid out for the SAP HANA platform. This applies to related objects as well, for example, analytic views and SQLScript artifacts. During design time, you can use application-lifecycle management tools to create a product, create and assign a delivery unit (or delivery units) to a product, create packages in a delivery unit, and create an application in a package. Using these application-lifecycle management tools at design time ensures that all entities are defined, stay together, and can be implemented easily at runtime. For information about the SAP HANA lifecycle manager, see the SAP HANA Update and Configuration Guide. Related Information SAP HANA Update and Configuration Guide
12.1
SAP HANA Application Lifecycle Manager
The SAP HANA Application Lifecycle Manager enables you to create your product, delivery unit, package, and basic application components. Additionally, the SAP HANA Application Lifecycle Manager enables administrators to set up the transport of delivery units, start and monitor transports, and upload or download delivery unit archives. The product you create comprises all components for its lifecycle management. The SAP HANA Application Lifecycle Manager provides a straightforward method for creating the product framework that supports your application development and its lifecycle management. For example, to enable application development activities, first you create metadata for both the product and delivery unit (DU). Then you create repository packages and, optionally, some frequently used base objects. Additionally, you can assign existing delivery units to a product. As an administrator you can use the SAP HANA Application Lifecycle Manager as a single point of access to perform the following tasks: Designate source and target systems for transports Assign the appropriate delivery units to the transport route Execute exports and imports (uploads and downloads) Monitor the transport processes
The SAP HANA Application Lifecycle Manager tool is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm.
Note
With the SAP HANA Application Lifecycle Manager, your authorization level determines which tasks you are able to perform. Authorization levels are granted by assigning the appropriate role, for example, sap.hana.xs.lm.roles::Administrator. If you do not have the required level of access, certain buttons are disabled, and certain options are hidden.
SAP HANA Developer Guide Implementing Lifecycle Management
PUBLIC
563
12.2 Maintaining the SAP HANA Application Lifecycle Manager

The SAP HANA Application Lifecycle Manager is a Web-based tool that runs in SAP HANA Extended Application Services (SAP HANA XS).
Prerequisites
To maintain the SAP HANA Application Lifecycle Manager, you must ensure that the following prerequisites are met: A SAP HANA system is available SAP HANA XS is up and running on the SAP HANA system You have system privileges on the SAP HANA system (for example, to add users)
Context
To maintain the SAP HANA Application Lifecycle Manager, for example, to add users or set the content vendor ID, you must perform the following high-level steps:
Note
To create SAP HANA users and assign privileges to these new users, you must have administrator access to the SAP HANA system.
Procedure
1. Create the necessary SAP HANA users, for example, the SAP HANA Application Lifecycle Manager administrator.
Note
This step must be performed in the SAP HANA system by a user with administrator privileges. 2. Assign user privileges. Access to features and options in the SAP HANA Application Lifecycle Manager is based on user privileges, which are assigned in user roles, for example, administrator or transport manager. 3. Set the Vendor ID. The vendor ID sets the namespace in the SAP HANA where your application development takes place, for example, sap.com or com.mycompany.
564
PUBLIC
Note
The namespace sap is restricted; you must not develop your own applications in this namespace. Place your packages in your own namespace, which you can create alongside the sap namespace.
Next Steps
For information about high-level lifecycle management, see the SAP HANA Update and Configuration Guide. Related Information SAP HANA Update and Configuration Guide
12.2.1
Application Lifecycle Management Tasks
The responsibility for the tasks you perform with the SAP HANA Application Lifecycle Manager is shared between dedicated lifecycle management roles. The responsibility for common application-lifecycle management performed with the SAP HANA Application Lifecycle Manager is shared between the various lifecycle management roles, which must be assigned to the SAP HANA users who start the SAP HANA Application Lifecycle Manager. For example, the Administrator role enables access to all options and tools in the SAP HANA Application Lifecycle Manager. To start a transport operation based on a defined route, you only need the privileges assigned with the user role ExecuteTransport. The Display role enables a user to view details of the delivery units, routes, and transports, but cannot make any changes. The following table provides an overview of the most common tasks performed with the SAP HANA Application Lifecycle Manager and which user role is required to perform the specified task.
Note
The SAP HANA systems you use as destination for delivery unit (DU) transport operations as well as the SAP HANA users required to complete the operation must be set up by an SAP HANA administrator. Table 27: SAP HANA Application Lifecycle Management Task/Role Matrix Task Create product, DU, package, application... Export DU Import DU Add transport destination Setup transport route Execute transport Administrator X X X X X X X X Execute Transport Display
PUBLIC
565
Task
Administrator
Execute Transport X
Display X
View log files for transport, X export, import operations
12.2.2 SAP HANA Application Lifecycle Management Roles

To grant users the privileges they require to perform tasks with the SAP HANA Application Lifecycle Manager you must assign them one or more dedicated application lifecycle management roles. The following table lists the roles that must be assigned to users who want to perform lifecycle-managementrelated tasks with the Web-based SAP HANA Application Lifecycle Manager tool. The roles are hierarchical and interlinked. For example, by default, the Administrator role grants the privileges included in all other roles; the ExecuteTransport role grants the privileges assigned in the Transport and Display roles.
Note
Some lifecycle-management tasks require interaction with external tools, and this requires additional privileges, which you can grant by assigning the appropriate roles. For example, to register an HTTP destination as part of the setup of a transport route, you need to supply logon credentials for an existing technical user on the source system - the system defined in the HTTP destination configuration. To maintain logon credentials, you can use the SAP HANA XS Administration Tool, which requires privileges assigned in the role sap.hana.xs.admin.roles::HTTPDestAdministrator. To display all available roles, start the SAP HANA studio, and in the SAP HANA Systems view, expand the node Security Roles .
Table 28: SAP HANA Application Lifecycle Management Roles Role Name sap.hana.xs.lm.roles::Administrator Description Full read/write access to all the features in the SAP HANA Application Lifecycle Management tool, including the access privileges granted to all other user roles available in the SAP HANA Application Lifecycle Management, for example, Display, ExecuteTransport, and Transport. View-only access; some features and options are hidden. A user with this role can view all information available but cannot make any changes or trigger any transport operations. Users with this role can view all information as well as trigger predefined transport operations. However, users with this role cannot register or maintain systems, create transport routes, or edit details of a product, a delivery unit, or a package. For technical users only. This role cannot be assigned to normal users; it is granted as part of the ExecuteTransport role. The Transport role grants the
sap.hana.xs.lm.roles::Display
sap.hana.xs.lm.roles::ExecuteTransport
sap.hana.xs.lm.roles::Transport
566
Role Name
Description privileges required for export or import actions during a transport operation. The credentials and privileges of a technical user with the Transport role cannot be used for interactive logons, for example, to start the SAP HANA Application Lifecycle Manager.
12.2.3 Assigning User Privileges

Access to features and functionality in SAP HANA Application Lifecycle Manager is based on roles and privileges; the role you have determines the tasks you can perform.
Prerequisites
To assign privileges to users of the SAP HANA Application Lifecycle Manager, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have administrator/system privileges on the SAP HANA system (for example, you can add/maintain database users)
Context
In the SAP HANA Application Lifecycle Manager, the availability of features, screens, tabs, and UI controls (for example, Add, Edit, or Save, or Delete buttons) is based on user privileges. For the sake of convenience, the specific privileges required to use the features provided with a particular tool have been collected into a selection of specific roles, which you assign to the user who needs to use a particular tool.
Note
To start the SAP HANA Application Lifecycle Manager, you must have been assigned one of the dedicated lifecycle-management roles, for example, Display. To assign the required privileges to people who want to use the features provided by the SAP HANA ALM tool, perform the following steps:
Procedure
1. In SAP HANA studio, create an administrator for SAP HANA application life cycle management.
PUBLIC
567
The SAP HANA application lifecycle management administrator requires the SAP HANA XS user role sap.hana.xs.lm.roles::Administrator. You can now start the SAP HANA ALM tool; SAP HANA application lifecycle management is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/ hana/xs/lm/. Log on with the user credentials of the newly created application-lifecycle-management administrator. 2. In SAP HANA studio, create a normal user for SAP HANA application life cycle management. The SAP HANA application lifecycle management user requires the SAP HANA XS user role sap.hana.xs.lm.roles::Display. 3. In SAP HANA studio, create a transport manager for SAP HANA application life cycle management. The SAP HANA application lifecycle management transport manager requires the SAP HANA XS user role sap.hana.xs.lm.roles::ExecuteTransport. 4. In SAP HANA studio, create a technical user for SAP HANA application life cycle management on each SAP HANA system that is a source for a transport operation. The technical user for SAP HANA application lifecycle management transport requires the SAP HANA XS user role sap.hana.xs.lm.roles::Transport.
12.2.4 Maintaining the Delivery-Unit Vendor ID

Prerequisites
To set the vendor ID, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been assigned the SAP HANA XS user role sap.hana.xs.lm.roles::Administrator
Context
Before creating your first own delivery unit you must set the identity of the vendor in the development system's configuration. To maintain details of the delivery-unit vendor ID, perform the following steps:
Procedure
1. Start the SAP HANA Application Lifecycle Manager.
568
The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm
Note
To start the SAP HANA Application Lifecycle Manager, you must use the logon credentials of an existing database user, who has the appropriate user role assigned. 2. 3. Switch to the CONFIGURATION tab. Maintain details of the vendor ID. In the CONFIGURATION tab, perform the following steps: a) Choose Change Vendor. b) In the Setup Vendor dialog, enter the name of the new vendor, for example, mycompany.com. c) Choose OK to save the changes. The new vendor ID is displayed in the Vendor box.
Note
The vendor ID is required to create a delivery unit.
12.3 Maintaining Repository Packages

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.
Note
You can also create and delete packages in the Project Explorer, for example, by creating or deleting folders in shared projects and committing and activating these changes. However, to maintain advanced package properties (for example, privileges, component, the package maintainer, and so on) you must use the Modeling perspective in the SAP HANA studio. As part of the process of maintaining your application packages, you typically perform the following tasks:
PUBLIC
569
Procedure
1. Creating a package Packages are necessary to group logically distinct artifacts together in one object location that is easy to transport. 2. Defining 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. 3. Defining 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. Related Information Creating a Package [page 60] 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. Defining the Package Hierarchy [page 60] Packages belonging to an application-development delivery unit (DU) should be organized in a clear hierarchical structure under a single root package representing the vendor, for example, acme.com. Defining Package Privileges [page 59] In the SAP HANA repository, 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. You can also specify if the assigned user authorizations can be passed on to other users.
12.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. 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
570
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 Hierarchy
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 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.
Note
You can only assign one project per package; this is important to remember if you have a mixture of designtime objects that need to be used in multiple projects, for example: server-side JavaScript (XSJS), SAPUI5, and a general project (for procedures). 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
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.
PUBLIC
571
Package Types
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 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.
Package Naming Conventions

The following rules apply to package names: Permitted characters Lower/upper case letters (aA-zZ), digits (0-9), hyphens (-), 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 maximum permitted length of a package name is 190 characters. To avoid problems, we recommend you restrict the length of package names to well under the 190-character limit. Package namespace 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. To avoid problems, we recommend you restrict the length of the package namespace to well under the 190-character limit.
572
PUBLIC
12.3.2 Creating a Package

Create a package in the SAP HANA Application Lifecycle Manager; you can add an SAP HANA application to the new package.
Prerequisites
To perform this task, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been assigned the SAP HANA XS user role sap.hana.xs.lm.roles::Administrator
Context
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. 5. Choose the PRODUCTS tab. Choose the PACKAGES tab. Choose the plus sign (+) on the left-hand side of the PACKAGES tab. The New Package dialog box appears. Define the details of the new package. When entering the DU details, note the following points: Name You must specify a package name in the Name box. The name must also include the full path to the repository location where you want to create the new package, for example, MyCompany.com.MyPackage.
Note
There are conventions for package names and the package path uses the dot (.) character to as a package delimiter. Original Language The language you specify here is optional and for translation purposes only.
PUBLIC
573
6. 7.
Choose Create to add the new package to the SAP HANA repository in the location specified in the path. Check the status bar at the bottom of the browser window for error messages. Click the message link to display the message text.
Results
You have created a new package. Related Information Creating an Application [page 576] If you use the SAP HANA Application Lifecycle Manager to create an application, you create a shell application that includes the mandatory application descriptors. Subsequently, you can build the application in the SAP HANA studio. Defining a Package Hierarchy [page 60] Packages belonging to an application-development delivery unit (DU) should be organized in a clear hierarchical structure under a single root package representing the vendor, for example, acme.com.
12.3.3 Defining a Package Hierarchy

Packages belonging to an application-development delivery unit (DU) should be organized in a clear hierarchical structure under a single root package representing the vendor, for example, acme.com.
Context
The package hierarchy for a new project might include 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.
Note
You can only assign one project per package; this is important to remember if you have a mixture of designtime objects that need to be used in multiple projects, for example: server-side JavaScript (XSJS), SAPUI5, and a general project (for procedures). The following simple example shows a package structure containing tutorials for the use of a new application: acme \
hana \ app1
docs
tutorials
574
Package hierarchy Each vendor uses a dedicated namespace, for example, acme.
Note
Do not use the namespace sap to build your application hierarchy. The namespace sap is reserved for use by SAP; packages created in the sap namespace are overwritten by system updates. 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.
To set up a package hierarchy in the SAP HANA repository, perform the following steps:
Procedure
1. Create a new root package. Open the Modeler perspective and perform the following steps: a) Choose b) Choose 2. New > Package Create... .
Maintain the package details. In the Create Package dialog, perform the following steps: a) Enter the name of the package (mandatory). Guidelines and conventions apply to package names. b) Enter a package description (optional). c) Specify the delivery unit that the package is assigned to. You can add additional packages to a delivery unit at a later point in time, too. d) Specify a language for the package content. e) Assign responsibility of the package to a specific user (optional). By default, the responsible user for a new package is the database user connected to the SAP HANA repository in the current SAP HANA studio session. f) Maintain translation details. If you plan to have the content translated, you need to maintain the translation details; this is covered in another topic.
3.
Create a new subpackage. In the SAP HANA Systems view of the Modeler perspective, perform the following steps: a) Right-click the package to which you want to add a new subpackage. b) In the pop-up menu, choose New > Package...
4.
Maintain the subpackage details. In the Create Package dialog, perform the following steps: a) Enter the name of the subpackage (mandatory). Guidelines and conventions apply to package names.
PUBLIC
575
b) Enter a description for the new subpackage (optional). c) Specify the delivery unit that the subpackage is assigned to. You can add additional packages to a delivery unit at a later point in time, too. d) Specify a language for the subpackage content. e) Assign responsibility of the subpackage to a specific user (optional). By default, the responsible user for a new package is the database user connected to the SAP HANA repository in the current SAP HANA studio session. f) Maintain translation details. If you plan to have the content translated, you need to maintain the translation details; this is covered in another topic. Related Information SAP HANA Delivery Unit Naming Conventions [page 46] The delivery unit (DU) is the vehicle that lifecycle management (LCM) uses to ship software components from SAP (or a partner) to a customer. The DU is also the container you use to transport application content in your system landscape. In SAP HANA, the name of a DU must adhere to conventions and guidelines.
12.3.4 Creating an Application

If you use the SAP HANA Application Lifecycle Manager to create an application, you create a shell application that includes the mandatory application descriptors. Subsequently, you can build the application in the SAP HANA studio.
Prerequisites
To perform this task, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been assigned the SAP HANA XS user role sap.hana.xs.lm.roles::Administrator
Context
By creating the application here, you have the option to create a schema and developer role at the same time as you create the new application framework; the developer role defines the privileges you need to maintain the application packages in the repository. Creating the infrastructure at one time reduces the effort required to create the same artifacts using the tools provided in the SAP HANA studio. To create a new application using the SAP HANA Application Lifecycle Manager, perform the following steps:
576
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. Choose the PRODUCTS tab. Choose the PACKAGES tab. Locate the package where you want to create a new application modify. Expand the nodes in the Package Browser on the left-hand side of the PACKAGES tab and select the package you want to modify, for example, by adding a new application. 5. Define the details of the new application. a) In the PACKAGE DETAILS panel, choose Create Application. b) In the Create Web Application dialog: Schema If you want to create a schema (with the necessary privileges), enable the Schema check box and type the name of the schema that you want to create. The new schema provides the privileges required to maintain application-specific runtime objects in SAP HANA, for example, tables, views, and procedures. Developer Role If you want to create a new developer role, enable the Developer Role checkbox and type the name of the developer to create. The new developer role provides the privileges required to maintain packages in the repository.
6.
Add the new application to the selected package. Choose Create to add anew application shell to the currently selected package. The application-creation process adds the basic files that an application requires, for example: .xsapp The application root file .xsaccess The application-access file
Note
Neither the .xsapp nor the .xsaccess file has a name - only a file extension. 7. Check the status bar at the bottom of the browser window for error messages. Click the message link to display the message text.
12.4 Maintaining Delivery Units

A delivery unit is a collection of packages that are to be transported together. You assign all the packages belonging to your application to the same delivery unit to ensure that they are transported consistently together within your system landscape. Each delivery unit has a unique identity.
PUBLIC
577
Prerequisites
To maintain delivery units with the SAP HANA Application Lifecycle Manager, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been granted the SAP HANA user role sap.hana.xs.lm.roles::Administrator A vendor ID is already defined
Context
The identity of a delivery unit consists of two parts: a vendor name and a delivery-unit name. The combined ID ensures that delivery units from different vendors are easy to distinguish and follows a pattern that SAP uses for all kinds of software components. To create and manage delivery units you first need to maintain the identity of the vendor, with whom the delivery units are associated, and in whose namespace the packages that make up the delivery unit are stored. As part of the vendor ID maintenance process, you must perform the following tasks:
Procedure
1. Understand delivery units You must be familiar with the conventions that exist for delivery-unit names and understand the phases of the delivery-unit lifecycle. 2. Maintain details of the vendor ID associated with a delivery unit. Delivery units are located in the namespace associated with the vendor who creates them and who manages the delivery-unit's lifecycle. 3. 4. Create a delivery unit. Assign packages to a delivery unit.
Related Information Maintaining the Delivery-Unit Vendor ID [page 45] In SAP HANA, the vendor ID is used primarily to define the identity of the company developing a software component, which it plans to ship for use with SAP HANA, for example, sap. If you want to create a delivery unit, it is a prerequisite to maintain a vendor ID in your system. Creating a Delivery Unit [page 46] A delivery unit is a group of transportable objects used for content delivery. You can use the SAP HANA Application Lifecycle Manager to create a delivery unit for your application content or your software component.
578
PUBLIC
12.4.1
SAP HANA Delivery Units
In SAP HANA, the delivery unit (DU) is the vehicle that lifecycle management (LCM) uses to ship one or more software components from SAP (or a partner) to a customer . Delivery Units correspond to an "application" with versions, for which support packages and patches are delivered. Delivery units are not an equivalent to development classes; they are similar to Software Component Versions in the Product Availability Matrix (PAM). You can also use the delivery unit to transport repository content between SAP HANA systems, for example, between development systems or between development and productive systems.
Note
A governance plan exists for the naming of delivery units and the package structure. A delivery unit is identified by the following key properties: Vendor Used primarily to define the identity of the company producing the software component to deliver, for example, "sap". However, vendor can also be used to specify any customer implementing SAP HANA. To create a delivery unit, it is a prerequisite to maintain a vendor in your system. Name Used to identify the software component to be delivered
Although a vendor might provide multiple versions of a delivery unit in parallel, only one version of a delivery unit can be installed in a HANA system at any one time. In addition, duplicate names are not allowed for delivery units. SAP HANA treats delivery units and their versions as software components and software-component versions. Software components and software-component versions are usually shipped as part of a product (product version).
Note
If you try to create a delivery unit using a name that already exists in your system, you will receive a validation error. A validation error also occurs if the check for a valid vendor ID does not find a suitable entry.
12.4.2 SAP HANA Delivery Unit Naming Conventions

The delivery unit (DU) is the vehicle that lifecycle management (LCM) uses to ship software components from SAP (or a partner) to a customer. The DU is also the container you use to transport application content in your system landscape. In SAP HANA, the name of a DU must adhere to conventions and guidelines. If you create a delivery unit, the name of the new delivery unit must adhere to the following conventions A delivery-unit name must contain only capital letters (A-Z), digits (0-9), and underscores (_). You cannot use an underscore (_) as the first character of a delivery-unit name. The maximum length of a delivery-unit name must not exceed 30 characters
PUBLIC
579
Note
The naming conventions for packages in a delivery unit differ from the naming conventions that apply to the delivery unit itself. For example, the maximum length of a package name is not restricted to 30 characters; however, it must be less than 190 characters (including the namespace hierarchy).
12.4.3 The SAP HANA Delivery-Unit Lifecycle

In SAP HANA, lifecycle management (LCM) includes all the activities you need to plan and perform to ensure that the software components you develop for SAP HANA Application Services are produced and shipped in a regulated way that meets the requirements laid out for the SAP HANA platform. For example, you need to plan, manage, and maintain the application versions you want to ship, and you need to ensure that a stable plan exists to provide support for existing and all future versions of your application. SAP HANA lifecycle management uses the delivery unit (DU) is a vehicle to ship one or more software components from SAP (or a partner) to a customer. Delivery units correspond to an "application" with versions, for which support packages and patches are delivered. You can also use the delivery unit to transport content between SAP HANA systems, for example, between development systems or between development and productive systems.
Note
Delivery units are not to be confused with development classes; delivery units are similar to software component versions in the Product Availability Matrix (PAM).
The Application-Development Lifecycle

Application development on SAP HANA requires a server-centric lifecycle for design-time objects, which are the development artifacts that you store in the SAP HANA repository. As an application developer, you check out design-time content from the repository and edit a copy of the checked-out artifact in the local file system on your personal computer (PC). The following steps provide a brief, high-level overview of the development lifecycle for design-time content: 1. Check out design-time content. Check out the package containing the design-time artifacts that you want to work on (if the package already exists). Edit the design-time content. Edit the copies of the design-time artifacts, which are stored in your SAP HANA repository "workspace" on your local file system; the local copies of the design-time artifacts are created during the checkout process. Commit changes to design-time content. Committing the changes you have made to the design-time artifacts creates new versions of the artifacts in the SAP HANA repository. Note that identical (unchanged) versions of a file are not committed. Activate changes to design-time content. Activating the changes you have made to the design-time artifacts makes these changes available to applications and to other users, creating runtime objects where necessary.
2.
3.
4.
580
12.4.4 Creating a Delivery Unit

A delivery unit is a group of transportable objects used for content delivery. You can use the SAP HANA Application Lifecycle Manager to create a delivery unit for your application content or your software component.
Prerequisites
To create a delivery unit with the SAP HANA Application Lifecycle Manager, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been granted the SAP HANA user role sap.hana.xs.lm.roles::Administrator The vendor ID is defined for the delivery unit; the vendor ID defines the repository namespace in which the new delivery unit resides
Context
You use a delivery unit to transport the design-time objects that are stored in the SAP HANA repository between two systems, for example, from a development system to a consolidation system. To create a new delivery unit using the SAP HANA Application Lifecycle Manager, perform the following steps.
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. 5. Choose the PRODUCTS tab. Choose the DELIVERY UNITS tab. Choose the plus sign (+) on the left-hand side of the DELIVERY UNITS tab. The New Delivery Unit dialog box appears. Enter details of the new delivery unit. When entering details, note the following points: Name The field is mandatory and you must follow strict naming conventions, for example, use capital letters. Vendor ID This field is mandatory. However, you cannot enter a vendor ID here; the box is populated by the value you enter when defining the vendor ID in the CONFIGURATION tab. Version Version numbers must take the form #.#.#, for example, 1.0.5, where:
PUBLIC
581
1 = the DU version number 0 = the support package version (if required) 5 = the patch version (if required)
Note
The numbers you enter here refer to the application component that you are developing; the numbers do not refer to the patch or service-pack level deployed on the SAP HANA server. 6. Choose Create. The new delivery unit is added to the SAP HANA repository in the namespace specified by the vendor ID and the application path. 7. Check the status bar at the bottom of the browser window for error messages. Click the message link to display the message text.
Results
You have created a delivery unit. Related Information SAP HANA Application Lifecycle Manager [page 563] The SAP HANA Application Lifecycle Manager enables you to create your product, delivery unit, package, and basic application components. Additionally, the SAP HANA Application Lifecycle Manager enables administrators to set up the transport of delivery units, start and monitor transports, and upload or download delivery unit archives.
12.4.5 Assigning Packages to a Delivery Unit

By default, a new delivery unit is empty; you must assign packages to it manually
Prerequisites
To assign packages to a delivery unit with the SAP HANA Application Lifecycle Manager, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been granted the SAP HANA user role sap.hana.xs.lm.roles::Administrator
582
PUBLIC
Context
A delivery unit contains one or more packages. You must assign the packages to the delivery unit manually. You can also remove (unassign) packages from a delivery unit and edit the details of a package. To assign packages to a delivery unit, perform the following steps:
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. Choose the PRODUCTS tab. Choose the DELIVERY UNITS tab. Select the delivery unit to which you want to assign some packages. The ASSIGNED PACKAGES panel displays the current contents of the selected delivery unit.
Tip
To remove (unassign) a package from a delivery unit, select the package and choose Unassign. 5. Assign new packages to the delivery unit. Choose Assign and enter the name of the package you want to assign to the delivery unit including the full package path, for example, mycompany.com.myapp.package1 6. Check the status bar at the bottom of the browser window for error messages. Click the message link to display the message text.
Related Information Creating a Delivery Unit [page 46] A delivery unit is a group of transportable objects used for content delivery. You can use the SAP HANA Application Lifecycle Manager to create a delivery unit for your application content or your software component. Maintaining Repository Packages [page 55] 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.
12.4.6 Exporting a Delivery Unit

You can export a delivery unit (for example, to a file) for your application content or your software components using the SAP HANA Application Lifecycle Manager.
PUBLIC
583
Prerequisites
To export a delivery unit with the SAP HANA Application Lifecycle Manager, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been granted one of the following SAP HANA user roles: sap.hana.xs.lm.roles::Administrator sap.hana.xs.lm.roles::ExecuteTransport
Context
A delivery unit is a group of transportable objects used for content delivery. You can use a delivery unit to transport the design-time objects that are stored in the SAP HANA repository between two systems, for example, from a development system to a consolidation system. To export a delivery unit (for example, from the SAP HANA repository to a file) using the SAP HANA Application Lifecycle Manager, perform the following steps.
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. Choose the PRODUCTS tab. Choose the EXPORT TO FILE tab. Select the delivery unit you want to export. In the Delivery Units list, locate and select the DU you want to export to a file.
Tip
You can check the details and contents of the selected in the Delivery Unit Details and Assigned Packages panels respectively. 5. Export the selected DU. Choose Export DU to file to display a dialog that enables you to specify the location, for example, on a local file system, where you want to save the exported DU.
Note
Depending on the browser settings, the import might start automatically or the file location is not requested, for example, because a default location exists for all download operations.
584
12.4.7 Importing a Delivery Unit

You can import a delivery unit (for example, from a file) for your application content or your software components using the SAP HANA Application Lifecycle Manager.
Prerequisites
To import a delivery unit with the SAP HANA Application Lifecycle Manager, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been granted the SAP HANA user role sap.hana.xs.lm.roles::Administrator
Context
A delivery unit is a group of transportable objects used for content delivery. You can use a delivery unit to transport the design-time objects that are stored in the SAP HANA repository between two systems, for example, from a development system to a consolidation system. To import a delivery unit (for example, from a file to the SAP HANA repository) using the SAP HANA Application Lifecycle Manager, perform the following steps.
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. Choose the UPLOAD/DOWNLOAD tab. Choose the IMPORT FROM FILE tab. Select the delivery unit you want to import. Choose Browse to display a file explorer, which you can use to locate the DU you want to import.
Tip
Exported DUs have the file extension .tgz, for example, MyDU.tgz. 5. Import the selected DU. Choose Import DU from file to import the selected delivery unit.
Note
The import operation overwrites any identical objects in the target system with the content of the imported DU.
PUBLIC
585
12.5 Maintaining Products

A product contains one or more delivery units. A delivery unit is a collection of packages that are to be transported together. You assign delivery units to a product to ensure that they are transported consistently together within your system landscape.
Prerequisites
To maintain products with the SAP HANA Application Lifecycle Manager, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been granted the SAP HANA user role sap.hana.xs.lm.roles::Administrator A vendor ID is already defined
Context
To create and manage products, you first need to maintain the delivery units which you assign to the product. A delivery unit requires a vendor ID, the name of the vendor with whom the delivery units are associated and in whose namespace in the SAP HANA repository the packages that make up the delivery unit are stored. As part of the product maintenance process, you must perform the following tasks:
Procedure
1. Maintain delivery units You must be familiar with the conventions that exist for delivery-unit names and understand the phases of the delivery-unit lifecycle. 2. 3. Create a product. Assign delivery units to a product.
Related Information Creating a Product [page 587] Use the SAP HANA Application Lifecycle Manager to create a product and its components. Assigning a Delivery Unit to a Product [page 588] A product can contain one or more delivery units. You must assign the delivery unit to the product manually. Maintaining Delivery Units [page 44] A delivery unit is a collection of packages that are to be transported together. You assign all the packages belonging to your application to the same delivery unit to ensure that they are transported consistently together within your system landscape. Each delivery unit has a unique identity. Maintaining the Delivery-Unit Vendor ID [page 45]
586
12.5.1
Creating a Product
Use the SAP HANA Application Lifecycle Manager to create a product and its components.
Prerequisites
To perform this task, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been assigned the SAP HANA XS user role sap.hana.xs.lm.roles::Administrator The vendor ID is already defined for the delivery units you assign to the product
Context
A product contains one or more delivery units, packages, and can contain applications associated with the packages. To use the SAP HANA Application Lifecycle Manager to create a new product, perform the following steps:
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. 5. Choose the PRODUCTS tab. Choose the PRODUCTS tab. Choose the plus sign (+) on the left-hand side of the PRODUCTS tab. The New Product dialog box appears. Define the details of the new product. In the New Product dialog, specify a name for the new product.
Tip
The Vendor ID box is populated with the value defined in the CONFIGURATION tab; you cannot enter or change the value here.
PUBLIC
587
6.
Create the new product. Choose Create to add the new product to the list of products displayed in the PRODUCTS tab. The new product is empty at this stage; you must assign one or more delivery units to it.
Related Information Assigning a Delivery Unit to a Product [page 588] A product can contain one or more delivery units. You must assign the delivery unit to the product manually.
12.5.2 Assigning a Delivery Unit to a Product

A product can contain one or more delivery units. You must assign the delivery unit to the product manually.
Prerequisites
To assign delivery units to a product, you must ensure the following prerequisites are met: You have access to an SAP HANA system You have been assigned the SAP HANA XS user role sap.hana.xs.lm.roles::Administrator The vendor ID is already defined for the delivery units you assign to the product
Context
To use the SAP HANA Application Lifecycle Manager to assign an existing delivery until to a product, perform the following steps.
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. Choose the PRODUCTS tab. Choose the PRODUCTS tab. Select the product to which you want to assign a delivery unit or delivery units. In the list of products displayed on the left-hand side of the PRODUCTS tab, select the product to which you want to assign a delivery unit. 5. Assign a delivery unit to the selected product.. The Assign Delivery Units dialog box appears, displaying the list of available delivery units. a) Choose Assign to display a list of available delivery units.
588
PUBLIC
b) In the Assign Delivery Units dialog locate the delivery unit you want to assign to the selected product and choose Assign. The assigned delivery unit is immediately removed from the Assign Delivery Units list and added to the ASSIGNED DELIVERY UNITS list for the selected product. c) If necessary, assign further delivery units to the product. 6. Save the changes to the product. Choose Save to add the assigned delivery units to the product.
Results
You have assigned delivery units to this product. Related Information Creating a Product [page 587] Use the SAP HANA Application Lifecycle Manager to create a product and its components. Maintaining Delivery Units [page 44] A delivery unit is a collection of packages that are to be transported together. You assign all the packages belonging to your application to the same delivery unit to ensure that they are transported consistently together within your system landscape. Each delivery unit has a unique identity.
12.6 Maintaining Transport Routes

A transport route defines the connection details required to complete the transport of a delivery unit from a source SAP HANA system to the local target system.
Prerequisites
To perform all the steps required to set up a transport route, you must ensure the following prerequisites are met: You are logged on to the SAP HANA system that is the target of the transport route A technical user must already exist on the destination system you register in this step. The technical user for SAP HANA application lifecycle management transport requires the SAP HANA XS user role sap.hana.xs.lm.roles::Transport. You must have the SAP HANA Application Lifecycle Manager role sap.hana.xs.lm.roles::Administrator You must have the following SAP HANA XS roles: sap.hana.xs.admin.roles::HTTPDestAdministrator sap.hana.xs.admin.roles::RuntimeConfAdministrator
PUBLIC
589
Context
To create and maintain transport routes, you first need to register the systems specified as sources for the transport operations. You also need to be able to maintain the transport destinations, which are the systems specified as source systems and where the delivery units to transport are located. As part of the transport-route maintenance process, you must perform the following tasks:
Procedure
1. Register source systems The source systems for a transport route are the SAP HANA systems where the delivery units you want to transport are located 2. Maintain transport destinations Transport destinations configure the connections details for the systems where the delivery units you want to transport are located.
Note
To maintain a HTTP destination, you must use the SAP HANA XS Administration Tool, which requires the privileges assigned in the user role sap.hana.xs.admin.roles::HTTPDestAdministrator. 3. 4. Add, modify, and remove transport routes. Transport a delivery unit. Execute a transport operation that moves exports a delivery unit from the source SAP HANA system (defined in an HTTP destination) and import it into the local (target) SAP HANA system.
Note
You can trigger a transport with the privileges assigned in the role sap.hana.xs.lm.roles::ExecuteTransport, you do not need to be an SAP HANA Application Lifecycle Manager administrator.
12.6.1
Registering a System for a Transport Route
In the context of a SAP HANA transport route, the system you register is an HTTP destination representing the source system where the object you want to transport is located, for example a delivery unit.
Prerequisites
To register a system for a transport route, you must ensure the following prerequisites are met: You are logged on to the SAP HANA system that is the target of the transport route
590
A technical user must already exist on the source (HTTP destination) system you register in this step. The technical user for SAP HANA application lifecycle management transport requires the SAP HANA XS user role sap.hana.xs.lm.roles::Transport. You must have the privileges granted by the SAP HANA Application Lifecycle Manager role sap.hana.xs.lm.roles::Administrator You must have the privileges granted by the following SAP HANA XS roles: sap.hana.xs.admin.roles::HTTPDestAdministrator sap.hana.xs.admin.roles::RuntimeConfAdministrator
Context
To create and register an HTTP destination as part of the setup of a transport route, you must have the privileges required to create an HTTP destination configuration and, in addition, maintain the logon credentials of an existing technical user on the destination system.
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. Choose the TRANSPORT tab. Choose the SYSTEMS tab. Register a new system. Choose +Register to start the registration process and enter the system details in the Register System dialog. Hostname The name of the source SAP HANA system, where the delivery units you want to transport are located. Port The port number associated with the SAP HANA instance running on the host specified in Hostname.
The Register System dialog box appears. 5. Maintain the HTTP destination. Choose Maintain Destination to display details of the HTTP destination you want to maintain in the SAP HANA XS Administration Tool.
Note
You must have the SAP HANA XS role sap.hana.xs.admin.roles::HTTPDestAdministrator to complete this step. 6. Maintain details of the required technical user. The technical user is required for the execution of the transport on the destination system. a) In the AUTHENTICATION panel of the HTTP DESTINATION screen (in the SAP HANA XS Administration Tool), select the method used to authenticate the user on the destination system, for example, Basic.
PUBLIC
591
b) Enter the name of the technical user. No check is made at this point to ensure the validity of the user name (or the corresponding password) on the destination system. c) Enter a password for the technical user. 7. 8. Choose Save to make the changes to the HTTP destination configuration and close the SAP HANA XS Administration Tool. Choose Finish to create the new HTTP destination.
Note
Before the changes are saved, a check is made to ensure a logon is possible on the destination system with the user name and password provided. If the check fails, see the message pane at the bottom of the browser windows for details.
12.6.2 Maintaining an SAP HANA Transport Destination

In the context of a transport route for SAP HANA application lifecycle management, the destination is the source system where the object you want to transport is located, for example a delivery unit.
Prerequisites
To maintain an HTTP destination as part of the definition of a SAP HANA transport route, you must ensure the following prerequisites are met: You are logged on to the SAP HANA system that is the target of the transport route A technical user must already exist on the destination system you maintain in this step; the technical user is required for the execution of the transport on the destination system. The technical user for SAP HANA application lifecycle management transport requires the SAP HANA XS user role sap.hana.xs.lm.roles::Transport. You have the privileges granted by the SAP HANA Application Lifecycle Manager role sap.hana.xs.lm.roles::Administrator You must have the privileges granted by the following SAP HANA XS roles: sap.hana.xs.admin.roles::HTTPDestAdministrator sap.hana.xs.admin.roles::RuntimeConfAdministrator
Context
To maintain an HTTP destination as part of the setup of a transport route, you must have the privileges required to create an HTTP destination configuration and, in addition, supply logon credentials for an existing technical user on the destination system.
592
Note
To maintain the HTTP destination and the user logon credentials, you also use the SAP HANA XS Administration Tool, for which you need the privileges granted by the role sap.hana.xs.admin.roles::HTTPDestAdministrator. To maintain a destination system as part of a SAP HANA transport route, perform the following steps:
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. 5. Choose the TRANSPORT tab. Choose the SYSTEMS tab. Select a System ID (SID). In the list of SAP HANA SIDs, select the SID whose destination details you want to maintain. Maintain the HTTP destination. Choose Maintain Destination to display details of the HTTP destination you want to maintain in the SAP HANA XS Administration Tool. 6. Maintain details of the required technical user. a) In the AUTHENTICATION panel of the HTTP DESTINATION screen (in the SAP HANA XS Administration Tool), select the method used to authenticate the user on the destination system, for example, Basic. b) Enter the name of the technical user. No check is made at this point to ensure the validity of the user name (or the corresponding password) on the destination system. c) Enter a password for the technical user. 7. 8. Choose Save to make the changes to the HTTP destination configuration and close the SAP HANA XS Administration Tool. Choose Finish to create the new HTTP destination.
Note
Before saving the changes the SAP HANA Application Lifecycle Manager checks if a logon is possible on the destination system with the user name and password provided. Check the message pane at the bottom of the browser window for details.
12.6.3 Adding a Transport Route

A transport route defines the configuration details which specify the source and destination systems for a transport operation.
PUBLIC
593
Prerequisites
To add an SAP HANA transport route, you must ensure the following prerequisites are met: You are logged on to an SAP HANA system You have the privileges granted by the SAP HANA Application Lifecycle Manager role sap.hana.xs.lm.roles::Administrator
Context
A transport route is a configuration object that specifies the source and destination systems for a transport operation as well as additional details about the objects to transport and the type of transport operation to execute, for example, a full or delta update. You can use the transport route to transfer a delivery unit between a source system (defined in an HTTP destination) and a target system, which is the local SAP HANA system that you are logged onto as the application lifecycle administrator. To add a transport route, perform the following steps:
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. Display the ROUTES tab. Choose the TRANSPORT tab and then choose the ROUTES tab. Add a new transport route. Choose +Add and use the Add a Route dialog to enter details of the new SAP HANA transport route: Type Choose between a delta or full delivery-unit transport type. The Delta option updates only changes made to the delivery unit on the source system since the last time the transport route was successfully executed; the Full option updates all delivery unit contents. The Specify on Transport option enables you to decide the transport type at the time you trigger the transport operation. Source System Use the drop-down list to select the System ID (SID) of the SAP HANA system where the delivery unit to transport is located. Delivery Units Select one or more (with the CTRL key) DUs to include in the transport operation.
4.
Save the details of the new transport route. Choose OK to add the new transport route the list of available routes.
Related Information SAP HANA Delivery Units [page 579] In SAP HANA, the delivery unit (DU) is the vehicle that lifecycle management (LCM) uses to ship one or more software components from SAP (or a partner) to a customer .
594
PUBLIC
12.6.4 Modifying a Transport Route

A transport route defines the configuration details which specify the source and destination systems for a transport operation. You can change the details after you create it.
Prerequisites
To modify an SAP HANA transport route, you must ensure the following prerequisites are met: You are logged on to an SAP HANA system You have the privileges granted by the the SAP HANA Application Lifecycle Manager role sap.hana.xs.lm.roles::Administrator
Context
A transport route is a configuration object that specifies the source and destination systems for a transport operation as well as additional details about the objects to transport and the type of transport operation to execute, for example, a full or delta update. You can use the transport route to transfer a delivery unit between a source system (defined in an HTTP destination) and a target system, which is the local SAP HANA system that you are logged onto as the application lifecycle administrator.
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. Display the ROUTES tab. Choose the TRANSPORT tab and then choose the ROUTES tab. Select the transport route you want to modify. Choose Edit and use the Edit a Route dialog to change details of the selected SAP HANA transport route: Type Choose between a delta or full delivery-unit transport type. The Delta option updates only changes made to the delivery unit on the source system since the last time the transport route was successfully executed; the Full option updates all delivery unit contents. The Specify on Transport option enables you to decide the transport type at the time you trigger the transport operation. Delivery Units Select one or more (with the CTRL key) DUs to include in the transport operation.
4.
Save the changes to the transport route. Choose OK to update the transport route.
PUBLIC
595
12.6.5 Removing a Transport Route

A transport route defines the configuration details which specify the source and destination systems for a transport operation. You can add and remove them as required.
Prerequisites
To remove an SAP HANA transport route, you must ensure the following prerequisites are met: You are logged on to an SAP HANA system You have the privileges granted by the SAP HANA Application Lifecycle Manager role sap.hana.xs.lm.roles::Administrator
Note
The removal of a registered system is allowed only if all the routes which use this system are removed before hand.
Context
A transport route is a configuration object that specifies the source and destination systems for a transport operation as well as additional details about the objects to transport and the type of transport operation to execute, for example, a full or delta update. You can use the transport route to transfer a delivery unit between a source system (defined in an HTTP destination) and a target system, which is the local SAP HANA system that you are logged onto as the application lifecycle administrator. You can add, modify, or delete transport routes. To remove a transport route, perform the following steps:
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. Display the ROUTES tab. Choose the TRANSPORT tab and then choose the ROUTES tab. Select the route you want to remove. In the list or routes displayed in the ROUTES tab, click the button immediately to the left of the route you want to remove. 4. Remove the selected route. In the Remove the Selected Route dialog, choose Yes to delete the selected transport route from the list of available routes.
596
Note
You can only remove a registered system, if all the transport routes which use this system are removed before hand.
12.6.6 Transporting a Delivery Unit

A transport operation enables you to move a delivery unit between a source system (defined in an HTTP destination) and a target system, which is the local SAP HANA system that you are logged onto as the application lifecycle administrator.
Prerequisites
To execute a transport operation using a defined SAP HANA transport route, you must ensure the following prerequisites are met: You can log on to the target system defined in the SAP HANA transport route A technical user with valid logon credentials exists on the source (HTTP destination) system specified in the SAP HANA transport route You have the privileges granted by the SAP HANA Application Lifecycle Manager role sap.hana.xs.lm.roles::ExecuteTransport
Context
To transport a delivery unit between a maintained HTTP destination (source) and the local (target) system defined in the selected transport route, perform the following steps:
Procedure
1. Open the SAP HANA Application Lifecycle Manager. The SAP HANA Application Lifecycle Manager is available on the SAP HANA XS Web server at the following URL: http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/lm 2. 3. 4. Choose the TRANSPORT tab. Choose the TRANSPORTS tab. Select the transport operation you want to execute. In the list or transports displayed in the TRANSPORTS tab, click the button immediately to the left of the transport you want to execute. 5. Choose Start Transport
PUBLIC
597
SAP HANA Application Lifecycle Manager displays the details of the transport operation you want to start in the Start the Transport dialog. 6. Choose OK to start the transport operation.
598
13
Using Database Client Interfaces
SAP HANA provides client interfaces for connecting applications so they can retrieve and update data. SAP HANA provides many methods for applications to access its data. For example, a spreadsheet application could use ODBO to consume analytic views and enable users to create pivot tables, or a Web application could use OData interfaces to access the data and display it. SAP HANA can expose data with the following interfaces: Client interfaces, which are available as long as the SAP HANA clients are installed: ODBC ODBO JDBC
Web-based interfaces, which must be defined by the application developer, who determines what data to expose and to whom: OData XMLA Server-Side JavaScript
Related Information SAP HANA Database - Client Installation and Update Guide Defining Web-based Data Access [page 274] 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.
13.1
Connecting via ODBC
SAP HANA provides an ODBC driver for connecting applications to the database.
Context
Note
Make sure to use the 32-bit ODBC driver for 32-bit applications, and the 64-bit driver for 64-bit applications.
Procedure
1. 2. Install the ODBC driver. The driver is installed as part of the SAP HANA client installation. Write code to create a connection to the database. You can use one of the following methods:
SAP HANA Developer Guide Using Database Client Interfaces
PUBLIC
599
Connection String (SQLDriverConnect): Use a connection string in the form: DRIVER={<driver>};UID=<username>;PWD=<password>; SERVERNODE=<server>:<port>; <driver> should be one of the following: HDBODBC: For 64-bit applications HDBODBC32: For 32-bit applications
<port> should be 3<instance number>15, for example, 30015, if the instance is 00. The following is an example of a connection string: DRIVER={HDBODBC};UID=myUser;PWD=myPassword;SERVERNODE=myServer:30015; DSN (SQLConnect): Create a data source by running the odbcad32.exe tool. You can run this via a command line or via the Control Panel /Administrative Tools /Data Sources (ODBC) .
Note
The application is located in the system32 directory. To create a data source for the 32-bit driver on a 64-bit Microsoft Windows machine, run the tool from the SysWOW64 directory. In the DSN tab, choose Add, select the SAP HANA driver, and select Finish. The following appears:
You cannot enter a user name and password here. For the server and port, you can either enter a key created using the SAP HANA user store (which defines the server, port, user name and password), or you can enter a server and port (e.g., myServer:30015). If you enter a server and port, then the application must supply the user name and password when connecting. Related Information SAP HANA Database - Client Installation and Update Guide Using the User Store [page 601]
600
13.1.1
Using the User Store
Context
The SAP HANA user store enables you to store connection information for connecting to an SAP HANA system. Instead of entering connection information each time you make a connection, you store the information, assign it a key, and use this key when making connections. This makes it easier to move between systems (for example, when executing SQL from the command line), and also keeps connection information, including user names and passwords, in a secure place. The SAP HANA user store is part of the client installation.
Procedure
1. In a command line, run the following: hdbuserstore.exe set <key> <server>:<port> <user> <password> The server, port, user name and password are now stored in the user store. The key is a string you use to refer to this set of connection information. 2. Use the key to reference a connection to a particular system. Always precede the key with an @, for example, @mykey. Use the key in the following ways: In the connection string, use the key for the SERVERNODE parameter, and do not include a user name and password, for example: SERVERNODE={@mykey};DRIVER={hdbodbc}; In creating a DSN, enter the key (for example, @mykey) for the server and port. In testing your connection (by running odbcreg -t hdbodbc), use the key (for example, @mykey) for the server and port. If the connection is successful, you get something like this:
PUBLIC
601
The response includes a sample connection string using the key. Related Information Testing the ODBC Installation [page 602] You can test the installation of the ODBC driver and your ability to connect by using the odbcreg tool, which is part of the ODBC installation.
13.1.2
Testing the ODBC Installation
You can test the installation of the ODBC driver and your ability to connect by using the odbcreg tool, which is part of the ODBC installation.
Procedure
1. 2. Open a command window. Start the odbcreg tool by enter a command in the form: odbcreg -t hdbcodbc (for 64-bit driver) or odbcreg32 -t hdbcodbc32 (for 32-bit driver). If the driver is installed properly, you should get the ODBC login screen.
Note
You can also run the command odbcreg -g or odbcreg32 -g to get a list of installed drivers. The SAP HANA driver is called HDBODBC.
602
3.
Test your ability to connect by entering connection information (system, port, user name and password) and select OK. The tool closes and the results of the test are printed in the command window.
Results
You can also run odbcreg -g to get a list of installed ODBC drivers, and check to make sure that the SAP HANA driver (either HDBODBC or HDBODBC32) is installed.
13.2 Connecting via JDBC

SAP HANA provides a JDBC driver for connecting Java applications to the database.
Procedure
1. Install the JDBC driver. The driver (ngdbc.jar) is installed as part of the SAP HANA client installation and is located at: 2. 3. C:\Program Files\sap\hdbclient\ on Microsoft Windows platforms /usr/sap/hdbclient/ on Linux and UNIX platforms
Add ngdbc.jar to your classpath. If you are on a version of Java earlier than Java 6, load the JDBC driver class, which is called com.sap.db.jdbc.Driver.
PUBLIC
603
4.
Write Java code to create a connection to the database and execute SQL commands. Use a connection string in the form of jdbc:sap://<server>:<port>[/?<options>]. For example: jdbc:sap://myServer:30015/?autocommit=false The port should be 3<instance number>15, for example, 30015, if the instance is 00. You can specify one or more failover servers by adding additional hosts, as in the following example: jdbc:sap://myServer:30015,failover1:30015,failover2:30015/?autocommit=false
Example
The following is an example of connecting to an SAP HANA server called myhdb, which was installed as instance 07, with user name myname and password mysecret. Make sure to change these for your system, and add the JDBC driver (ngdbc.jar) to your classpath. import java.sql.*; public class jdemo { public static void main(String[] argv) { Connection connection = null; try { connection = DriverManager.getConnection( "jdbc:sap://myhdb:30715/? autocommit=false",myname,mysecret); } catch (SQLException e) { System.err.println("Connection Failed. User/Passwd Error?"); return; } if (connection != null) { try { System.out.println("Connection to HANA successful!"); Statement stmt = connection.createStatement(); ResultSet resultSet = stmt.executeQuery("Select 'hello world' from dummy"); resultSet.next(); String hello = resultSet.getString(1); System.out.println(hello); } catch (SQLException e) { System.err.println("Query failed!"); } } } } Related Information SAP HANA Database - Client Installation and Update Guide
13.2.1
Tracing JDBC Connections
You can activate the JDBC trace to find errors while your application is connected to a database via JDBC.
604
PUBLIC
Prerequisites
You must be logged on as the operating system user who started (or will start) the JDBC application.
Note
You always activate the JDBC trace for all JDBC applications that the current operating system user has started. Configuration changes have an effect on all JDBC applications that the current operating system user has started.
Context
When the JDBC trace is activated, the JDBC driver logs on the client the following information: JDBC API calls called by the JDBC application JDBC API call parameters Executed SQL statements and their results
The location of the trace file is determined by the trace options.
13.2.1.1
Tracing via GUI
You can start tracing by running the tracing configuration tool that includes a graphical user interface (GUI).
Context
Tracing via the GUI enables you to start and configure tracing without stopping and restarting your application that is connected via JDBC.
Procedure
1. 2. 3. 4. On the client, enter the following command on the command line: java -jar <installation_path> \ngdbc.jar. Select Trace enabled. Select and modify the tracing options. Select OK.
PUBLIC
605
13.2.1.2
Tracing via Command Line
You can start tracing by running the tracing configuration tool and sending commands via the command line.
Context
Tracing via the command line enables you to start and configure tracing without stopping and restarting your application that is connected via JDBC.
Procedure
1. 2. 3. Display the current configuration by running the command java -jar <installation_path> \ngdbc.jar. Select trace options by running the command java -jar <installation_path>\ngdbc.jar <option>. Start tracing by running the command java -jar <installation_path>\ngdbc.jar TRACE ON.
Related Information Trace Options
13.2.1.3
Tracing via Connection String
You can start tracing by adding an option in the connection string when creating a JDBC connection.
Context
Tracing via the connection string requires you to stop and restart your application that is making the JDBC connection. Also, with the connection string, you cannot turn off tracing or set any options except setting the trace filename.
Procedure
Add the trace option to the connection when creating a JDBC connection. Here is an example connection string that starts tracing: jdbc:sap://localhost:30015/?autocommit=false&trace=traceFile.txt
606
Next Steps
The location of the trace file is determined by the trace options.
13.2.1.4
Trace Options
Options when enabling JDBC tracing. The first column shows the field name in the GUI-based tracing configuration tool, and the second column shows the command to enter when using the command-line tool. Table 30: Trace Options Option Trace enabled Trace file folder Command Line Option TRACE ON | OFF No command-line option. The folder can be specified with the FILENAME option. Description Starts and stops tracing Sets the directory where the system writes the trace files. When no folder is specified, the files are saved in the working directory of the application. Trace file name TRACE FILENAME [<path>]<file_name> Sets the name of the trace file. The system assigns each trace file an additional unique ID, so the file name is: <file_name>_<id>.prt The default file name is jdbctrace. Limit file size TRACE SIZE <size> [KB|MB|GB] To remove the size limit, use the following option: TRACE SIZE UNLIMITED Stop on error TRACE STOP ON ERROR <error_code> To no longer stop on the specified error, use the following option: TRACE STOP ON ERROR OFF Stops writing the JDBC trace when the specified error code occurs. Limits the size of each trace file.
13.2.2 Valid Java-to-SQL Conversions

SAP HANA allows each Java object to be converted to specific SQL types using the JDBC method PreparedStatement.setObject or RowSet.setObject. Some conversions may fail at runtime if the value passed is invalid.
PUBLIC
607
13.3 Connecting via ODBO

SAP HANA provides an ODBO driver for connecting applications to the database and executing MDX statements.
Procedure
1. 2. 3. Install the ODBO driver. The driver is installed as part of the SAP HANA client installation. Specify in your client the provider name: SAPNewDBMDXProvider Create a connection string in the form of: <host of HANA>;User ID=<your user>;Password=<your password;SFC_USE_ROWCACHE=true;SFC_INSTANCE_NUM=<instance number> For example: localhost;User ID=system;Password=mypassword;SFC_USE_ROWCACHE=true;SFC_INSTANCE_NUM=00 If the server instance is 00, then you can omit the SFC_INSTANCE_NUM parameter. SFC_USE_ROWCACHE is optional. It enables backward and forward navigation through rowsets. Related Information SAP HANA Database - Client Installation and Update Guide
608
13.3.1
Connecting with Microsoft Excel
You can use Microsoft Excel and its PivotTables as a practical way to access and analyze SAP HANA data, connecting with ODBO.
Context
SAP HANA supports Microsoft Excel 2007 and 2010.
Procedure
1. 2. Start the Data Connection Wizard, and select Other/Advanced as the type of data source. Select the SAP HANA MDX Provider as the OLE DB Provider.
3.
In the Connection tab of the Data Link Properties window, enter the SAP HANA server name, instance number, user name and password.
PUBLIC
609
4.
Select the cube from which you want to import data. SAP HANA analytic and calculation views are exposed as cubes.
610
Results
SAP HANA supports the following Microsoft Excel features: Drilling down Selection filtering Top/bottom filters Report filters Member properties Refresh cube Convert PivotTable into formulas Server formatting Pre-modeled calculated members Show/hide fields Enhanced value and label filters Insert slicer Text search in report filter PivotTable filter Creation of named sets
PUBLIC
611
13.3.2 Multidimensional Expressions (MDX)

Multidimensional Expressions (MDX) is a language you can use to query multidimensional data 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 that are designed to enable faster and more efficient access to multidimensional data, for example, to serve specific SAP HANA application requirements and to optimize the resultset 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 key attributes of attribute views are linked to private attributes in an analytical 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 levelbased 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 [MINI_C1_VAR] Where [Measures].[M2_1_M3_CONV] SAP VARIABLES [VAR_VAT] including 10, [VAR_K2] including 112, [VAR_TARGET_CURRENCY] including 'EUR',
13.3.3 MDX Functions

MDX in SAP HANA supports a variety of standard MDX functions.
612
PUBLIC
Table 31: Supported MDX Functions Function Aggregate Ancestor Ancestors Ascendants Avg BottomCount Children ClosingPeriod Count Cousin Crossjoin CurrentMember DefaultMember Descendants Dimension Dimensions Distinct DistinctCount DrillDownLevel DrillDownLevelBottom DrillDownLevelTop DrillDownMember DrillDownMemberBottom DrillDownMemberTop Description Returns a calculated value using the appropriate aggregate function, based on the aggregation type of the member. Returns the ancestor of a member at a specified level or at a specific distance away in the hierarchy. Returns a set of all ancestors of a member at a specified level or at a specific distance away in the hierarchy. Returns the set of the ascendants of the member. Returns the average value of a numeric expression evaluated over a set. Returns a specified number of items from the bottom of a set, optionally sorting the set first. Returns the children of a member. Returns the last sibling among the descendants of a member at a specified level. Counts the number of members in the tuple. Returns the child member with the same relative position under a parent member as the specified child member. Returns the cross product of two sets. Returns the current member along a hierarchy. Returns the default member of a hierarchy. Returns the set of descendants of a member at a specified level or at a specific distance away in the hierarchy. Returns the hierarchy that contains a specified member or level. Returns a hierarchy specified by a numeric or string expression. Returns a set, removing duplicate tuples from a specified set. Returns the number of distinct tuples in a set. Drills down the members of a set one level below the lowest level represented in the set, or to one level below an optional level of a member represented in the set. Drills down the members of a specified count of bottom members of a set, at a specified level, to one level below. Drills down a specified count of top members of a set, at a specified level, to one level below. Drills down the members in a specified set that are present in a second specified set. Drills down the members in a specified set that are present in a second specified set, limiting the result set to a specified number of bottommost members. Drills down the members in a specified set that are present in a second specified set, limiting the result set to a specified number of topmost members.
PUBLIC
613
Function DrillUpLevel DrillUpmember Except Filter FirstChild FirstSibling Generate
Description Drills up the members of a set that are below a specified level. Drills up the members in a specified set that are present in a second specified set. Finds the difference between two sets, optionally retaining duplicates. Returns the set resulting from filtering a set based on a search condition. Returns the first child of a specified member. Returns the first child of the parent of a specified member. Applies a set to each member of another set, and then joins the resulting sets by union. Alternatively, this function returns a concatenated string created by evaluating a string expression over a set. Returns the first specified number of elements in a set. Orders the members of a specified set in a hierarchy in natural or, optionally, postnatural order.
Head Hierarchize Hierarchy Instr Intersect IsAncestor IsGeneration IsLeaf IsSibling Item IIF Lag LastChild LastPeriods LastSibling Lead Leaves
The InStr function finds the starting location of a substring within a specified string. Returns the intersection of two sets, optionally retaining duplicates. Returns true if the first member specified is an ancestor of the second member specified, else returns false. Returns true if the member specified is a leaf, else returns false. Returns true if the first member specified is an ancestor of the second member specified, else returns false. Returns true if the first member specified is an sibling of the second member specified, else returns false. If an integer is specified, the Item function returns the tuple that is in the zerobased position specified by Index. Returns one of values determined by a logical test. Returns the member that is a specified number of positions prior to a specified member along the dimension of the member. Returns the last child of a specified member. Returns a set of members prior to and including a specified member. Returns the last child of the parent of a specified member. Returns the member that is a specified number of positions following a specified member along the dimension of the member. If a dimension name is specified, returns a set that contains the leaf members of the key attribute for the specified dimension.If a dimension name is not specified, the function returns a set that contains the leaf members of the entire cube.
614
Function Left Level Levels Max Member_caption Members MembersAscendantsDesc endants Mid Min MTD Name NextMember NOT OpeningPeriod OR Ordinal ParallelPeriod Parent PeriodsToDate PrevMember Properties QTD Range
Description The Left function returns a string of a specified number of characters from the left side (beginning) of a specified string. Returns the level of a member. Returns the level whose zero-based position in a dimension is specified by a numeric expression. Returns the maximum value of a numeric expression evaluated over a set. Returns the caption of a member Returns the set of all members in a specified hierarchy. Returns the set of specified members in a given hierarchy. The Mid function returns a substring of a string argument. Returns the minimum value of a numeric expression evaluated over a set Returns a set of members from the Month level in a Time dimension starting with the first period and ending with a specified member. Returns the name of a specified hierarchy or member. Returns the next member in the level that contains a specified member. Performs a logical negation on a numeric expression. Returns the first sibling among the descendants of a specified level, optionally at a specified member. Performs a logical disjunction on two numeric expressions. Returns the zero-based ordinal value associated with a specified level. Returns a member from a prior period in the same relative position as a specified member. Returns the parent of a specified member. Returns a set of members (periods) from a specified level starting with the first member and ending with a specified member. Returns the previous member in the level that contains a specified member. Returns a string containing the value of the specified member property. Returns a set of members from the Quarter level in a Time dimension starting with the first period and ending with a specified member. Performs a set operation that returns a naturally ordered set, with the two specified members as endpoints, and all members between the two specified members included as members of the set The Right function returns a string of a specified number of characters from the right side (end) of a specified string. Returns the set of siblings of a specified member, including the member itself.
Right Siblings
PUBLIC
615
Function StrToMember StrToSet StrToTuple StrToValue Subset Sum Tail TopCount Union UniqueName WTD YTD
Description Returns a member from a string expression in MDX format. Constructs a set from a specified string expression in MDX format. Constructs a tuple from a specified string expression in MDX format. Returns a value from a string expression Returns a subset of tuples from a specified set. Returns the sum of a numeric expression evaluated over a specified set. Returns the last specified number of elements in a set. Returns a specified number of items from the topmost members of a specified set, optionally ordering the set first. Performs a set operation that returns a union of two sets, removing duplicate members. Returns the unique name of a specified hierarchy. Returns a set of members from the Week level in a Time dimension starting with the first period and ending with a specified member. Returns a set of members from the Year level in a Time dimension starting with the first period and ending with a specified member.
13.3.4 MDX Extensions

SAP HANA supports several extensions to the MDX language, for example, additional predefined functions and support for variables.
13.3.4.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 ( [MDX_TEST_10_DISTRIBUTION_CHANNEL].[MDX_TEST_10_DISTRIBUTION_CHANNEL].[All].
616
[(all)], 1, SELF_AND_BEFORE ) DIMENSION PROPERTIES SIBLING_ORDINAL ON ROWS FROM MDX_TEST_10_ITELO_SALES_DATA
13.3.4.2 MembersAscendantsDescendants Function

SAP HANA includes a new function called MembersAscendantsDescendants 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([JUICE_TIME].[TimeHier].[QUARTER].[3]: [JUICE_TIME].[TimeHier].[QUARTER].[4], MEMBERS_AND_ASCENDANTS_AND_DESCENDANTS )) } ON ROWS FROM [JUICE]
Example
SELECT { [Measures].[SALES] } ON COLUMNS, NON EMPTY { Hierarchize( MembersAscendantsDescendants([JUICE_TIME].[TimeHier].[QUARTER].[3]: [JUICE_TIME].[TimeHier].[QUARTER].[4], ONLY_ASCENDANTS )) } ON ROWS FROM [JUICE]
PUBLIC
617
13.3.4.3 Variables
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 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 specifies a single value for variables VAR_KAT, VAR_K2, and VAR_TARGET_CURRENCY. SELECT FROM [MINI_C1_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 [MINI_C1_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
618
PUBLIC
BIMC_VARIABLE_ASSIGNMENT BIMC_VARIABLE_VALUE BIMC_VARIABLE_ODBO (virtual table)
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.
PUBLIC
619
www.sap.com/contactsap
No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group 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 AG in Germany and other countries. Please see http://www.sap.com/corporate-en/legal/copyright/ index.epx for additional trademark information and notices.

SAP HANA Developer Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SAP HANA Developer Guide

Uploaded by

Copyright:

Available Formats

PUBLIC

SAP HANA Platform SPS 06 Document Version: 1.2 - 03-09-2013

SAP HANA Developer Guide

Maintaining Repository Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 3.4.1 3.4.2 3.4.3 3.4.4

Creating the Application Descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

PUBLIC 2013 SAP AG or an SAP affiliate company. All rights reserved.

SAP HANA Developer Guide Table of Contents

Maintaining Application Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82

Maintaining HTTP Destinations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

4.3 4.4 4.5 4.6

Data Persistence Objects in Core Data Services (CDS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 4.7.1

SAP HANA Developer Guide Table of Contents

SAP HANA Developer Guide Table of Contents

5.6 6 6.1 6.2

6.3 6.4 6.5 6.6

SAP HANA Developer Guide Table of Contents

7.2.8 7.2.9 8 8.1 8.2

Server-Side JavaScript Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 8.3.1 8.3.2

8.4 8.5 8.6 8.7

Debugging Server-Side JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 8.8.1 8.8.2 8.8.3 8.8.4 8.8.5

Using UI Integration Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 9.3.1 9.3.2 9.3.3 9.3.4

PUBLIC 2013 SAP AG or an SAP affiliate company. All rights reserved.

SAP HANA Developer Guide Table of Contents

Building SQL Search Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414 10.2.1 10.2.2 10.2.3 10.2.4

11 11.1 11.2 11.3

Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 11.4.1 11.4.2 11.4.3 11.4.4 11.4.5 11.4.6

11.5 12 12.1 12.2

Maintaining Repository Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 12.3.1 12.3.2 12.3.3

SAP HANA Developer Guide Table of Contents

Maintaining Delivery Units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

Maintaining Products. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586

Maintaining Transport Routes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .589

Connecting via JDBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 13.2.1 13.2.2

Connecting via ODBO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 13.3.1 13.3.2 13.3.3 13.3.4

PUBLIC 2013 SAP AG or an SAP affiliate company. All rights reserved.

SAP HANA Developer Guide Table of Contents

Introduction to SAP HANA Development

SAP HANA Developer Guide Introduction to SAP HANA Development

SAP HANA Architecture

SAP HANA In-Memory Database

Columnar Data Storage

PUBLIC 2013 SAP AG or an SAP affiliate company. All rights reserved.

SAP HANA Developer Guide Introduction to SAP HANA Development

SAP HANA Developer Guide Introduction to SAP HANA Development

SAP HANA Database Architecture

SAP HANA Developer Guide Introduction to SAP HANA Development

SAP HANA Extended Application Services

SAP HANA Developer Guide Introduction to SAP HANA Development

PUBLIC 2013 SAP AG or an SAP affiliate company. All rights reserved.

SAP HANA Developer Guide Introduction to SAP HANA Development

SAP HANA Developer Guide Introduction to SAP HANA Development

SAP HANA-Based Applications

PUBLIC 2013 SAP AG or an SAP affiliate company. All rights reserved.

SAP HANA Developer Guide Introduction to SAP HANA Development

Scenario: Developing Native SAP HANA Applications

SAP HANA Developer Guide Introduction to SAP HANA Development

Scenario: Using Database Client Interfaces

SAP HANA Developer Guide Introduction to SAP HANA Development

More Information Developing Procedures [page 254]

SAP HANA Developer Guide Introduction to SAP HANA Development

PUBLIC 2013 SAP AG or an SAP affiliate company. All rights reserved.

SAP HANA Developer Guide Getting Started

SAP HANA Studio

The SAP HANA Development Perspective